JavaScript events overview
Listen to the storefront DOM CustomEvents the app dispatches to react to cart updates, quick-view actions, and checkout clicks.
The app dispatches native DOM CustomEvents on the storefront as shoppers interact with the cart, upsell widgets, and checkout. You can listen for these events to keep your own UI in sync, trigger analytics, or run custom logic — without patching the app's internals.
All events are dispatched on document, so you attach listeners with document.addEventListener. Many events carry a detail payload (for example the updated cart) that you can read inside your handler.
How to listen
Every event name is a plain string. Add a listener, read the detail payload, and remember to remove the listener when you no longer need it.
function onCartUpdated(event) {
// The updated cart is passed on the event's detail payload
const cart = event.detail.newCart;
console.log('Cart updated:', cart);
}
document.addEventListener('upsell:cart-updated', onCartUpdated);
// Later, when you no longer need it:
// document.removeEventListener('upsell:cart-updated', onCartUpdated);The exact shape of detail depends on the event. The reference table below notes which events carry a payload, and the dedicated pages document each payload in detail.
Event reference
The table lists every event the app exposes, along with the exact event-name string you pass to addEventListener.
| Event name (string) | Description |
|---|---|
upsell:cart-updated | The Shopify cart changed. detail.newCart holds the updated cart. |
upsell:storefront-cart-updated | The Storefront API view of the cart changed. detail.newStorefrontCart holds the updated cart. |
lcu:smart-cart:updated | The Llama Cart (smart cart) state was updated. |
upsell:cart-discount-codes-updated | The discount codes applied to the cart changed. |
lcu:pre-purchase-recommendations | Pre-purchase (product recommendation) offers were resolved for the cart. |
lcu:cart:toggle | The Llama Cart drawer was opened or closed. |
lcu:cart:item_added | One or more items were added to the cart. |
lcu:cart:item_removed | One or more items were removed from the cart. |
lcu:checkout:clicked | A shopper clicked a checkout button. |
The app also dispatches an upsell:refresh event after it re-renders cart content, with the latest cart on detail.cart. See Upsell refresh for how to use it.
Example: reacting to cart changes
When the cart changes, the app dispatches upsell:cart-updated with the new cart, then follows up with upsell:storefront-cart-updated once the Storefront API view is available. You can listen for either, depending on which cart shape you need.
document.addEventListener('upsell:cart-updated', (event) => {
const cart = event.detail.newCart;
// Update your custom cart badge, mini-cart, etc.
updateCartBadge(cart.item_count);
});
document.addEventListener('upsell:storefront-cart-updated', (event) => {
const storefrontCart = event.detail.newStorefrontCart;
// Read Storefront API fields such as discount allocations
console.log(storefrontCart.discountCodes);
});Related event pages
Each group of events has its own page with payload details and usage examples.