Skip to main content
When your marketing funnel extends beyond your Shopify storefront — landing pages, subdomains, headless commerce frontends, WordPress sites, or third-party quiz/survey platforms — you need to install the Upstack Pixel manually to capture events and maintain attribution continuity. This guide covers two implementation methods:
  • Direct installation — Add the pixel script directly to your page’s HTML
  • Google Tag Manager (GTM) — Deploy via your GTM container for centralized tag management
For the full event payload reference — including all required and optional properties — see Standard Events Reference and Properties & Context.

​
When You Need This Guide

Install the Upstack Pixel manually when you have:
  • Landing pages — Unbounce, Instapage, Webflow, Carrd, or custom HTML pages
  • Subdomains — shop.yourdomain.com or promo.yourdomain.com running outside Shopify
  • Headless storefronts — Custom React, Next.js, or Vue frontends using Shopify’s Storefront API
  • WordPress / WooCommerce — Sites that redirect to Shopify checkout
  • Quiz or survey tools — Octane AI, Typeform, or Jotform funnels
  • Third-party checkout platforms — Checkout Champ, ClickFunnels, or custom checkout flows

​
Prerequisites

  • An Upstack Data account with the Upstack Data app installed on your Shopify store
  • 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 site or landing page (admin access in your page builder, CMS, or GTM container)

​
Step 1: Find Your Upstack Pixel ID

Your Upstack Pixel ID is a unique identifier linked to your Shopify store. This ID connects browser events from external sites to your Upstack account. For step-by-step instructions, see: How to find my Upstack Data Pixel ID?

​
Step 2: Choose Your Implementation Method

Add the pixel script directly to your page’s <head> section. This is the simplest approach for landing pages and sites without a tag manager.

​
Base Pixel Snippet (Required on Every Page)

<!-- START Upstack Script Tag -->
<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 Upstack Script Tag -->
Replace YOUR_PIXEL_ID with the Pixel ID you obtained in Step 1 (UUID format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

​
Step 3: Track Events

Beyond page views, you’ll want to track key conversion events. Each event follows the same pattern: 
window._upstack('track', 'event_name', { /* event properties */ });
For the complete list of standard events and their required properties, see the Standard Events Reference.

​
Event Snippets Reference

Fires when a visitor views a product or content page.
<script>
  window._upsqueue = window._upsqueue || [];
  window._upstack = window._upstack || function () {
    window._upsqueue.push(arguments);
  };
  window._upstack('track', 'view_content', {
    value: 100,           // product price
    currency: 'USD',      // ISO 4217 currency code
    items: [{
      id: '1234',         // product id
      quantity: 1,
      name: 'Product 1',
      price: 100,
      variant: '1234',    // variant id
    }],
  });
</script>
Required properties: value, currency, itemsSee ViewContent in Standard Events for the full specification.
Fires when a visitor adds an item to their cart.
<script>
  window._upsqueue = window._upsqueue || [];
  window._upstack = window._upstack || function () {
    window._upsqueue.push(arguments);
  };
  window._upstack('track', 'add_to_cart', {
    value: 100,
    currency: 'USD',
    items: [{
      id: '1234',
      quantity: 1,
      name: 'Product 1',
      price: 100,
      variant: '1234',
    }],
  });
</script>
Required properties: value, currency, itemsSee AddToCart in Standard Events for the full specification.
Fires when a visitor starts the checkout flow.
<script>
  window._upsqueue = window._upsqueue || [];
  window._upstack = window._upstack || function () {
    window._upsqueue.push(arguments);
  };
  window._upstack('track', 'initiate_checkout', {
    value: 100,
    currency: 'USD',
    items: [{
      id: '1234',
      quantity: 1,
      name: 'Product 1',
      price: 100,
      variant: '1234',
    }],
    // Optional but recommended identity fields
    email: 'customer@example.com',
    phone: '+15551234567',
    firstName: 'Jane',
    lastName: 'Doe',
    addresses: [{
      address1: '123 Main St',
      city: 'New York',
      province: 'New York',
      provinceCode: 'NY',
      zip: '10001',
      country: 'United States',
      countryCode: 'US',
    }],
  });
</script>
Required properties: value, currency, itemsRecommended: Include identity fields (email, phone, firstName, lastName) to improve destination match quality.See InitiateCheckout in Standard Events for the full specification.
Fires when an order is completed. This is the most important conversion event.
<script>
  window._upsqueue = window._upsqueue || [];
  window._upstack = window._upstack || function () {
    window._upsqueue.push(arguments);
  };
  window._upstack('track', 'purchase', {
    transactionId: 'order_12345',
    orderId: 'order_12345',
    orderName: '#1042',
    value: 100,
    currency: 'USD',
    items: [{
      id: '1234',
      quantity: 1,
      name: 'Product 1',
      price: 100,
      variant: '1234',
    }],
    email: 'customer@example.com',
    phone: '+15551234567',
    firstName: 'Jane',
    lastName: 'Doe',
    addresses: [{
      address1: '123 Main St',
      city: 'New York',
      province: 'New York',
      provinceCode: 'NY',
      zip: '10001',
      country: 'United States',
      countryCode: 'US',
    }],
  });
</script>
Required properties: transactionId or orderId, value, currency, itemsRecommended: Include all identity fields for maximum match quality at destinations.See Purchase in Standard Events for the full specification.
Fires when a visitor submits a lead form, quiz, or survey.
<script>
  window._upsqueue = window._upsqueue || [];
  window._upstack = window._upstack || function () {
    window._upsqueue.push(arguments);
  };
  window._upstack('track', 'lead', {
    email: 'customer@example.com',
    phone: '+15551234567',
    firstName: 'Jane',
    lastName: 'Doe',
  });
</script>
Required properties: At least one identity field (email or phone)See Lead in Standard Events for the full specification.
Fires when a visitor subscribes to email or SMS marketing.
<script>
  window._upsqueue = window._upsqueue || [];
  window._upstack = window._upstack || function () {
    window._upsqueue.push(arguments);
  };
  window._upstack('track', 'subscribe', {
    email: 'customer@example.com',
    phone: '+15551234567',
  });
</script>
See Subscribe in Standard Events for the full specification.

​
Step 4: Preserve UTM Parameters Across Pages

If your landing page links to your Shopify store or checkout, preserve UTM parameters and click IDs to maintain attribution continuity. Add this script to automatically append the current page’s query string to all outbound links: 
<script>
  function addCurrentQueryStringToLinks() {
    var currentQueryString = window.location.search.slice(1);
    if (!currentQueryString) return;
    var links = document.getElementsByTagName('a');
    for (var i = 0; i < links.length; i++) {
      var link = links[i];
      var href = link.href;
      if (href.startsWith('#')) continue;
      if (href.indexOf('?') !== -1) {
        href += '&' + currentQueryString;
      } else {
        href += '?' + currentQueryString;
      }
      link.href = href;
    }
  }
  window.addEventListener('load', addCurrentQueryStringToLinks);
</script>
This ensures fbclid, gclid, ttclid, and UTM parameters flow through to Shopify checkout.

​
Step 5: Verify Your Installation

  1. Visit your site and trigger each event you configured (page view, lead capture, purchase, etc.)
  2. Use the Pixel Helper — Install the Upstack Data Pixel Helper browser extension to confirm events fire with the expected parameters
  3. Check Event Health — In the Upstack dashboard under Event Health, confirm events arrive with your Pixel ID and correct properties
If using GTM, use Preview / Debug mode to verify tags fire on the correct triggers before publishing.

​
Platform-Specific Guides

Landing Pages & Subdomains

Quick setup for Unbounce, Instapage, Webflow, and custom landing pages.

Checkout Champ

Full integration guide for Checkout Champ implementations.

​
Reference Documentation

Event Taxonomy

Overview of the Upstack event model and how events flow through the pipeline.

Standard Events

Complete specification for every standard event — required properties, optional fields, and example payloads.

Properties & Context

Full reference for user data, custom data, and context fields attached to events.

Custom Events

Define your own events for interactions beyond the standard taxonomy.
Health and Wellness stores: If you’re in the health/wellness category and need to use custom event names for platform compliance, see Health and Wellness Custom Event Mappings →