Skip to main content

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.

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. Instead, install the Upstack JavaScript SDK directly in your storefront code.
Server-side events (orders, refunds, fulfillment updates) are still captured automatically through Shopify webhooks regardless of your storefront architecture. This page only covers browser-side event tracking.

​
Prerequisites

  • The Upstack Data app installed in your Shopify Admin (so server-side webhooks are configured)
  • 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.

​
Installation

Choose one of the two installation methods below depending on your storefront’s build system.

​
Option 1: CDN Script Tag

The simplest approach is to load the Upstack pixel from our CDN. Add the following tag to the <head> of every page that should track events: 
<script src="https://cdn.upstackdata.com/pixel.js" data-pixel-id="YOUR_PIXEL_ID" async></script>
Replace YOUR_PIXEL_ID with the Pixel ID found in the Upstack dashboard under Settings → Event Health (UUID format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX). See How to find my Upstack Data Pixel ID for step-by-step instructions. The async attribute prevents the pixel from blocking page rendering. Once loaded, the pixel automatically captures page views and listens for cart and checkout events through the Shopify Storefront API.

​
Option 2: NPM Package

For tighter integration with your front end framework — including programmatic event tracking and SSR support — install the Upstack npm package: 
npm install @upstackdata/pixel
Then initialize the pixel in your storefront’s entry point: 
import { Upstack } from '@upstackdata/pixel';

const upstack = new Upstack({ pixelId: 'YOUR_PIXEL_ID' });
upstack.page();
Call upstack.page() on every route change to register a page view. For cart and checkout events, see the SDK reference for the full event API.
In framework-specific environments like Hydrogen or Next.js, initialize the pixel in your root layout or _app component so it’s only created once per session.

​
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 — continue to reach Upstack through Shopify webhooks regardless of your storefront architecture. As long as the Upstack Shopify app is installed in your Shopify admin, these webhooks are configured automatically. 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 and navigate between pages.
  2. Use the Upstack Data Pixel Helper to confirm the pixel fires with your Pixel ID.
  3. Open the Upstack dashboard and go to Sources → Shopify.
  4. Confirm PageView events arrive within 1–2 minutes of activity.
For more thorough event verification, see Verify events are flowing.

Standard Shopify install

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

Shopify source

How the Shopify source ingests events through the pixel and webhooks.

Shopify webhooks

Server-side events that capture automatically regardless of storefront architecture.

Verify events

Confirm events are flowing from your storefront into Upstack.