Skip to main content
If your storefront runs on Shopify Hydrogen, Next.js, Remix, or any other custom front end, the standard Shopify Theme App Extension won’t load — there’s no Liquid theme to inject into, so nothing fires storefront events for you. Instead, add the standard Upstack Pixel script to your storefront and fire each storefront event from your own code using the JavaScript SDK and the standard event definitions.
Orders and refunds still reach Upstack directly from Shopify, whatever your storefront architecture. This page only covers browser-side event tracking.

​
Prerequisites

  • The Upstack Data app installed in your Shopify Admin (so orders reach Upstack directly from Shopify)
  • An Upstack Data account with subscription active
  • Your Upstack Pixel ID (UUID format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, e.g., 58284d43-85f6-41fb-b2e0-f32f8ecb4e9b). See How to find my Upstack Data Pixel ID
  • Edit access to the headless storefront codebase (Hydrogen, Next.js, Remix, Nuxt, or other framework)
  • Ability to deploy changes to your storefront (CI/CD or manual deploy access)

​
When to Use This Page

Use the headless installation if any of the following are true:
  • Your storefront is built on Shopify Hydrogen, Next.js, Remix, Nuxt, or another custom framework
  • You serve checkout through Shopify but render product, collection, and cart pages from your own front end
  • You don’t have a standard Liquid theme where the Shopify Theme App Extension can be enabled
If your storefront uses a standard Shopify theme, follow the standard Shopify installation guide instead — the Theme App Extension handles everything automatically.

​
Step 1: Add the Upstack Pixel script

Add the standard Upstack Pixel script to the <head> of every page. Replace YOUR_PIXEL_ID with your Pixel ID from System → Events Manager in the Upstack dashboard.
The script defines window._upstack() immediately and queues any calls made before the SDK finishes loading, so you can fire events right away. See Installation in the JavaScript SDK reference for how the queue works.
In Hydrogen, Next.js, or Remix, add the script to your root layout or document <head> so it loads once per full page load — not inside a component that re-renders on every route change.

​
Step 2: Track route changes

The script’s window._upstack('page') call only runs on a full page load. Headless storefronts usually navigate client-side, so call it again on every later route change — but not on the first render, which the script already tracked:
See SPA navigation tracking for React Router and Next.js App Router examples.

​
Step 3: Fire storefront events

On a theme-based store, the theme app extension and the Upstack custom pixel fire these events automatically. Neither runs on your headless storefront pages, so fire each one from your own code when the matching action happens. Each event page lists the required and optional properties. For example, fire add_to_cart from your add-to-cart handler:
Use the snake_case event names exactly as shown. For other actions your storefront supports — wishlists, account sign-ups, logins, newsletter forms — see the full standard events list. When a shopper signs in or enters an email on your storefront, call identify so later events are matched to that customer.

​
Checkout and purchase

Checkout runs on Shopify’s hosted checkout, which your storefront code doesn’t control. To track it, add the Upstack custom pixel in your Shopify admin under Settings → Customer events — follow Add Custom Pixel in the Shopify setup guide. The custom pixel sends initiate_checkout, add_shipping_info, add_payment_info, and purchase from the checkout. Without the custom pixel, purchases (a few minutes after the order) and initiate_checkout (once a shopper enters contact details) still reach Upstack directly from Shopify, but shipping and payment steps aren’t tracked. Don’t fire initiate_checkout, add_shipping_info, add_payment_info, or purchase from your storefront, or they’ll be counted twice.

​
Server-Side Events Continue to Flow

Headless installation only affects browser-side tracking. Server-side events from Shopify — orders placed, orders refunded, products updated, customer changes — keep reaching Upstack directly from Shopify as long as the Upstack Data app is installed, whatever your storefront architecture. This means your conversion data, revenue, and order-level attribution will still flow into Upstack even if you skip the browser pixel entirely. Browser tracking adds page views, product views, and pre-checkout cart events on top of the server-side baseline.

​
Verify the Install

Once the pixel is loaded on your storefront:
  1. Open your storefront in a browser, navigate between pages, and add a product to the cart.
  2. Use the Upstack Data Pixel Helper to confirm the pixel fires with your Pixel ID.
  3. Open the Upstack dashboard and go to System → Events Manager.
  4. Confirm page_view events — and the storefront events you wired — arrive within a few minutes of activity.
For more thorough event verification, see Verify events are flowing.

JavaScript SDK

Full reference for page, track, and identify.

Standard events

Event names and properties to use when wiring storefront events.

Automatic tracking

What a theme-based store tracks automatically — the events you replicate on headless.

Standard Shopify install

The default install path for storefronts that use a Shopify theme.

Verify events

Confirm events are flowing from your storefront into Upstack.