Last updated

setCartToken()

Adopts an externally-created cart into the storefront SDK. Use this when an external system (e.g., a companion app or backend service) creates a cart via the API with metadata and needs to hand it off to the storefront so the user can browse, add items, and check out — with metadata persisting throughout the session.

Integration Methods

There are two ways to adopt an external cart token:

Redirect users to your storefront with a cart_token query parameter. The SDK automatically detects the parameter on initialization, validates the cart, saves it, and cleans the token from the URL.

https://shop.example.com/?cart_token=TOKEN

No JavaScript is needed — the SDK handles everything:

  1. Detects ?cart_token= on page load
  2. Validates the cart by fetching it from the API
  3. Saves the cart to localStorage (preserving attribution, recurring items, and payer metadata)
  4. Subscribes to Pusher realtime updates
  5. Removes cart_token from the URL via history.replaceState to prevent leaking in referrer headers, bookmarks, and analytics

If validation fails (e.g., expired or invalid token), the parameter remains in the URL so the user can retry on refresh. An error is logged to the console.

2. Programmatic API

For integrations that need JavaScript-level control:

const cart = await window.FairShareSDK.setCartToken("TOKEN");

Signature

const cart = await window.FairShareSDK.setCartToken(token);

Parameters

ParameterTypeRequiredDescription
tokenstringYesThe cart token from an externally-created cart

Returns

Promise<Cart> — Resolves to the validated Cart object from the API.

Behavior

  1. Validates that the SDK is initialized and the token is non-empty
  2. Fetches the cart from the API using the provided token
  3. Saves the validated cart to localStorage (preserving attribution, recurring items, and payer metadata)
  4. Subscribes to Pusher realtime updates for the cart
  5. Dispatches SET_CART_TOKEN and UPDATE_CART_ITEM events so cart widgets react immediately
  6. Prevents the SDK's init-time getCart() from overwriting the adopted cart

Examples

Redirect from External App

// External app (e.g., Dash) creates a cart via the API:
// POST /api/carts → { cart_token: "abc123" }

// Then redirects the user to the storefront:
// https://shop.example.com/?cart_token=abc123

// The SDK handles adoption automatically on page load.

Programmatic Adoption

// After creating a cart via your backend
const cart = await window.FairShareSDK.setCartToken("abc123");

console.log("Adopted cart:", cart.cart_token);
console.log("Items:", cart.items.length);

Listening for Adoption Events

window.addEventListener("SET_CART_TOKEN", (e) => {
  console.log("External cart adopted:", e.detail.cart);
});

Error Handling

ErrorCause
"Cart token cannot be empty"An empty string was passed
"Fluid SDK not initialized"initializeFluid() has not been called
"Cart not found for the provided token"The API returned no cart for the token
"Cart has been completed or is no longer available"The cart was already checked out (HTTP 410)
"Another setCartToken operation is already in progress"Concurrent calls are not allowed
try {
  const cart = await window.FairShareSDK.setCartToken("abc123");
} catch (error) {
  console.error("Failed to adopt cart:", error.message);
}

Notes

  • Requires FairShareSDK.initializeFluid() to have been called first
  • Only one setCartToken call can run at a time — concurrent calls throw an error
  • If adoption fails, any existing cart in localStorage is preserved
  • The URL parameter method is best for redirect-based flows where the external system creates the cart and sends the user to the storefront
  • The programmatic method is best for single-page apps or cases where you need to handle the result in JavaScript