{"templateId":"markdown","sharedDataIds":{},"props":{"codeGuideFiles":[],"dynamicMarkdocComponents":[],"metadata":{"type":"markdown"},"seo":{"title":"setCartToken()","description":"Fluid is the open e-commerce platform built for direct-sales."},"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"setcarttoken"},"children":["setCartToken()"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-methods"},"children":["Integration Methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways to adopt an external cart token:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1.-url-parameter-recommended-for-redirects"},"children":["1. URL Parameter (Recommended for Redirects)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redirect users to your storefront with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cart_token"]}," query parameter. The SDK automatically detects the parameter on initialization, validates the cart, saves it, and cleans the token from the URL."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://shop.example.com/?cart_token=TOKEN\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No JavaScript is needed — the SDK handles everything:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Detects ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?cart_token="]}," on page load"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validates the cart by fetching it from the API"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Saves the cart to localStorage (preserving attribution, recurring items, and payer metadata)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subscribes to Pusher realtime updates"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Removes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cart_token"]}," from the URL via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["history.replaceState"]}," to prevent leaking in referrer headers, bookmarks, and analytics"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2.-programmatic-api"},"children":["2. Programmatic API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For integrations that need JavaScript-level control:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const cart = await window.FairShareSDK.setCartToken(\"TOKEN\");\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"signature"},"children":["Signature"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const cart = await window.FairShareSDK.setCartToken(token);\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"parameters"},"children":["Parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The cart token from an externally-created cart"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns"},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Promise<Cart>"]}," — Resolves to the validated Cart object from the API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"behavior"},"children":["Behavior"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validates that the SDK is initialized and the token is non-empty"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fetches the cart from the API using the provided token"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Saves the validated cart to localStorage (preserving attribution, recurring items, and payer metadata)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subscribes to Pusher realtime updates for the cart"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Dispatches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SET_CART_TOKEN"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE_CART_ITEM"]}," events so cart widgets react immediately"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prevents the SDK's init-time ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getCart()"]}," from overwriting the adopted cart"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples"},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redirect-from-external-app"},"children":["Redirect from External App"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"// External app (e.g., Dash) creates a cart via the API:\n// POST /api/carts → { cart_token: \"abc123\" }\n\n// Then redirects the user to the storefront:\n// https://shop.example.com/?cart_token=abc123\n\n// The SDK handles adoption automatically on page load.\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"programmatic-adoption"},"children":["Programmatic Adoption"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// After creating a cart via your backend\nconst cart = await window.FairShareSDK.setCartToken(\"abc123\");\n\nconsole.log(\"Adopted cart:\", cart.cart_token);\nconsole.log(\"Items:\", cart.items.length);\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"listening-for-adoption-events"},"children":["Listening for Adoption Events"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"window.addEventListener(\"SET_CART_TOKEN\", (e) => {\n  console.log(\"External cart adopted:\", e.detail.cart);\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling"},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Cart token cannot be empty\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An empty string was passed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Fluid SDK not initialized\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initializeFluid()"]}," has not been called"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Cart not found for the provided token\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The API returned no cart for the token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Cart has been completed or is no longer available\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The cart was already checked out (HTTP 410)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Another setCartToken operation is already in progress\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Concurrent calls are not allowed"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"try {\n  const cart = await window.FairShareSDK.setCartToken(\"abc123\");\n} catch (error) {\n  console.error(\"Failed to adopt cart:\", error.message);\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notes"},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FairShareSDK.initializeFluid()"]}," to have been called first"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setCartToken"]}," call can run at a time — concurrent calls throw an error"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If adoption fails, any existing cart in localStorage is preserved"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The URL parameter method is best for redirect-based flows where the external system creates the cart and sends the user to the storefront"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The programmatic method is best for single-page apps or cases where you need to handle the result in JavaScript"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related"},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/getcart"},"children":["getCart"]}," — Fetch cart from API"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/createcart"},"children":["createCart"]}," — Create a new empty cart"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/refreshcart"},"children":["refreshCart"]}," — Fetch cart from API and update all widgets"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/getlocalcart"},"children":["getLocalCart"]}," — Get cart from cache without API call"]}]}]},"headings":[{"value":"setCartToken()","id":"setcarttoken","depth":1},{"value":"Integration Methods","id":"integration-methods","depth":2},{"value":"1. URL Parameter (Recommended for Redirects)","id":"1.-url-parameter-recommended-for-redirects","depth":3},{"value":"2. Programmatic API","id":"2.-programmatic-api","depth":3},{"value":"Signature","id":"signature","depth":2},{"value":"Parameters","id":"parameters","depth":2},{"value":"Returns","id":"returns","depth":2},{"value":"Behavior","id":"behavior","depth":2},{"value":"Examples","id":"examples","depth":2},{"value":"Redirect from External App","id":"redirect-from-external-app","depth":3},{"value":"Programmatic Adoption","id":"programmatic-adoption","depth":3},{"value":"Listening for Adoption Events","id":"listening-for-adoption-events","depth":3},{"value":"Error Handling","id":"error-handling","depth":2},{"value":"Notes","id":"notes","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"seo":{"title":"setCartToken()"}},"lastModified":"2026-03-16T20:44:24.000Z"},"slug":"/docs/sdk/fairshare/cart/setcarttoken","userData":{"isAuthenticated":false,"teams":["anonymous"]}}