> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless Shopify installation

> Install the standard Upstack Pixel script on headless Shopify storefronts (Hydrogen, Next.js, Remix) and wire storefront events yourself with the JavaScript SDK.

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](https://docs.upstackdata.com/pixel/javascript-sdk.md) and the [standard event definitions](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events).

> [!NOTE]
>
> 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](https://admin.shopify.com) (so orders reach Upstack directly from Shopify)

* An [Upstack Data](https://app.upstackdata.com) 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](https://docs.upstackdata.com/resources/how-to-find-my-upstack-data-pixel-id.md)

* 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](https://docs.upstackdata.com/quickstart/install-on-shopify.md) 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](https://app.upstackdata.com).

```html theme={null}
<!-- Start UpstackData Pixel -->
<script src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js" async="true"></script>
<script>
  window._adqLoaded = 0;
  window._upsqueue = window._upsqueue || [];
  window._upstack = window._upstack || function () {
    window._upsqueue.push(arguments);
  };
  window._upstack('init', 'YOUR_PIXEL_ID'); // replace with your Pixel ID
  window._upstack('page');
</script>
<!-- End UpstackData Pixel -->
```

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](https://docs.upstackdata.com/pixel/javascript-sdk.md#installation) in the JavaScript SDK reference for how the queue works.

> [!TIP]
>
> 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:

```javascript theme={null}
window._upstack('page');
```

See [SPA navigation tracking](https://docs.upstackdata.com/pixel/javascript-sdk.md#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.

| Storefront action | Event to fire | Event documentation |
| - | - | - |
| Views a product page | `view_content` | [view\_content](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events/view-content.md) |
| Views a collection | `view_category` | [view\_category](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events/view-category.md) |
| Views a product list or grid | `view_item_list` | [view\_item\_list](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events/view-item-list.md) |
| Searches the store | `search` | [search](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events/search.md) |
| Views the cart page or opens the cart drawer | `view_cart` | [view\_cart](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events/view-cart.md) |
| Adds an item to the cart | `add_to_cart` | [add\_to\_cart](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events/add-to-cart.md) |
| Removes an item from the cart | `product_removed_from_cart` | [product\_removed\_from\_cart](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events/product-removed-from-cart.md) |

For example, fire `add_to_cart` from your add-to-cart handler:

```javascript theme={null}
window._upstack('track', 'add_to_cart', {
  items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 1 }],
  value: 34.99,
  currency: 'USD'
});
```

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](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events).

When a shopper signs in or enters an email on your storefront, call [`identify`](https://docs.upstackdata.com/pixel/javascript-sdk#identifyuserid-data) 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](https://docs.upstackdata.com/sources/catalog/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify.md#part-3-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](https://docs.upstackdata.com/guides/pixel-helper/how-to-install-upstack-data-pixel-helper.md) to confirm the pixel fires with your Pixel ID.
3. Open the [Upstack dashboard](https://app.upstackdata.com) 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](https://docs.upstackdata.com/quickstart/verify-events.md).

## Related

> [card] [JavaScript SDK](https://docs.upstackdata.com/pixel/javascript-sdk.md)
>
> Full reference for `page`, `track`, and `identify`.

> [card] [Standard events](https://docs.upstackdata.com/event-tracking/event-taxonomy/standard-events)
>
> Event names and properties to use when wiring storefront events.

> [card] [Automatic tracking](https://docs.upstackdata.com/sources/catalog/shopify-automatic-tracking.md)
>
> What a theme-based store tracks automatically — the events you replicate on headless.

> [card] [Standard Shopify install](https://docs.upstackdata.com/quickstart/install-on-shopify.md)
>
> The default install path for storefronts that use a Shopify theme.

> [card] [Verify events](https://docs.upstackdata.com/quickstart/verify-events.md)
>
> Confirm events are flowing from your storefront into Upstack.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.