Developer Documentation (Methods/Events/CSS Selectors)

Lightweight, global helpers for opening/closing the slide cart and adding items programmatically. These functions are added to the storefront's window once the cart drawer has loaded on the page.

Getting Started

Once the Oxify: Cart Upsell & Gift app embed is turned on in your theme and you have saved the cart in the Cart Editor at least once, the public API becomes available on the global window object on storefront pages.

Prerequisites

• Active Oxify Cart installation on your Shopify store
• Basic understanding of JavaScript
• Familiarity with Shopify theme structure

Feature Detection (Important)

Always check that the functions exist before calling them. This prevents errors if the app is disabled or a script hasn’t loaded yet.

<script>  
 function isIACartReady() {  
   return typeof window.openIACartDrawer === "function" &&  
          typeof window.closeIACartDrawer === "function" &&  
          typeof window.addItemsToIACartDrawer === "function";  
 }  
</script>

Best Practices

• Check for API availability before calling (see Feature Detection).
• These functions don't return a result, so if you need to confirm an add worked (after a network issue or an invalid variant ID, for example), check the cart yourself, such as by fetching /cart.js.
• Use event listeners from your theme (e.g., re-render cart badge after add) where applicable.
• Test across multiple devices and browsers; verify behavior with other cart apps present.

Browser Compatibility

The cart drawer runs in the shopper's browser as part of your storefront, so these functions are available wherever the drawer loads.

Note: Implement feature detection before using these APIs to ensure compatibility across browsers and versions.

API Reference

window.openIACartDrawer()

Summary

Programmatically opens the Oxify Cart slide cart. Useful when your theme or another app overrides default open behavior.

Type

() => void

Example

if (typeof window.openIACartDrawer === "function") {

window.openIACartDrawer();

}

window.closeIACartDrawer()

Summary

Programmatically closes the IA Cart slide cart. Useful when another app intercepts default close behavior.

Type

() => void

Example

if (typeof window.closeIACartDrawer === "function") {

window.closeIACartDrawer();

}

window.addItemsToIACartDrawer(listOfItems: any)

Summary

Adds one or more line items to the cart and refreshes the drawer's contents. It doesn't open the drawer by itself; call openIACartDrawer() as well to show the updated cart.

Type

(listOfItems: Array<{ id: number; quantity: number; selling_plan?: number }>) => void

Parameters

Name

Type

Required

Description

id

number

Yes

The variant ID to add. A numeric string or a gid://shopify/ProductVariant/... ID also works.

quantity

number

Yes

Quantity to add for this variant.

selling_plan

number

No

Optional Shopify selling plan ID for subscriptions.

Example
​

if (typeof window.addItemsToIACartDrawer === "function") {  
 window.addItemsToIACartDrawer([  
   { id: 50633075097873, quantity: 1, selling_plan: 5960958225 }  
 ]);  
 // Optionally open the drawer after adding:  
 if (typeof window.openIACartDrawer === "function") {  
   window.openIACartDrawer();  
 }  
}

Oxify-named aliases

Each method above also exists under the preferred Oxify name, and both names run the same code: window.openOxifyCartDrawer(), window.closeOxifyCartDrawer() and window.addItemsToOxifyCartDrawer(listOfItems).

Other methods

• window.toggleOxifyCartDrawer() (also window.toggleIACartDrawer()) — Opens the drawer if it is closed and closes it if it is open.
• window.setOxifyCartLoading(loading: boolean) (also window.setIACartLoading()) — Shows or hides the cart's loading state.
• window.refreshOxifyCartDrawer({ showLoading }) — Re-reads the cart from Shopify and refreshes rewards, upsells and recommendations. showLoading is optional and defaults to true, but you must still pass an options object, for example window.refreshOxifyCartDrawer({}). This one has no IA name.
• window.setOxifyLastAddedProductId(productId) (also window.setIALastAddedProductId()) — Tells the cart which product was added last, which is used to choose which upsells to show.

Usage Examples

Open the cart from a custom button

<button id="open-cart">Open Cart</button>  
<script>  
 document.getElementById("open-cart").addEventListener("click", function () {  
   if (typeof window.openIACartDrawer === "function") {  
     window.openIACartDrawer();  
   }  
 });  
</script>  

Add a single variant (with optional subscription)

<button id="add-variant">Add & Open Cart</button>  
<script>  
 const VARIANT_ID = 50633075097873;      // replace with your variant id  
 const SELLING_PLAN_ID = 5960958225;     // optional, remove if not using subscriptions  

 document.getElementById("add-variant").addEventListener("click", () => {  
   if (typeof window.addItemsToIACartDrawer !== "function") return;  

   window.addItemsToIACartDrawer([  
     { id: VARIANT_ID, quantity: 1, selling_plan: SELLING_PLAN_ID }  
   ]);  

   if (typeof window.openIACartDrawer === "function") {  
     window.openIACartDrawer();  
   }  
 });  
</script>

Add multiple line items at once

<script>  
 function addBundleToCart() {  
   if (typeof window.addItemsToIACartDrawer !== "function") return;  

   const items = [  
     { id: 50633075097873, quantity: 1 },  
     { id: 50633075130641, quantity: 2 },  
     { id: 50633075163409, quantity: 1, selling_plan: 5960958225 } // optional subscription  
   ];  

   window.addItemsToIACartDrawer(items);  

   if (typeof window.openIACartDrawer === "function") {  
     window.openIACartDrawer();  
   }  
 }  

 // Example: call this after a bundle CTA click  
 // document.querySelector(".bundle-cta").addEventListener("click", addBundleToCart);  
</script>

Events

oxify-cart:opened

Dispatched on window every time the cart drawer opens, however it was opened (a cart icon, an add to cart, or openIACartDrawer()). event.detail.timestamp holds the time as an ISO string. There is no matching close event.

window.addEventListener("oxify-cart:opened", function (event) {
  console.log("Cart opened at", event.detail.timestamp);
});

Refreshing the cart after your own changes

The drawer refreshes itself when another script changes the cart through fetch or XMLHttpRequest calls to /cart/add, /cart/update, /cart/change or /cart/clear. You can also make it re-read the cart by calling window.refreshOxifyCartDrawer({}) or by dispatching one of these events on document:

• oxify-cart:external-change
• oxify-fbt:cart-updated, oxify-addon:items-added and oxify-plw:cart-updated (dispatched by Oxify's own widgets)
• discount_kit:cart_changed

CSS Selectors

These elements and class names exist in the storefront markup, and you can target them from Custom CSS. Start your rules with #ia-upsell-cart-parent so they stay inside the drawer.

• #ia-upsell-cart-parent-div — The element the cart drawer mounts into (added by the app embed).
• .ia-sliding-cart — The sliding drawer container. Modifiers: .ia-sliding-cart--active, .ia-sliding-cart--inactive, .ia-sliding-cart--left and .ia-sliding-cart--right. It reads the CSS variables --ia-cart-z-index, --ia-cart-padding, --ia-cart-min-width and --ia-cart-width.
• #ia-upsell-cart-parent and .ia-upsell-cart-parent — Wrap everything inside the drawer.
• .ia-cart-body — The body of the cart, shown when the cart has items.
• .ia-cart-item-container — A cart line item (.ia-cart-item-container-style-2-card with the card item template).
• .ia-cart-item-title — A line item's product title link.
• .ia-cart-item-property-value-image — An image shown for a line item property value, when Show image URLs in line item properties is on.
• .ia-rewards-banner-progress-wrapper — The progress bar of the rewards banner.
• .ia-subscription-upgrade-button — The subscription upgrade button on a line item.
• .ia-checkout-button — The checkout button.

Troubleshooting & FAQs

The functions are undefined.

• Ensure the Oxify: Cart Upsell & Gift app embed is on for the published theme.
• Make sure you have saved the cart in the Cart Editor at least once; until then the cart drawer doesn't load and these functions don't exist.
• Verify the storefront is not blocking third-party scripts (content security policy/ad blockers).
• Use feature detection, and call the functions from a user action (such as a click) or after the page has finished loading.

Items didn’t appear in the cart, or the wrong item was added.

• Confirm you’re passing variant IDs (not product IDs).
• Make sure the selling_plan ID is valid for that variant (if used).
• Check quantity is a positive integer.

Another cart app conflicts with opening/closing.

• Prefer calling window.openIACartDrawer() and window.closeIACartDrawer() directly from your custom triggers to override theme/app intercepts.
• Avoid binding duplicate click handlers on the same element.

Type Definitions

type IACartLineItem = {

id: number; // Variant ID

quantity: number; // > 0

selling_plan?: number; // Optional subscription selling plan ID

};