EliteCart JavaScript API
Open, close and refresh EliteCart from your theme or another app, read the cart and react to cart events.
Last updated
Your theme, another app or your own Custom HTML can control EliteCart through the EliteCart JavaScript API: open and close the drawer, read the current cart and react when it changes. This page lists every public method, event, setting override and URL parameter.
If you write scripts that run inside the cart, also read Custom HTML for developers.
Methods on window.EliteCart
| Method | What it does | Returns |
|---|---|---|
openDrawerWithDataRefresh() | Loads the latest cart from Shopify, then opens the drawer | Promise |
openDrawerWithoutDataRefresh() | Opens the drawer without reloading the cart | nothing |
closeDrawer() | Closes the drawer | nothing |
switchFromTwoStepToRegularCart() | Closes the two-step cart and opens the regular cart | nothing |
refreshCart() | Loads the latest cart from Shopify and re-renders EliteCart, for example after another script changed the cart | Promise |
getCurrentCart() | The cart EliteCart currently shows, in Shopify's /cart.js format (prices in cents), or null before it has loaded | cart object or null |
onCartChange(callback) | Calls callback(cart) every time the cart changes | a function that removes the listener |
// Ask another app to open EliteCart instead of the theme cart
window.EliteCart.openDrawerWithDataRefresh();
// React to cart changes, and stop listening later
const stop = window.EliteCart.onCartChange(function (cart) {
console.log("Items in cart:", cart.item_count);
});
// stop();
Events
| Event | Listen on | Payload | When it fires |
|---|---|---|---|
eliteCartRendered | document | event.detail.cart | After EliteCart has rendered a loaded cart. Use it when you need to read or change elements in the cart |
eliteCartUpdated | document | none | After EliteCart has changed the cart, for example an add-to-cart or a quantity change |
eliteAddProductToCart | document | none | When EliteCart starts adding a product from a product form. It fires before the add finishes, also for adds that then fail, and not for upsells, addons or gifts |
document.addEventListener("eliteCartRendered", function (event) {
const cart = event.detail.cart;
console.log("Cart rendered with", cart.item_count, "items");
});
onCartChange can run before the cart has updated on screen. If your code touches elements inside the cart, use eliteCartRendered.
For a data layer that tracks add-to-cart, see Google Analytics events missing add-to-cart event.
Events you can send
Send these on window:
| Event | What it does |
|---|---|
eliteCart:openDrawerWithRefresh | Same as openDrawerWithDataRefresh(), for apps that prefer sending an event to calling a method. EliteCart must already be loaded |
eliteCart:reinitializeSettings | Re-reads the store's money format and texts from the page, for example after you changed them with a script |
eliteCart:reinitializeRewardBar | Recalculates the reward bar, for example after you set reward overrides late |
window.dispatchEvent(new CustomEvent("eliteCart:openDrawerWithRefresh"));
Let another script handle add-to-cart
Set one of these before the shopper clicks add to cart:
// EliteCart doesn't add the product, and still blocks the browser's default action.
// Use this when another app adds to cart with JavaScript.
window.eliteCartSkipAddToCart = true;
// EliteCart doesn't add the product and lets the form submit normally.
// Use this when your theme should do the add itself.
window.eliteCartSkipAddToCartAndDoNotPreventDefault = true;
EliteCart can still open afterwards: turn on Detect external cart changes and Open cart drawer on external add-to-cart at Cart designerOtherAdvanced. See the Advanced settings reference.
To hide parts of the cart for some visitors, see Adapt functionality based on customer tags or other conditions.
Open EliteCart with a URL parameter
Add elitecart-open=true to any store URL and EliteCart opens when the page loads:
https://yourstore.com/?elitecart-open=true
This is useful after a Shopify cart permalink in an email campaign, which adds a product and then sends the shopper to your store.
Good to know
- Shadow DOM. With Use Shadow DOM for CSS isolation on (the default for new stores),
document.querySelectorcan't find elements inside the cart. Usewindow.eliteCartDocumentOrShadowRootinstead. It works with the setting on or off. - Your own cart changes. If your script calls Shopify's cart endpoints (
/cart/add.js,/cart/change.js), add?elitecart=1to the URL and callwindow.EliteCart.refreshCart()afterwards. Without it, Detect external cart changes treats the call as coming from another app and may refresh or open the drawer. - CSS classes. Cart elements carry classes starting with
ec-. To style them, see Custom styling with CSS and AI.
Still stuck?
Chat with us and we'll help you get your cart live. Or email contact@elitecart.app.