On the live storefront, Instant exposes a small JavaScript API at window.Instant.api for wiring your own code to the Instant cart. This is an advanced, developer-oriented feature — most stores never need it, because automatic cart actions already connect the common themes. Reach for the SDK only when a theme or third-party app isn't connected automatically and you want to integrate it yourself.
When you need the SDK
When you point add-to-cart actions at the Instant cart, Instant opens and refreshes the drawer for you, and Automatic cart actions setup connects most themes. Use the SDK when:
Your theme or a third-party app changes the cart with its own code and you want the Instant drawer to reflect it.
You want to open or close the Instant cart from your own script.
Check the API is available
The API is attached after the Instant storefront script loads, so guard for it before calling:
if (window.Instant?.api) {
// safe to call window.Instant.api methods
}You can read the loaded client version from window.Instant.initializedVersion.
Methods
toggleCart(open?)
Opens or closes the Instant cart drawer. Omit the argument to toggle; pass true to open or false to close.
window.Instant.api.toggleCart(); // toggle window.Instant.api.toggleCart(true); // open window.Instant.api.toggleCart(false); // close
If no Instant cart is published on the page, it falls back to redirecting the shopper to the Shopify cart page.
updateCart()
Refreshes the Instant cart UI — line items, totals, count badges, and rewards — from the current Shopify cart. It returns a Promise.
updateCart() does not add, change, or remove items. It only re-reads the current cart and repaints Instant's UI. To change the cart, call Shopify's Cart API (/cart/add.js, /cart/change.js, and so on), then call updateCart() to sync:
await fetch(`${window.Shopify.routes.root}cart/add.js`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ id: variantId, quantity: 1 }),
});
await window.Instant.api.updateCart();
Listen for cart events
Instant dispatches events on document that your code can handle. This is how a Custom cart action is meant to be wired up: set an add-to-cart control or cart button's Open option to Custom cart (see Build a cart drawer), then respond to the event yourself.
Event | Fires when |
|
| Instant has finished refreshing its cart UI | none |
| A shopper adds an item through an Instant action |
|
| A shopper clicks a cart button that opens the cart |
|
useInstantCart is true when the action targets the Instant cart and false when it targets a Custom cart, so you can react only to the custom case:
document.addEventListener('instant:add-to-cart', (event) => {
if (!event.detail.useInstantCart) {
// open your own cart drawer, refresh its UI, etc.
}
});