Cart events

Llama Upsells keeps your theme in sync with cart state by dispatching DOM CustomEvents on document whenever the cart changes. You listen for these events to react to add-to-cart actions, cart updates, discount-code changes, and Llama Cart toggles — without polling the Shopify cart yourself.

All events are dispatched on document, so attach listeners with document.addEventListener(...). Each event name is a fixed string; the tables and examples below use the exact value Llama Upsells emits.

Event reference

upsell:cart-updated

The primary cart event. Llama Upsells dispatches it whenever it detects the Shopify cart has changed, passing the full updated cart object.

event.detail

document.addEventListener('upsell:cart-updated', (event) => {
  const { newCart } = event.detail;

  console.log('Item count:', newCart.item_count);
  console.log('Line items:', newCart.items);
});

upsell:storefront-cart-updated

Fires after Llama Upsells refetches the cart through the Shopify Storefront API. This carries the richer Storefront cart representation (including discount data), which the standard /cart.js payload does not provide.

It is dispatched in two situations:

• After upsell:cart-updated, once the follow-up Storefront fetch resolves (skipped if the cart has no token or no items array).
• After a discount code is applied or removed, with the cart returned by the discount mutation.

event.detail

document.addEventListener('upsell:storefront-cart-updated', (event) => {
  const { newStorefrontCart } = event.detail;

  console.log('Storefront cart:', newStorefrontCart);
  console.log('Discount codes:', newStorefrontCart.discountCodes);
});

lcu:smart-cart:updated

Fires when the Llama (Smart) Cart's internal state updates. Use it to react to changes in the rendered Llama Cart specifically, rather than the underlying Shopify cart.

document.addEventListener('lcu:smart-cart:updated', (event) => {
  // React to the latest Llama Cart state.
  console.log('Smart cart updated', event.detail);
});

upsell:cart-discount-codes-updated

Fires when the set of applied discount codes changes — for example, after a shopper applies or removes a code in the Llama Cart and Llama Upsells revalidates the cart against your campaigns.

event.detail

document.addEventListener('upsell:cart-discount-codes-updated', (event) => {
  const { newCart, discountCodes } = event.detail;

  console.log('Applied discount codes:', discountCodes);
  console.log('Cart total:', newCart.total_price);
});

lcu:cart:item_added

Fires when one or more line items are added to the cart. Use it to trigger your own analytics, animations, or side effects on add-to-cart.

document.addEventListener('lcu:cart:item_added', (event) => {
  // Items were just added to the cart.
  console.log('Items added', event.detail);
});

lcu:cart:item_removed

Fires when one or more line items are removed from the cart.

document.addEventListener('lcu:cart:item_removed', (event) => {
  // Items were just removed from the cart.
  console.log('Items removed', event.detail);
});

lcu:cart:toggle

Fires when the Llama Cart is toggled — opened or closed. Use it to keep your own UI in sync with the cart drawer's open state.

document.addEventListener('lcu:cart:toggle', (event) => {
  // The Llama Cart was opened or closed.
  console.log('Llama Cart toggled', event.detail);
});

Putting it together

A common pattern is to listen for upsell:cart-updated to react to any cart change, then use upsell:storefront-cart-updated when you specifically need discount information. Remember to remove your listeners when they are no longer needed.

function onCartUpdated(event) {
  const { newCart } = event.detail;
  // Update your UI with the latest cart.
  render(newCart);
}

function onStorefrontCartUpdated(event) {
  const { newStorefrontCart } = event.detail;
  // Update discount-aware UI.
  renderDiscounts(newStorefrontCart.discountCodes);
}

document.addEventListener('upsell:cart-updated', onCartUpdated);
document.addEventListener('upsell:storefront-cart-updated', onStorefrontCartUpdated);

// Later, when tearing down:
document.removeEventListener('upsell:cart-updated', onCartUpdated);
document.removeEventListener('upsell:storefront-cart-updated', onStorefrontCartUpdated);

Related events