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 example on WordPress sites
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
  • Page builders — Replo or similar builder pages (landing, thank-you, or custom storefront pages) where the Pixel Helper doesn’t show Upstack events firing
  • Funnel builders — Funnelish or similar tools that host funnel pages outside your Shopify theme
  • Subdomains — shop.yourdomain.com or promo.yourdomain.com running outside Shopify
  • Alias or secondary domains — pages served on a secondary domain (for example, mystorealias.com when mystore.com is your primary domain)
  • 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, static host, or GTM container). For direct installation, you also need to be able to add code to the page’s <head> section (usually a Custom Code or Header Code area)

​
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. In most page builders and landing page tools, paste it into the Custom Code or Header Code area. This is the simplest approach for landing pages and sites without a tag manager.

​
Base Pixel Snippet (Required on Every Page)

Replace YOUR_PIXEL_ID with the Pixel ID you obtained in Step 1 (UUID format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX). Enter the ID exactly as shown — extra spaces or mismatched quotation marks break tracking.
After you paste the snippet, save and republish the page so the script goes live.For where to paste the snippet in a specific page builder or funnel app, see Platform-Specific Guides.
Load the pixel script with async (as in the snippet above), not defer, or the pixel can miss visitors who leave the page quickly. See Check your script tag configuration.

​
Step 3: Track Events

Beyond page views, you’ll want to track key conversion events. The values in the snippets below are samples only — populate them dynamically with your product, checkout, and order details (for example, with GTM variables or your site’s template code). Each event follows the same pattern:
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.
Required properties: value, currency, itemsSee ViewContent in Standard Events for the full specification.
Fires when a visitor adds an item to their cart.
Required properties: value, currency, itemsSee AddToCart in Standard Events for the full specification.
Fires when a visitor starts the checkout flow.
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.
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.
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.
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:
This ensures fbclid, gclid, ttclid, and UTM parameters flow through to Shopify checkout. If a page builder or funnel app redirects visitors to checkout, also check that its redirect settings keep fbclid and the other parameters in the redirect URL.

​
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. When the page URL includes a click ID such as fbclid, confirm the click ID appears in the event details
  3. Check Events Manager — In the Upstack dashboard under System → Events Manager, 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

Each guide covers only what’s specific to that app, such as where to paste the snippet, and points back here for everything else.

Set Up Checkout Champ

Add the pixel in Checkout Champ’s Global Scripts and turn off its Facebook pixel.

Set Up Funnelish

Add the pixel as a head tracking code in each funnel and turn off its Meta pixel.

Set Up Replo

Check whether your theme already covers Replo pages, then add the pixel in Replo.

​
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: Health & Wellness custom event mappings are deprecated (January 2026). See how Upstack handles Meta’s Health & Wellness restrictions.