Llama Cart for developers

Llama Cart is the smart cart drawer that replaces your theme's default cart drawer. This page explains how it loads on the storefront, how it keeps itself in sync with cart changes by overriding fetch and XMLHttpRequest, and how to open it or run it in preview mode using query parameters and events.

If you only need the events the cart emits, jump straight to Cart events.

How Llama Cart loads

Llama Cart ships as part of the theme app extension. When the app embed is active, a loader script runs on every storefront page and decides whether to render the smart cart.

The cart renders only when both of these are true:

• The block's version setting is not disabled (the originalLlamaCartVersion value).
• Llama Cart is enabled — either globally (globalSettings.llamaCartEnabled) or through an active preview session.

When those conditions are met, the loader does two things:

cart-drawer,
cart-notification,
cart-drawer-component > dialog {
  display: none !important;
}

The rendered drawer lives in a container with the id lcu-llama-cart and is mounted onto document.body. The embed data the bundle reads is a JSON payload in the #upsell-app-embed-data element, which includes the cart, the customer, drawer settings, active campaigns, and translatable content.

Staying in sync: the fetch override

The host theme, its sections, and other apps all modify the cart by calling the Shopify Cart AJAX API (/cart/add, /cart/change, /cart/update, and so on). Llama Cart needs to know whenever that happens so its contents stay accurate. It does this by wrapping the browser's native window.fetch and XMLHttpRequest.prototype.open.

What gets intercepted

The override stores references to the native functions first, then installs its wrappers. Only cart-modifying requests are intercepted — everything else passes straight through to the native implementation untouched. A request is treated as a cart modification when:

• The URL contains /cart, and
• The request method is POST.

For any request that isn't a cart POST, the wrapper calls the native fetch directly and returns. This keeps the override invisible to the rest of the page.

What happens on a cart change

For an intercepted cart POST, the wrapper awaits the real request, clones the response, and — if the response is ok — parses the cart JSON. It then:

The cart re-fetch uses the native fetch with Cache-Control: no-cache against {root}cart.js, where {root} comes from window.Shopify.routes.root. Using the native function here is deliberate — it avoids re-entering the override and causing an infinite loop.

The two-stage update

The update handler is debounced (100 ms) and dispatches cart-updated events in two stages:

1. It dispatches upsell:cart-updated synchronously with the new Shopify cart.
2. If the cart has a valid token and items, it then fetches the matching Storefront API cart and dispatches upsell:storefront-cart-updated once that resolves.

The storefront fetch is what powers bundle line components inside the cart. It calls the Storefront GraphQL API using the access token exposed on window[APP_HANDLE].storefrontAccessToken.accessToken, and it fails silently — a missing token, network error, or rate limit must never break the host theme.

Idempotent installation

The override guards against being installed twice. It namespaces everything under window[APP_HANDLE] and sets window[APP_HANDLE].isFetchOverwritten = true once installed. If the script runs again and finds that flag, it logs Fetch already overridden and returns without re-wrapping.

Opening the cart

There are three supported ways to open Llama Cart.

// Open the cart
document.dispatchEvent(
  new CustomEvent('lcu:cart:toggle', { detail: { open: true } })
);

// Close the cart
document.dispatchEvent(
  new CustomEvent('lcu:cart:toggle', { detail: { open: false } })
);

[
  '[data-lcu-smart-cart-trigger]',
  'cart-icon[data-testid="cart-icon"]',
  'header a[href="{root}cart"]',
  'header a[href="/cart"]',
  'header a[href="cart"]',
  'nav a[href="{root}cart"]',
  'nav a[href="/cart"]',
  'nav a[href="cart"]',
]

<button data-lcu-smart-cart-trigger>View cart</button>

https://your-store.com/products/example?showLlamaCart=1

Preview mode

Preview mode lets you load Llama Cart on a storefront even when it isn't enabled globally, and lets you preview specific design versions. It's driven entirely by query parameters, and each preview selection is stored in sessionStorage with a 10-minute expiry so it survives navigation within the same tab.

Enable or disable the preview

Use llama-cart-preview-mode to force the cart on or off for your session:

https://your-store.com/?llama-cart-preview-mode=1

When preview mode is active, the cart loads even if globalSettings.llamaCartEnabled is false — as long as the block version is not set to disabled.

Preview a specific version

Use llama-cart-preview-target to preview one of the cart's design versions. The target value maps to an internal version:

https://your-store.com/?llama-cart-preview-target=a

When a valid target is set, the loader swaps in that version's drawer settings and translatable content before the cart renders. An unrecognized target value clears any stored target.

Preview a specific market

Pair the target with llama-cart-market-id to preview the version as configured for a specific market. When omitted, the market id defaults to main:

https://your-store.com/?llama-cart-preview-target=a&llama-cart-market-id=main

Constant reference

These are the exact constants Llama Cart uses. Treat the event names and query-parameter keys as a stable contract; the internal storage keys are listed for completeness.

Query parameters

Events

DOM and storage keys

Frequently asked

Next steps