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.
Use the standard document.addEventListener API. Every CartGenie event is dispatched on the document object:
js
document.addEventListener('item.added', (event) => {
console.log('A product was just added to the cart.');
});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. |
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. |
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. |
Event | Fires when… |
discount.applied | A discount code or automatic discount has been applied to the cart. |
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)
});
});
});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.