Refreshing widgets

When you change the cart programmatically from your theme — adding, updating, or removing line items with your own JavaScript — Llama Upsells widgets don't automatically know the cart changed. Dispatch the upsell:refresh event, passing the latest cart in detail.cart, to tell them to re-render.

The upsell:refresh event

upsell:refresh is a CustomEvent dispatched on document. The app's listeners do not fetch the cart themselves — they re-render and re-bootstrap the widgets using the cart you provide in detail.cart.

The app dispatches this event itself after it rebuilds the cart drawer and footer markup, so its own cart actions stay in sync. You dispatch the same event — with the latest cart attached — to opt your custom cart changes into that refresh.

When you need to dispatch it

Dispatch upsell:refresh whenever you modify the cart with your own code rather than through a Llama Upsells widget or the Llama Cart. Common cases:

• You call Shopify's Cart AJAX API directly — /cart/add.js, /cart/change.js, /cart/update.js, or /cart/clear.js.
• A custom or third-party cart drawer mutates the cart and you want Llama Upsells widgets to reflect the new state.
• Any flow where the cart changes but no Llama Upsells action triggered the change.

How to dispatch it

After your cart write completes, fetch the latest cart and dispatch the event on document with that cart in detail.cart:

async function addItemAndRefresh(variantId, quantity = 1) {
  const baseUrl = window.Shopify.routes.root;

  await fetch(`${baseUrl}cart/add.js`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      items: [{ id: variantId, quantity }],
    }),
  });

  // Fetch the updated cart, then hand it to Llama Upsells to re-render.
  const cart = await fetch(`${baseUrl}cart.json`).then((r) => r.json());

  document.dispatchEvent(
    new CustomEvent('upsell:refresh', { detail: { cart } }),
  );
}

The same pattern applies to any cart mutation — fetch /cart.json after the write, then pass the result in detail.cart:

async function changeLineAndRefresh(line, quantity) {
  const baseUrl = window.Shopify.routes.root;

  await fetch(`${baseUrl}cart/change.js`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ line, quantity }),
  });

  const cart = await fetch(`${baseUrl}cart.json`).then((r) => r.json());

  document.dispatchEvent(
    new CustomEvent('upsell:refresh', { detail: { cart } }),
  );
}

Listening for the refresh

The app dispatches upsell:refresh after it re-renders the cart drawer and footer markup, so you can listen for it too if your own theme code needs to react once the widgets and cart contents have updated:

document.addEventListener('upsell:refresh', (event) => {
  const cart = event.detail?.cart;
  // React to the refreshed cart, e.g. update your own cart count badge.
  console.log('Llama Upsells refreshed', cart);
});

Related events