Events reference

Poison announces every important storefront interaction as a DOM event, so apps, custom code and analytics can react without depending on the theme's markup. There are two layers:

1. Poison events (cart:updated, variant:change, …): CustomEvents dispatched on document with a detail payload. They always fire after the page has been updated, so listeners see the fresh state.
2. Shopify standard storefront events (shopify:cart:lines-update, shopify:page:view, …): the platform-wide events every app understands, dispatched from the element where the interaction happened. See Standard events.

This page is the reference for developers who build on the theme.

---

Listening

document.addEventListener('cart:updated', (event) => {
  const { cart, action } = event.detail;
  console.log(`Cart ${action}: ${cart.item_count} items`);
});

Every Poison event's detail also has timestamp (milliseconds) and source ("poison", or "standard-action" when the change came from Shopify.actions.updateCart).

Asking the cart UI to refresh

After your code changes the cart outside the theme (for example with fetch('/cart/add.js')), tell every cart UI on the page — drawer, header count, cart page, free-shipping goal — to re-render:

document.dispatchEvent(new CustomEvent('cart:refresh'));

Poison combines simultaneous refresh requests into one Section Rendering API request. Prefer Shopify.actions.updateCart(...) when you can: it updates the cart and the theme's UI in one call and emits the standard events for you.

---

Catalog

variant and previousVariant on variant:change are { id, exists, available, title, sku, price, currency, options, selected_options, featured_media_id } (price in the currency's subunit, as Liquid outputs it). cart is the AJAX cart object (the shape returned by /cart.js). action on cart:updated is one of add, remove, update, note or standard-action.

Example payloads

// cart:item-added
{
  items: [{ id: 44011, variant_id: 44011, product_id: 8812, quantity: 1, title: 'Reflection slip dress - Lacquer red / S', … }],
  cart: { token: '…', item_count: 3, total_price: 84900, items: [ … ], … },
  sourceElement: <article class="po-card" …>,
  productId: 8812,
  variantId: 44011,
  quantity: 1,
  timestamp: 1791037200000,
  source: 'poison'
}

// cart:item-updated
{ lineKey: '44011:8a6b…', previousQuantity: 1, quantity: 2, cart: { … } }

// cart:error
{ action: 'add', message: 'All 3 Reflection slip dress - Lacquer red / S are in your cart.', status: 422, variantId: 44011 }

// variant:change
{ productId: 8812, variant: { id: 44012, title: 'Ink / M', available: true, price: 42000, … }, previousVariant: { … }, sectionId: 'template--main', available: true }

// facets:updated
{ url: '/collections/new-in?filter.v.availability=1&sort_by=price-ascending', sectionId: 'template--main-collection', resultsCount: 24 }

---

Order and loop prevention

Every cart change follows the same order:

1. The cart request is sent with the cart sections bundled (Section Rendering API).
2. The returned HTML is swapped into the page.
3. The specific event fires: cart:item-added, cart:item-removed, cart:item-updated or cart:note-updated.
4. cart:updated { cart, action }.
5. cart:empty { cart }, when the cart became empty.
6. cart:refresh { handled: true, sections }.

Rule for cart UI: re-render on cart:refresh only when event.detail?.handled !== true. Poison's own broadcast is already handled, so this never causes a second request:

document.addEventListener('cart:refresh', (event) => {
  if (event.detail?.handled === true) return;
  // fetch and re-render this component
});

An external cart:refresh (no detail) triggers one coalesced request for all cart sections; that render emits section:rendered, never another cart:refresh.

---

Shopify standard events

Poison dispatches Shopify's standard storefront events for changes the theme makes itself, using Shopify's library from https://cdn.shopify.com/storefront/standard-events.js:

When an app calls Shopify.actions.updateCart, the action emits the standard cart events itself; Poison's configured handler then re-renders the cart sections and emits cart:updated, cart:empty and cart:refresh { handled: true }, and returns detail.handledBy: 'poison' so app listeners can skip their own re-render. Shopify.actions.openCart opens Poison's cart drawer, or the cart page when the cart type isn't drawer.

---

For theme developers

Poison's modules are ES modules behind an import map:

import { POISON_EVENTS, emit, on } from '@poison/events';
import { add, change, update, get } from '@poison/cart-api';

const stop = on(POISON_EVENTS.CART_UPDATED, ({ detail }) => console.log(detail.cart));
await add({ items: [{ id: 44011, quantity: 1 }] });
stop();

emit(name, detail, target = document) adds timestamp and source. on(name, handler) returns a function that removes the listener. Use the cart-api functions instead of calling the AJAX endpoints directly: they bundle the cart sections and fire the events above in order.