Browse articles

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

MethodWhat it doesReturns
openDrawerWithDataRefresh()Loads the latest cart from Shopify, then opens the drawerPromise
openDrawerWithoutDataRefresh()Opens the drawer without reloading the cartnothing
closeDrawer()Closes the drawernothing
switchFromTwoStepToRegularCart()Closes the two-step cart and opens the regular cartnothing
refreshCart()Loads the latest cart from Shopify and re-renders EliteCart, for example after another script changed the cartPromise
getCurrentCart()The cart EliteCart currently shows, in Shopify's /cart.js format (prices in cents), or null before it has loadedcart object or null
onCartChange(callback)Calls callback(cart) every time the cart changesa 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

EventListen onPayloadWhen it fires
eliteCartRendereddocumentevent.detail.cartAfter EliteCart has rendered a loaded cart. Use it when you need to read or change elements in the cart
eliteCartUpdateddocumentnoneAfter EliteCart has changed the cart, for example an add-to-cart or a quantity change
eliteAddProductToCartdocumentnoneWhen 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:

EventWhat it does
eliteCart:openDrawerWithRefreshSame as openDrawerWithDataRefresh(), for apps that prefer sending an event to calling a method. EliteCart must already be loaded
eliteCart:reinitializeSettingsRe-reads the store's money format and texts from the page, for example after you changed them with a script
eliteCart:reinitializeRewardBarRecalculates 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.querySelector can't find elements inside the cart. Use window.eliteCartDocumentOrShadowRoot instead. 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=1 to the URL and call window.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.