JavaScript API, Events and URL Parameters
For developers. The cart drawer exposes a small JavaScript API on your storefront, plus events and URL parameters. Use them to open the drawer from custom buttons, react to cart changes, or run your own checks before checkout.
The API exists on pages where the cart drawer is enabled and the Essential Cart app embed is on.
Open the drawer from a link
Add one of these to any store URL to open the drawer when the page loads:
?essential_cart_open=true?open_cart=1
Values true, 1, yes or an empty value open the drawer. false, 0 and no don't.
window.essentialCartApi
| Method | What it does |
|---|---|
openCart(), closeCart(), toggleCart() |
Open, close or toggle the drawer |
refreshCart() |
Reload the cart, for example after your own add-to-cart request |
getCartData() |
The cart the drawer currently holds, in Shopify's /cart.js format. It is cached, so call refreshCart() first to get the latest cart |
isOpen(), getItemCount() |
Drawer state and item count |
addItem(variantId, quantity, properties) |
Add a variant, then refresh the drawer |
removeItem(lineItemKey) |
Remove a line by its key |
updateItemQuantity(lineItemKey, quantity) |
Change a line's quantity |
clearCart() |
Empty the cart |
Callbacks
Each returns a function that removes the listener.
| Callback | Runs when |
|---|---|
onCartOpen(fn), onCartClose(fn) |
The drawer opens or closes |
onCartUpdate(fn) |
The cart changes. Receives the cart |
onBeforeOpen(fn), onBeforeClose(fn) |
Before opening or closing. Return false to cancel |
onAfterOpen(fn), onAfterClose(fn) |
After opening or closing |
onBeforeCheckout(fn) |
Before checkout. Receives { checkoutUrl, cart }. Return false to stop checkout |
onItemAdd(fn), onItemRemove(fn) |
After addItem or removeItem is called through this API |
Events
Listen on document:
| Event | Fires when |
|---|---|
essential-cart:open |
The drawer is opened through the app API, for example by openCart() |
essential-cart:close |
The drawer is closed through the app API, for example by closeCart() |
essential-cart:item-added |
A shopper adds a product (automatic free gifts do not trigger it) |
essential-cart:before-checkout |
Checkout is about to start. Call event.preventDefault() to stop it. event.detail has checkoutUrl and cart |
Examples
Open the drawer after your own add-to-cart button:
fetch('/cart/add.js', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ items: [{ id: 123456789, quantity: 1 }] }) }) .then(() => window.essentialCartApi.refreshCart()) .then(() => window.essentialCartApi.openCart());
Block checkout until a custom check passes:
document.addEventListener('essential-cart:before-checkout', (event) => { if (!myCheckPassed()) { event.preventDefault(); alert('Please choose a delivery date first.'); } });
Stop auto-open on some pages
Add this script to the pages where the drawer shouldn't pop open on add to cart:
window.essentialCartPreventAutoOpenPaths = ['/pages/wholesale'];
The cart icon and openCart() still work there. See Controlling When the Cart Drawer Opens.
Page classes
<html> gets essential-cart__open while the drawer is open and essential-cart__closed when it's shut.