Supplying the cart token

The cart token is the ID of the shopper's current cart. Fast Simon uses it to tie an order back to the searches and clicks that led to it, so it has to reach Fast Simon twice with the same value: on the storefront's events, and on the order your server sends.

The SDK tries to detect the token by itself: on Shopify and BigCommerce it reads the platform's cart, and on any platform it reuses a token it already saved in the browser. A custom storefront gives it nothing to read, so every event goes out with an empty token and revenue can't be attributed to search queries. On a headless storefront, detection can find a different cart from the one that reaches checkout. In both cases, give the SDK your cart ID with cartTokenProvider.

Using cartTokenProvider

Set a function on __fast_options that returns your current cart ID as a string:

<script>
    var __fast_options = __fast_options || {};
    __fast_options.cartTokenProvider = function () {
        return window.myStore.getCartId(); // your own cart ID, or undefined if there is no cart yet
    };
</script>
<script src="https://assets.fastsimon.com/sdk/latest/fast_simon_sdk.js" async></script>

Set it before the SDK script so that the first request of the page carries the token too. If you assign it later, only the requests made after that point carry it.

If you install the SDK from npm, assign it to window.__fast_options before you call FastSimonSDK.initialization.

Using the same value on the order

Send the same string as cart_token when your server reports the order. A cart ID that differs in any way, even in case, won't match. The order request is described in Step 4 of the Custom Platform Integration Guide in the Fast Simon dashboard's Help Center.

How the provider behaves

It's called on every event, not once at initialization. A cart created on the shopper's first add to cart is picked up by the next event, with no need to initialize again.

While it's configured, it's the only source of the token. The SDK won't fall back to its own detection or to setCartToken, so if it returns nothing, the event goes out with no token. Return undefined or null when there's no cart yet.

A bad provider doesn't break the page. If it throws, returns something other than a string, or returns an empty string, the event goes out with no token. If it isn't a function, the SDK ignores it and uses its own detection. Each case logs one warning to the browser console per page load. Numeric cart IDs have to be converted first: return String(cartId).

Other ways to set the token

Option	Use it when	Limits
cartToken in FastSimonSDK.initialization	The cart ID is known at initialization and doesn't change on the page	It's a fixed value, so a cart created later isn't picked up
FastSimonSDK.setCartToken(id)	Your code already runs on every cart change, for example in a native app host	It has no effect while cartTokenProvider is configured, and it applies to the SDK only
cartToken in the AddToCartPerformed event's data	You only have the cart ID at the moment of the add to cart	It applies to that one event only

For a browser storefront, prefer cartTokenProvider. Other Fast Simon scripts on the page, such as recommendation widgets, read it as well, so all of them report the same cart.