How Shopify Customer Events work, and what they can’t see

Customer events are how Shopify wants you to track visitors today. Every tracking tool on a modern Shopify store, from the Google & YouTube app to a custom GTM setup, now runs through them. They are reliable and they work on the checkout, but they come with rules that catch people out. Here is how they work, and what they can’t see.

What Customer events are

Shopify watches what visitors do on your store and publishes it as events: a product was viewed, an item was added to the cart, a checkout started, an order was completed. Tracking code doesn’t scrape the page anymore. It subscribes to these events and forwards them to GA4, Meta, Google Ads or any other platform.

You find them in Settings → Customer events. The page lists every pixel installed on your store, its status, and its consent permissions.

The standard events

Event	When it fires	Where
page_viewed	Every page load	Theme and checkout
collection_viewed	A collection page is viewed	Theme
search_submitted	A search is run	Theme
product_viewed	A product page is viewed	Theme
product_added_to_cart	An item is added to the cart	Theme
product_removed_from_cart	An item is removed	Theme
cart_viewed	The cart page is viewed	Theme
checkout_started	The checkout opens	Checkout
checkout_contact_info_submitted	Email or phone submitted	Checkout
checkout_address_info_submitted	Address submitted	Checkout
checkout_shipping_info_submitted	Shipping method chosen	Checkout
payment_info_submitted	Payment details submitted	Checkout
checkout_completed	The order is placed	Thank-you page, or the first upsell page

Each event carries data: the product and variant with prices, the cart lines, or the full checkout with line items, discounts, shipping, taxes and the order ID. It also carries context: the page URL, referrer and title, and a Shopify client ID.

Shopify also publishes DOM events (clicks, form submissions, input changes) and lets your theme or apps publish custom events, for example a newsletter sign-up, with Shopify.analytics.publish().

App pixels and custom pixels

• App pixels come with an app: the Google & YouTube app, Facebook & Instagram, TikTok, Pinterest, Klaviyo or a tracking app. You configure them inside the app.
• Custom pixels are code you paste yourself in Customer events, typically to load Google Tag Manager or a platform that has no app.

Both subscribe to the same events. The difference is the sandbox they run in.

The sandbox: strict and lax

Shopify never lets pixel code run directly on your pages. It isolates it:

• App pixels run in a strict sandbox (a web worker). No page, no DOM, no window. They can only receive events and send data out.
• Custom pixels run in a lax sandbox (a hidden iframe). They have their own small page, so they can load scripts like GTM, but that page isn’t your store’s page.

In practice, inside a custom pixel:

• window.location and document.title describe the sandbox iframe, not your store. Use event.context.document instead.
• The dataLayer is the pixel’s own. Your theme’s dataLayer, if you have one, is a different object, and the two GTM containers don’t share variables.
• Cookies are read and written with Shopify’s browser.cookie API, which is asynchronous.
• You can’t add elements to the page, read form fields, or watch clicks on specific buttons, other than through DOM events.

Here is the pattern to send the right page data:

analytics.subscribe("page_viewed", (event) => {
  const doc = event.context.document;
  window.dataLayer.push({
    event: "page_view",
    page_location: doc.location.href,
    page_referrer: doc.referrer,
    page_title: doc.title
  });
});

Consent and pixels

Each pixel has permission settings. You choose whether it needs analytics, marketing or preferences consent, and whether its data counts as a sale of data under US privacy laws. If a pixel needs a permission the visitor hasn’t given, Shopify doesn’t load it at all.

This only works if your cookie banner tells Shopify about the visitor’s choice through the Customer Privacy API. Shopify’s own banner does it automatically, and most banner apps built for Shopify do too. A banner that only blocks scripts in the theme does nothing for pixels. I explain the full chain in Consent Mode v2 on Shopify.

What Customer events can’t see

• Your theme’s content. A custom pixel can’t read a product badge, a size selector or a value printed in the page. If you need it, publish a custom event from the theme with the data attached.
• Specific clicks and widgets. DOM events report clicks and form submissions in general terms. For a precise interaction (a size guide opened, a filter used), publish a custom event.
• Extra checkout fields. Data added by checkout UI extensions (a gift message, a delivery date) isn’t in the standard checkout object. The extension must publish it.
• Payments and refunds after the order. Customer events stop at checkout_completed. Refunds, cancellations and subscription renewals happen on Shopify’s servers and need webhooks or a server-side integration.
• Other sales channels. POS sales and many marketplace orders never go through the online store, so pixels never see them.
• Some third-party checkouts and upsell apps. If a funnel leaves Shopify’s checkout, check that it still publishes the standard events.
• Visitors without consent. If the pixel requires consent, it sees nothing until the visitor accepts.

Common surprises

• Purchase fires on the upsell page. With a post-purchase upsell app, checkout_completed fires on the first upsell page, not the thank-you page. Accepted upsells may not be included in the purchase value.
• Cart events from drawers. Some themes add to cart without a page reload in a way that doesn’t trigger product_added_to_cart. Test your theme’s own add-to-cart buttons, including quick-add on collection pages.
• GTM preview doesn’t connect. GTM’s Tag Assistant struggles to attach to a container running in the sandbox iframe. Test with Shopify’s Pixel Helper (available from the Customer events page), GA4’s DebugView, the browser console and real orders.
• Pixel disconnected. If a pixel is saved but not connected, it doesn’t run. Check its status on the Customer events page after every edit.

Frequently asked questions

What is the difference between Customer events and the Web Pixels API?

Customer events is the admin page and the events Shopify publishes. The Web Pixels API is the developer interface that pixels use to subscribe to those events, read cookies and receive consent.

Are custom pixels available on all Shopify plans?

Yes. Custom pixels and app pixels work on all plans. Checkout UI extensions on the information, shipping and payment steps are the Plus-only part.

Why is my dataLayer undefined on the checkout?

The theme’s dataLayer doesn’t exist in the pixel sandbox, and the pixel’s own dataLayer only exists if the pixel is connected and defines it. Check the pixel status, and inspect the sandbox frame in the console rather than the main page.

Do custom pixels slow down my store?

Pixels load in a sandbox, separately from your theme’s rendering, so their impact on page speed is limited compared with scripts in theme.liquid. Heavy containers still add network requests, so keep GTM tidy.

Where to go next

To put this into practice, the full code is in building a full ecommerce dataLayer from a Shopify custom pixel, and the checkout specifics are in how to track Shopify checkout inside the pixel sandbox. If you’d rather have it done, my Shopify tracking packages start at 1,300€, or you can book a free 30-minute call.