Skip to main content
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.” Once you understand this pattern, you can apply it to almost any customization. 💡 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: Upcart 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 you’ve added.

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

A common UX improvement: hide the floating cart button when there’s nothing in the cart, so it doesn’t clutter the page. How it works: window.upcartOnCartLoaded fires every time the cart is loaded. It receives Shopify’s Cart object, which includes item_count- the total number of items in the cart. 
<script>
  window.upcartOnCartLoaded = (cart) => {
    const stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      stickyBtn.style.display = cart.item_count === 0 ? "none" : "block";
    }
  };
</script>
What’s happening line by line:
  1. upcartOnCartLoaded is called every time the cart loads, passing in the Shopify cart object.
  2. We grab the sticky button element by its ID (#upCartStickyButton).
  3. If item_count is 0, we hide it. Otherwise, we show it.

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

Useful for debugging, analytics, or triggering custom logic whenever a shopper adds a product. 
<script>
  window.upcartOnAddToCart = (id, quantity, item) => {
    console.log("Added to cart:", item.title, "| Qty:", quantity);
  };
</script>
Parameters available:
ParameterDescription
idThe variant ID of the added product
quantityNumber of units added
itemFull Shopify line item object

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

Some apps need a small script to track cart activity through Upcart. Here’s how to fire a TripleWhale AddToCart pixel event whenever a product is added: 
<script>
  window.upcartOnAddToCart = (id, quantity, item) => {
    window.TriplePixel('AddToCart', { item: id, q: quantity });
  };
</script>
Note: Each third-party app is different. Check with your app’s support team to confirm whether a script is needed and what the correct event format is. Upcart doesn’t provide support for third-party app scripts.

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

Want the cart drawer to open immediately when a shopper adds an item? Use upcartOnAddToCart alongside the window.upcartOpen() function: 
<script>
  window.upcartOnAddToCart = (id, quantity, item) => {
    window.upcartOpen();
  };
</script>

​
Quick Reference: Common API Functions

Function / EventWhen it fires / What it does
window.upcartOnCartLoaded(cart)Fires when the cart is loaded; receives cart object
window.upcartOnAddToCart(id, qty, item)Fires when an item is added to the cart
window.upcartOpen()Programmatically opens the cart drawer
window.upcartClose()Programmatically closes the cart drawer
For the full list of API functions and events, 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.