--- title: "Storefront JavaScript Events" description: "Add cart and item lifecycle events to build custom integrations on your storefront." url: https://help.cartgenie.com/en/articles/191-storefront-javascript-events collection: "Developers" updated: 2026-09-15 language: en --- # Storefront JavaScript Events Add cart and item lifecycle events to build custom integrations on your storefront. CartGenie emits a set of DOM events at key moments during the shopping experience — when the cart opens, when items are added or removed, when discounts are applied, and more. Any third-party script running on your storefront can listen for these events and react accordingly. ## Listening for Events Use the standard `document.addEventListener` API. Every CartGenie event is dispatched on the `document` object: js ```js document.addEventListener('item.added', (event) => { console.log('A product was just added to the cart.'); }); ``` ## Available Events ### Initialization

Event	Fires when…
cartgenie.ready	The CartGenie script has fully loaded and initialized on the page. Wait for this event before calling any CartGenie APIs.

### Cart Lifecycle

Event	Fires when…
cart.created	A new cart is created for the current visitor (first item added or cart initialized for a new session).
cart.ready	The cart has finished loading its contents and is available for interaction.
cart.open	The cart drawer or modal becomes visible to the shopper.
cart.close	The cart drawer or modal is dismissed.

### Item Events

Event	Fires when…
item.adding	An add-to-cart request has started but has not yet completed. Useful for showing loading states.
item.added	An item has been successfully added to the cart.
item.adding.error	An add-to-cart request failed (e.g., out of stock, network error).
item.updated	An existing line item's quantity or properties have changed.
item.removed	An item has been removed from the cart entirely.

### Discounts

Event	Fires when…
discount.applied	A discount code or automatic discount has been applied to the cart.

## Example: Fire a Tracking Pixel After Add-to-Cart js ```js document.addEventListener('cartgenie.ready', () => { console.log('CartGenie is ready — registering event listeners.'); document.addEventListener('item.added', (event) => { // Send an event to your analytics provider analytics.track('Product Added', { // Access event.detail for item data (if provided) }); }); }); ``` ## Tips - **Always wait for** `cartgenie.ready` before registering other listeners. This guarantees the CartGenie runtime is available. - **Events bubble up the DOM**, so `document.addEventListener` will catch them regardless of where they originate. - **Check** `event.detail` — some events include a payload with contextual data such as the item, quantity, or error message. - **Multiple listeners are fine.** You can register as many listeners for the same event as you need; they won't interfere with each other.