Shopify Customer Events Explained (and How to Track Them with Custom Pixels)

Introduction

Shopify Customer Events are signals Shopify emits when customers interact with your store  e.g. viewing products, adding to cart, starting checkout or completing a purchase.

This system replaced old tracking methods like checkout.liquid and thank you/order status scripts

In this guide, we’ll cover the technical setup for custom web pixels: capturing these events and sending them to third-party platforms via the Customer events Javascript sandbox.

For a lot of use cases tracking setup can be done via App Web pixels (using apps), however should you require a more custom setup the custom web pixel will work.

Note: this article is about Custom Web Pixels not App Web Pixels.

Figure 1 - Custom Web Pixels

How Custom Pixels Work?

A Custom Web Pixel in Shopify is a sandboxed JavaScript snippet configured inside the Pixel Manager.

It listens to specific customer events (like checkout_completed) and sends those events to external platforms e.g. Meta, TikTok, GA4, your own server.

Figure 2. Custom Web Pixel Sandbox

Key Concepts

  • Sandboxed environment: Runs isolated from storefront theme code.

  • No external libraries: jQuery or other imports aren’t allowed - native JS only.

  • No HTML: <script> tags must be rewritten in plain JS.

  • Web Pixel API: The custom pixel uses the Web Pixels API to track checkout events and interact with the DOM and browser.

  • Replaces old tracking: via checkout.liquid and order status/thank you page scripts.

Tracking flow

Custom pixels typically have 3 steps:

  1. Initialize third-party SDK e.g. Meta
  2. Subscribe to events with analytics.subscribe()
  3. Send payload to third party

Events You Can Capture

Events you can capture to include:

  • page_viewed

  • product_added_to_cart

  • checkout_started

  • payment_info_submitted

  • checkout_completed 

Full list: Shopify Standard Events


Event Payloads

Each event gives you structured data e.g.:

  • Order details: totalPrice, currencyCode, token.

  • Products: lineItems[] with name, quantity, price, variant ID.

  • Customer info: email, phone, marketing opt-ins.

  • Addresses: shipping + billing.

The structured data received depends on the event, so be sure to check the data available for the event via Shopify standards events docs or by logging the event payload (see Basic Pixel Script Structure below).

Basic Pixel Script Structure

analytics.subscribe("checkout_completed", (event) => {
  console.log("Checkout completed:", event);
});

Data Access Helpers

You can access:

  • Cookies: browser.cookie.get("_landing_page")

  • Storage: browser.localStorage.getItem("foo")

  • Session: browser.sessionStorage.getItem("foo")

See browser object for more details.


init object

  • init.context -> browser + page signals (referrer, userAgent, window size).

  • init.data -> Shopify objects like cart + customer.

See init object for more details.

 

DOM Events

Custom pixels can also track DOM interactions in checkout:

analytics.subscribe("clicked", (event) => {
  console.log("Clicked element:", event.data.element.id);
});

See DOM events for more details.

 

Customer Privacy

 Shopify enforces GDPR, but we must check init.customerPrivacy to avoid sending data the customer hasn’t consented to.

  • GDPR (EEA/UK): Pixel only runs if user opts in (Shopify determine this).

  • CCPA (California): Runs by default but block “data sale” if opted out.

  • Use init.customerPrivacy flags to check before sending. For more detail see Customer Privacy API.

Sending Event Payloads

Once subscribed to events, build a payload and forward it to your third-party endpoint or server. Keep it lean (only send fields you need) and always respect init.customerPrivacy.

analytics.subscribe("checkout_completed", (event) => {
  const privacy = init.customerPrivacy; 
 // Only send if marketing allowed (GDPR) and data sale allowed (CCPA) 
if (privacy.marketingAllowed && privacy.saleOfDataAllowed) {
    fbq("track", "Purchase", {
      value: event.data.totalPrice,
      currency: event.data.currencyCode,
      content_ids: event.data.checkout.lineItems.map(i => i.variant.id),
      content_type: "product",
    });
  } else {
    console.log("Meta Pixel blocked due to consent:", privacy);
  }
});

See another checkout_completed event example here.

Server-side flow

If you have the ability to setup a custom server side, to handle sending to third parties (e.g. Meta, Tiktok etc) I'd recommend this approach because:

  • Deduplication: Use a stable event_id (e.g. checkout.token/order id).
  • Secrets: Keep API keys off the client.
  • Reliability: Queue + retry; isolate vendor outages.


High level server side flow:

1) Pixel sends lean event to server
2) Server validates, checks consent, idempotency store, normalizes.
3) Enqueue jobs to Meta CAPI, TikTok Events, GA4 
4) Workers call vendors with retries and monitoring.

Debugging Custom Pixels

Debugging ensures your pixel fires correctly and data reaches third parties.

  • Shopify Pixel Debugger: In Admin -> Settings -> Customer events -> Test, trigger actions (view product, add to cart, checkout) and inspect events + payloads in real time.

  • Console logs: Add console.log(event) in your subscriptions to see payloads.

  • Network tab: Check requests to third-party endpoints (e.g. facebook.com/tr/, analytics.tiktok.com, or your server).

  • Platform tools:

Conclusion

When Shopify retired checkout.liquid and order status scripts, I had to rebuild tracking from scratch across multiple client stores. This post is a distilled version of what I learned in the process as a Shopify freelancer.

For a ready-to-use custom pixel reference with GDPR/CCPA-safe snippets for Meta, TikTok, and Bing grab my free cheatsheet:

👉 Shopify Pixel Cheatsheet (Meta, TikTok, Bing)