Cart integration and attribution

Antla generations and Shopify carts are separate operations. Use the Shopify Storefront Cart API to create a cart or add merchandise; there is no Headless API cart endpoint.

SDK cart ownership

Pass the current shopper’s complete Shopify Storefront Cart GID through cart-id. Preserve its full value including any ?key= suffix. Do not use a theme AJAX cart token.

If there is no cart-id, the SDK creates a cart when the result action is used. It sets the returned cart ID on the element and stores it in local browser storage. It does not automatically create or update your framework’s server-side cart session.

A cart page must read the same cart. Otherwise the SDK can successfully add a product while your storefront displays an empty or different cart.

Observe a new cart ID

const block = document.querySelector("antla-block");
let previousCartId = block.getAttribute("cart-id");

const observer = new MutationObserver(() => {
  const cartId = block.getAttribute("cart-id");
  if (!cartId || cartId === previousCartId) return;
  previousCartId = cartId;
  // Persist this ID in YOUR storefront's shopper session,
  // using your existing authenticated/cart-session mechanism.
  syncCurrentShopperCart(cartId);
});

observer.observe(block, {
  attributes: true,
  attributeFilter: ["cart-id"],
});

// On unmount:
// observer.disconnect();

syncCurrentShopperCart is your own integration function, not an Antla SDK method. Watching the ID does not detect every quantity/line change to an existing cart. Revalidate your cart through your application’s normal lifecycle, or use your own API-driven result/cart UI.

Direct Shopify mutation

Get public Storefront credentials through GET /context if Headless SDK is connected, or use your existing correctly configured Shopify client. API-only shops cannot call /context. Send Shopify GraphQL requests to the Storefront apiUrl, using X-Shopify-Storefront-Access-Token.

mutation AddTryOnProduct($cartId: ID!, $lines: [CartLineInput!]!) {
  cartLinesAdd(cartId: $cartId, lines: $lines) {
    cart { id checkoutUrl }
    userErrors { field message }
  }
}

{
  "cartId": "gid://shopify/Cart/YOUR_CART_ID?key=YOUR_CART_KEY",
  "lines": [{
    "merchandiseId": "gid://shopify/ProductVariant/456",
    "quantity": 1,
    "attributes": [{
      "key": "__antla-funnel_id",
      "value": "123"
    }]
  }]
}

Use the variant GID as merchandiseId. Parse top-level GraphQL errors and mutation userErrors, even for HTTP 200. Handle expired carts explicitly rather than blindly repeating the add-line request.

For creating a cart, use cartCreate(input: CartInput!). See Shopify’s cart guide.

Attribution used by the current SDK

Location	Attribute	Format
Added cart line	__antla-funnel_id	Funnel ID converted to a string
Cart attributes	__antla_tryon_details	JSON string of numeric product/variant/funnel entries

[
  { "productId": 123, "variantId": 456, "funnelId": 123 }
]

The SDK records this after a final generation. If a cart already exists, it attempts cartAttributesUpdate; otherwise it includes stored details on cart creation. It tracks the variant that generated the image separately from the currently selected variant.

If you set these attributes yourself, merge them with the cart your app already has. The SDK keeps a short history in the browser and clears it when the cart ID changes. That history is not an analytics API.

These attributes match current SDK behavior. They do not guarantee a discount, a reporting event, a conversion attribution policy or compatibility with every custom checkout.

Result-action behavior

The SDK adds one unit of the selected available variant, then follows merchant settings:

• Cart: navigate to cart-url (default /cart).
• Checkout: navigate to Shopify’s returned checkoutUrl.
• Close: close the modal after adding the line.

If you want to show an image without any add-to-cart action, or route to a native checkout under your own control, build the result UI with the Headless API.

Session safety

Cart IDs are shopper-specific and contain a secret component. Never place real cart IDs in shared docs, analytics, support screenshots or globally cached HTML. Follow Shopify’s guidance on handling cart IDs and keep them within the intended shopper’s session.