Common Upcart API Uses

Learn how to put Upcart’s Public API to work with practical, copy-paste examples.

How the API Pattern Works

Most Upcart API scripts follow the same simple pattern:

Listen for a cart event → Check a condition → Take an action

For example: “When the cart loads → check if it’s empty → hide the sticky button.”

💡 New to APIs? Start with What is an API? before diving into the examples below.

---

Where to Add Your Scripts

All scripts below go in:

Cart Editor → Settings → Custom HTML → Scripts (before load)

Wrap each snippet in <script>...</script> tags and save. To test, open your browser’s Dev Tools console (F12) and look for any console.log messages.

---

A note on legacy vs. modern callbacks

Upcart has two ways to listen for cart events:

Style	Example	Status
Modern (recommended)	upcartSubscribeAddedToCart(fn)	Current
Legacy (deprecated)	upcartOnAddToCart = fn	Still works, logs console warning

All examples below use the modern API. Existing scripts using the old style will continue working.

---

Example 1: Hide the Sticky Cart Button When the Cart is Empty

<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>

How it works: upcartSubscribeCartLoaded fires every time the cart is loaded. The callback receives an event with a cart object containing an items array. We sum the quantity of each item to determine if the cart is empty.

⚠️ IMPORTANT: event.cart does NOT have an item_count property. You must calculate the total by iterating event.cart.items.

---

Example 2: Log When an Item is Added to the Cart

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>

Properties available on event.item:

Property	Description
event.item.title	Product title
event.item.quantityAdded	Number of units added in this action
event.item.quantity	Total quantity of this item now in cart
event.item.variantId	Shopify variant ID
event.item.handle	Product handle
event.item.productId	Shopify product ID
event.item.finalPrice	Final price after discounts
event.item.image	Product image URL

---

Example 3: Integrate with a Third-Party Analytics App (e.g. TripleWhale)

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>

Note: Each third-party app is different. Check with your app’s support team for the correct event format.

---

Example 4: Open the Cart Automatically After a Product is Added

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>

Note: If “Open cart drawer on add to cart” is already enabled in Cart Editor → Settings → Cart Settings, you don’t need this script.

---

Quick Reference: Subscribe Functions (Modern API)

Function	When it fires	Callback receives
upcartSubscribeCartLoaded(fn)	Cart data loads	{ cart } - cart has .items[], .total, .currency
upcartSubscribeAddedToCart(fn)	Item added to cart	{ item } - item has .title, .variantId, .quantityAdded, .quantity
upcartSubscribeCartOpened(fn)	Cart drawer opens	{} (empty object)
upcartSubscribeCartClosed(fn)	Cart drawer closes	{} (empty object)
upcartSubscribeCartUpdated(fn)	Cart contents change	{ cart }
upcartSubscribeItemRemoved(fn)	Item removed	{ item }
upcartSubscribeCheckoutClicked(fn)	Checkout button clicked	{ event } - browser MouseEvent
upcartSubscribeUpsellsAddedToCart(fn)	Upsell item added	{ variant } - has .id and .title
upcartSubscribeUpsellsRendered(fn)	Upsells render in cart	{ item, element } - item is the product, element is the DOM node
upcartSubscribeNotesTextChanged(fn)	Cart notes updated	{ text } - the updated notes string
upcartSubscribeRewardsMilestonesCompletedChanged(fn)	Reward milestone status changes	{ milestonesCompleted }

---

Direct Action Functions

Function	What it does
window.upcartOpenCart()	Opens the cart drawer
window.upcartCloseCart()	Closes the cart drawer
window.upcartRefreshCart()	Refreshes cart data
window.upcartGetCart()	Returns the current cart object
window.upcartRegisterAddToCart()	Registers add-to-cart for page builders (Replo, PageFly, etc.)
window.upcartFormatMoney()	Formats a price using your store’s money format

For the full API documentation, see the Upcart Public API Documentation.

---

Troubleshooting

• Script not running? Double-check placement: it should be in Scripts (before load), not after load.
• Element not found? Make sure the selector (e.g. #upCartStickyButton) matches the actual element ID in your cart.
• Something broke? Comment out your script by adding // to the start of each line, save, and refresh.
• Still stuck? See the API FAQ for more troubleshooting steps.