Headless Event Tracking: What Changes When You Leave the Theme Behind

You went headless. Your storefront is faster, your design is custom, your checkout is still Shopify. But when you check your analytics, half your events are missing. Product views? Gone. Add to carts? Silent. Purchases? Still there. This article explains why — and how to fix it.

The Headless Tracking Divide

When you move from a Shopify theme to a headless storefront (like Hydrogen), event tracking splits into two completely different systems:

What breaks:

• Product page views
• Collection page views
• Search events
• Add to cart
• Cart views
• Any custom storefront interactions

What survives:

• Checkout started
• Payment info submitted
• Checkout completed (purchase)

The reason is architectural: Shopify’s Customer Events (web pixels) only run on Shopify-hosted pages — the Online Store theme and the checkout. Your custom Hydrogen storefront is your own React app, hosted elsewhere, so Shopify’s pixel system never loads there.

This means:

• If you installed pixels via Settings → Customer Events, they fire on checkout but not on your storefront
• Your storefront events need a completely different setup — either Hydrogen’s built-in Analytics components or manual pixel scripts

How Events Travel: Two Separate Pipelines

Headless tracking uses two independent pipelines, depending on where the event happens:

Pipeline 1: Storefront Events (Your React App)

When a shopper browses your Hydrogen storefront, events flow like this:

Hydrogen Component → Analytics.Provider → Shopify Monorail → Shopify Analytics

What fires:

• page_rendered (all pages)
• collection_page_rendered
• product_page_rendered
• product_added_to_cart
• search_submitted

Where it goes:

• Shopify’s internal analytics (Monorail, schema custom_storefront_customer_tracking/1.2)
• Shows up in your Shopify admin Analytics reports
• Does NOT automatically go to GA4, Meta, TikTok, or any third-party platform

To get storefront events into GA4/Meta/TikTok, you have two options (covered in the next section).

Pipeline 2: Checkout Events (Shopify-Hosted)

When a shopper clicks “Checkout,” they leave your Hydrogen storefront and land on Shopify’s hosted checkout domain (checkout.yourstore.com). From this point forward:

Shopify Checkout → Customer Events (Web Pixels) → Your Pixels (GA4, Meta, etc.)

What fires:

• checkout_started
• checkout_contact_info_submitted
• checkout_address_info_submitted
• checkout_shipping_info_submitted
• payment_info_submitted
• checkout_completed (purchase)

Where it goes:

• Any pixel you installed via Settings → Customer Events
• Works exactly like a theme-based store
• Purchase attribution is fully intact — you get complete checkout data even on headless

This is the good news: your conversion tracking doesn’t break. The bad news: everything before checkout needs to be rebuilt.

Two Ways to Send Storefront Events

Your Hydrogen storefront is a React app with no sandbox restrictions. You have two ways to get events into third-party platforms — and you can mix both:

Option 1: Direct Pixel Scripts (Manual)

Load Meta Pixel, gtag, or TikTok Pixel directly in your Hydrogen app, then manually fire events:

// In your product page component
fbq('track', 'ViewContent', {
  content_ids: ['12345'],
  content_type: 'product',
  value: 29.99,
  currency: 'USD'
});

// In your add-to-cart handler
fbq('track', 'AddToCart', {
  content_ids: ['12345'],
  value: 29.99,
  currency: 'USD'
});

Pros:

• Full control over event timing and parameters
• No dependency on Hydrogen’s Analytics components
• Works with any tracking setup

Cons:

• You write every event call manually
• Easy to miss events or send inconsistent data
• You handle consent gating yourself

Option 2: Subscribe to Hydrogen’s Event Bus (Convenience Layer)

Hydrogen’s Analytics components (Analytics.ProductView, Analytics.CartView, etc.) automatically collect standard events. You can subscribe to this event bus and forward everything to your platforms:

import { useAnalytics } from '@shopify/hydrogen-react';

function AnalyticsListener() {
  const { subscribe } = useAnalytics();

  useEffect(() => {
    subscribe('product_page_rendered', (event) => {
      // Forward to Meta
      fbq('track', 'ViewContent', {
        content_ids: [event.products[0].product_id],
        value: event.products[0].price,
        currency: event.currency
      });

      // Forward to GA4
      gtag('event', 'view_item', {
        items: event.products,
        value: event.total_value,
        currency: event.currency
      });
    });
  }, []);
}

Pros:

• Hydrogen collects the data for you (page views, cart contents, product details)
• One central place to forward events to multiple platforms
• Consistent event structure

Cons:

• Only works if you use Hydrogen’s Analytics components
• If you’re not using Analytics.ProductView, there’s nothing to subscribe to
• Still need to handle consent gating

Best practice: Use both. Standard events (page views, add to cart) go through subscribe(). Custom interactions (video plays, form submissions) are fired manually.

Need help figuring out which events to track? Fill out your custom event spec sheet →

Consent: The Hard Gate

Here’s the critical part most guides skip: Hydrogen’s Analytics components check consent before firing anything.

From the Hydrogen source code (analytics.ts):

if (!payload.hasUserConsent) return Promise.resolve();

If you haven’t configured consent, zero events fire. No page views, no add to carts, nothing. This is by design — Shopify enforces privacy compliance at the framework level.

The Official Consent Setup (5 Steps)

Shopify’s recommended approach uses the Customer Privacy API with a native cookie banner:

1. Assign a checkout subdomain — Point checkout.yourdomain.com to your Online Store (Settings → Domains → Target: Online Store, Type: Primary). This ensures consent cookies are shared between your Hydrogen storefront and Shopify checkout.

2. Add environment variable — In Storefront settings → Environments and variables, add PUBLIC_CHECKOUT_DOMAIN (without https://), apply to Production.

3. Configure CSP — Your Content Security Policy must include your store and checkout domains (Hydrogen skeleton includes this by default).

4. Enable the cookie banner — Settings → Customer Privacy → Cookie banner. Choose regions, customize appearance and text.

5. Turn it on in code — Pass withPrivacyBanner: true to Analytics.Provider:

<Analytics.Provider
  shopId="your-shop-id"
  consent={{
    withPrivacyBanner: true,
    country: 'US',
    language: 'en'
  }}
>
  {/* your app */}
</Analytics.Provider>

No Double Consent

Here’s the elegant part: consent is shared between your Hydrogen storefront and Shopify checkout. When a customer accepts cookies on your storefront, they don’t see the banner again at checkout.

The mechanism:

• Shopify stores consent in an HTTP-only cookie on your store domain
• The checkout subdomain setup (step 1) ensures both interfaces share the same cookie
• Regional settings (EEA, UK, etc.) apply uniformly to both

If you skip the checkout subdomain setup, consent doesn’t carry over — and customers see the banner twice. This is why the 5-step setup isn’t optional.

Alternative Consent Solutions

• Third-party CMPs — Consentmo, Pandectes, Avada all support Hydrogen + Customer Privacy API + Google Consent Mode v2
• Custom banner — Build your own consent UI, set consent state manually, gate pixel firing yourself (full flexibility, full compliance responsibility)

Shopify’s official position: “You’re responsible for ensuring that all analytics you’re sending from your Hydrogen site are compliant with consent laws.”

What Hydrogen Actually Sends (Source Code Verification)

From hydrogen-react/src/analytics-schema-custom-storefront-customer-tracking.ts, here’s what Hydrogen’s Analytics components actually track:

Events:

• page_rendered — All pages
• collection_page_rendered — Collection pages
• product_page_rendered — Product pages
• product_added_to_cart — Add to cart
• search_submitted — Search

Fields sent with each event:

Page context:

• canonical_url
• event_source_url (url, path, search params, title)
• referrer
• user_agent
• navigation_type

Shop/user:

• shop_id
• customer_id
• currency

Products (on product/cart events):

• products[] array with product_id, variant_id, variant_gid, sku, name, brand, category, price, quantity
• total_value

Cart:

• cart_token

Privacy flags:

• analytics_allowed
• marketing_allowed
• sale_of_data_allowed
• gdpr_enforced
• ccpa_enforced
• is_persistent_cookie (= hasUserConsent)

Destination: https://{shopDomain}/.well-known/shopify/monorail/unstable/produce_batch (or monorail-edge.shopifysvc.com), schema custom_storefront_customer_tracking/1.2.

This data goes to Shopify’s internal analytics. To get it into GA4/Meta/TikTok, you subscribe and forward (Option 2 above) or send manually (Option 1).

Once the events reach GA4/Meta/TikTok, they need to use the right names — see the complete event name mapping →

FAQ

Do I need to rebuild all my tracking when going headless?

Only your storefront tracking. Checkout events (checkout started, payment submitted, purchase) work exactly like a theme store — they’re handled by Shopify’s Customer Events system. But product views, add to carts, and search events need to be rebuilt using Hydrogen’s Analytics components or manual pixel scripts.

Can I just use Google Tag Manager on Hydrogen?

Yes — GTM works fine on Hydrogen. You can load the GTM script in your root layout and use GTM’s data layer to fire events. But you still need to handle consent gating yourself, and you’ll need to manually push events to the data layer (or use Hydrogen’s useAnalytics().subscribe() to forward them).

What happens if I don't set up consent?

Nothing fires. Hydrogen’s Analytics components check hasUserConsent before sending anything. If consent isn’t configured, you get zero page views, zero add to carts, zero search events. This is intentional — Shopify enforces privacy compliance at the framework level.

Do customers see the cookie banner twice (storefront + checkout)?

Not if you set it up correctly. When you assign a checkout subdomain (checkout.yourdomain.com) and configure the Customer Privacy API, consent is stored in a shared cookie. Customers accept once on your storefront, and the banner doesn’t appear again at checkout.

Can I mix manual pixel scripts with Hydrogen's Analytics components?

Absolutely. Best practice is to use Hydrogen’s Analytics components for standard events (page views, add to cart) and subscribe to forward them to your platforms. For custom interactions (video plays, form submissions), fire events manually with fbq(), gtag(), etc. Just make sure both paths respect consent.

---

Headless tracking architecture verified against Shopify Hydrogen documentation, Customer Privacy API docs, and hydrogen-react source code as of August 2026. Hydrogen is actively developed — if you spot anything outdated, let us know and we’ll update the article.