Shopify Customer Events and Custom Pixels: Setup, Consent and Testing

Shopify customer events are the actions shoppers take in their browser, such as viewing a product, adding it to the cart or completing checkout. You collect them with pixels, which you manage in Settings > Customer events. App pixels arrive with apps and sales channels, such as Google & YouTube. Custom pixels are JavaScript you paste in yourself. Both are web pixels built on Shopify's Web Pixels API.

Both kinds run in a Shopify sandbox on the storefront, checkout, Thank you and Order status pages, and both follow the visitor's consent. In regions that require consent, a pixel loads only after the visitor has given every permission it needs. Customer events replace tracking code that used to live in theme.liquid, checkout.liquid and the Additional scripts box.

This guide follows Shopify's documentation as of October 2026. It is general information, not legal advice.

What are Shopify customer events?

Shopify's pixels overview defines customer events as actions that happen in the customer's browser. Shopify publishes each event to an event bus. A pixel subscribes to the events it needs and reshapes the data for the analytics or ad platform it feeds, as the web pixels developer guide explains.

Settings > Customer events is the admin page for this. Shopify calls it the pixels manager. It lists each pixel and whether it is connected. According to the overview, pixels load automatically on:

• the online store
• checkout
• the Thank you page
• the Order status page
• customer account pages, but only once you connect a custom subdomain for customer accounts, and only the page_viewed event is tracked there

One catch on the Order status page, which now sits in customer accounts: if your store uses a custom domain, Shopify's guide to replacing additional scripts says the customer account domain must be a subdomain of it, such as account.example.com, or pixels and cookie consent won't work there.

The page lists your pixels and their status. To watch the events themselves arrive as you browse, use the Pixel Helper described in the testing section below.

Don't confuse customer events with Shopify's Events API. The Events API lets apps subscribe to changes in store data, such as product updates, through server-side deliveries. Customer events describe what shoppers do in the browser.

What's the difference between app pixels and custom pixels?

Shopify's custom pixels guide says to use an app pixel when one meets your needs and fall back to a custom pixel when none does. It also states that adding and using custom pixels is unsupported by Shopify, so troubleshooting falls to you or a Shopify Partner.

The privacy rows follow Shopify's app pixels guide and custom pixel guide.

For Meta and Google, Shopify's pixel migration guide recommends the Facebook & Instagram and Google & YouTube channels. As of February 2025, Meta pixels and Google Universal Analytics tags that weren't set up through those apps were removed from the Preferences page and converted to custom pixels. Shopify warns that this may reduce measurement performance and features. If you find a custom pixel nobody remembers adding, that's a likely origin.

What does the data access setting on app pixels do?

Each app pixel's detail page has a data access setting. With Optimized, the default since a January 2026 change, Shopify can pause data sharing with a marketing pixel that isn't driving traffic or sales, and resumes it when those signals return. Analytics app pixels can't be optimized and stay on Always on. To see what changed, click More options > View details on the pixel; the activity log starts on 3 June 2026.

What can a pixel do inside Shopify's sandbox?

Every pixel in Customer events runs in a sandbox, an isolated environment that keeps its code away from the rest of your store. That isolation explains most "my pixel doesn't work" reports. According to Shopify's pixels overview and developer guide, sandboxed pixels:

• Can't render anything. No buttons, forms, banners or popups.
• Can't read the page. The strict sandbox has no DOM at all. The lax sandbox can't reach the top frame, so DOM scraping, outbound link clicks, scroll depth and heatmaps aren't detected automatically.
• See the wrong URL. In the lax sandbox, the window's own address is the sandbox, not your store page. Read the page address from event.context.document.location.href instead.
• Run only JavaScript. Shopify's custom pixel code guide says to remove HTML and <noscript> fallbacks from vendor code.

There are two workarounds. DOM events (clicked, form_submitted, input_blurred, input_changed and input_focused) work on the storefront, checkout and Thank you pages, but not on customer account or Order status pages. Custom events, covered below, let your theme publish anything else.

Google Tag Manager can run as a custom pixel, but the same limits apply. Shopify's GTM tutorial also notes that Tag Assistant's Troubleshoot tag feature can't detect tags inside a custom pixel.

Which standard events can a pixel subscribe to?

Shopify's standard events reference lists 15 events. Subscribe to each by name with analytics.subscribe().

The last two arrived in an October 2024 update. They capture alerts buyers see, such as field validation messages, and errors from checkout UI extensions.

What matters most for checkout tracking?

Two details:

• checkout_completed fires once per checkout, usually on the Thank you page. With a post-purchase upsell, Shopify's checkout_completed reference says it fires on the first upsell page and not again on the Thank you page. If that page fails to load, the event doesn't fire.
• Bulk subscriptions can change. The Web Pixels API overview offers all_events, all_standard_events, all_custom_events and all_dom_events, but warns their contents may change. Name each event you forward, so new event types don't reach your tools unannounced.

How do pixel privacy settings follow customer consent?

Consent travels through three steps:

1. Your cookie banner, whether Shopify's own or a consent app, records the visitor's choice in Shopify's Customer Privacy API.
2. The pixel manager reads that choice for every pixel.
3. Each pixel loads only if the visitor allowed everything it requires.

The API tracks four purposes: analytics, marketing, preferences and sale of data. In regions that require consent, non-essential purposes aren't allowed until the visitor consents. Elsewhere, all purposes are allowed by default. You choose the consent regions in Settings > Customer privacy. Our guide to the Shopify Customer Privacy API covers regions, defaults and console checks.

Which privacy settings does a custom pixel have?

Each custom pixel has a Customer privacy section with two settings:

• Permission. Choose Required and select the purposes the pixel needs (marketing, analytics, preferences), or choose Not required. Shopify notes that to request consent at all, your store needs a cookie banner.
• Data sale. Pick the data sale collection permissions that fit the pixel. The code guide says pixels set up for data sale don't run for customers who opted out of data sale or sharing, unless the pixel supports limited data use.

New custom pixels require Marketing and Analytics and are treated as data sale by default. Match each pixel to what its tool actually does. A pure analytics tool may need only Analytics, while an ad pixel needs Marketing. Not required means the pixel runs before any choice is made, so only use it after confirming the tool doesn't need consent where you sell. Our guide to what Shopify merchants still have to do under the GDPR covers the wider obligations.

Who sets an app pixel's privacy settings?

App developers declare permissions in a [customer_privacy] block of the pixel's configuration. The pixel privacy docs say the pixel loads only if the visitor has granted every setting marked as required. To see them, click More options > View customer privacy on the pixel. If the settings don't fit how you use the app, ask the developer, because you can't edit them. When consent arrives mid-visit, the developer guide says app pixel callbacks then run and earlier events on the page are replayed.

How can a pixel read consent itself?

A pixel can also read the choice itself, which is useful for a pixel set to Not required or one that sends extra data only with marketing consent:

let consent = init.customerPrivacy

api.customerPrivacy.subscribe('visitorConsentCollected', (event) => {
  consent = event.customerPrivacy
})

analytics.subscribe('product_added_to_cart', (event) => {
  if (!consent.marketingAllowed) return
  // Forward the event to your ad platform here.
})

In a custom pixel, init and api are ready to use. An app pixel gets customerPrivacy from register() and calls customerPrivacy.subscribe() instead, as the pixel privacy docs show. Besides marketingAllowed, the consent object has analyticsProcessingAllowed, preferencesProcessingAllowed and saleOfDataAllowed. For Google tags, our Google Consent Mode v2 on Shopify guide explains how to map these choices to Google's consent types.

A third-party banner must write each choice to the Customer Privacy API, or pixels won't hear about it. ShopOpsy's Cookify, whose Shopify App Store listing is pending, passes every choice to that API, so pixels in Customer events follow the same decision. It doesn't hold script tags written directly into theme code, which is one more reason to move those into Customer events. To choose a banner, see our comparison of Shopify's cookie banner and consent apps.

How do you add a custom pixel in Shopify?

These steps follow Shopify's custom pixel management guide. Labels can differ slightly between admin versions.

1. Remove the old code first. Find the same tracker in theme.liquid, checkout.liquid (Plus only) and Additional scripts, and plan to remove it. Otherwise events may be counted twice.
2. Go to Settings > Customer events.
3. Give the pixel a unique name, then click Add pixel to open the event editor.
4. In Customer privacy, set Permission and Data sale.
5. Paste your JavaScript into the Code window.
6. Click Save, then Connect pixel when you're ready to track. Shopify asks you to confirm the pixel meets the service requirements in its Terms of Service.
7. Test it, as described below, before you trust the numbers.

To pause a pixel, open the Custom pixels tab and click Disconnect. That stops tracking without deleting the code. If the pixel's tool sets cookies, list it in your Shopify cookie policy too.

What does a minimal custom pixel look like?

This pixel sends page views and completed purchases to an endpoint you control. Replace the URL with your own.

const ENDPOINT = 'https://example.com/collect'

function send(payload) {
  fetch(ENDPOINT, {
    method: 'POST',
    body: JSON.stringify(payload),
    keepalive: true,
  })
}

analytics.subscribe('page_viewed', (event) => {
  send({
    event: event.name,
    eventId: event.id,
    url: event.context.document.location.href,
  })
})

analytics.subscribe('checkout_completed', (event) => {
  const checkout = event.data.checkout
  send({
    event: event.name,
    eventId: event.id,
    orderId: checkout.order?.id,
    value: checkout.totalPrice?.amount,
    currency: checkout.currencyCode,
  })
})

A few notes:

• analytics, browser and init are already available in a custom pixel. App pixels get them through register(), as the Web Pixels API overview shows.
• The checkout_completed reference says the order ID is null on every event except checkout_completed. Since 10 December 2025, app pixels receive name, email, phone and address fields only if the app is approved for the matching protected customer data scopes. Shopify's changelog entry says custom pixels are out of scope for that change.
• keepalive: true tells the browser not to abort the request if the page unloads first, as MDN's fetch reference explains. MDN also notes that keepalive bodies are limited to 64 KiB, so keep payloads small. Shopify's own checkout_completed examples send data the same way.
• The example doesn't set a Content-Type header, so set up your endpoint to parse the raw request body as JSON.

To install a vendor's tag instead, follow the vendor's instructions, but turn any <script src> tag into JavaScript that builds the script element, and drop the vendor's own initial page view. Then send events from analytics.subscribe() callbacks, as Shopify's code guide describes.

How do you send custom events from your theme?

For anything the standard events miss, such as a size guide click, publish a custom event from your theme's JavaScript:

Shopify.analytics.publish('my_store:size_guide_opened', {
  productHandle: 'linen-shirt',
})

Then subscribe to it by name in the pixel and read the payload from event.customData. Shopify's custom events docs recommend a prefix like my_store: to avoid name collisions. They also warn that anyone can publish custom events from the browser console, so don't treat them as trusted data. Standard events can't be published this way.

How do you migrate from additional scripts and checkout.liquid?

If your conversion tracking still lives in checkout code, the deadlines have passed:

Shopify's script tag docs name web pixels as the replacement for analytics and conversion tracking, and the upgrade guide says customizations are replaced when the pages are upgraded. If old tracking still shows in Additional scripts, treat it as unreliable and rebuild it as a pixel. For what customers now see after checkout, read our guide to the Shopify order status page.

The pixel migration guide sets out this order:

1. Map what you have. For each tracker, find the base JavaScript SDK, usually in the header, and the event calls, such as fbq(), gtag() or dataLayer.push().
2. Pick the path. If an app pixel covers the tool and you added no extra code, there is nothing to rebuild. Otherwise, write a custom pixel that subscribes to the events you need.
3. Replace custom events. Swap calls like fbq("trackCustom", "my_custom_event") in your theme for Shopify.analytics.publish("my_custom_event"), and subscribe to them in the pixel.
4. Choose your cutover. Connect the new pixel before removing the old code to miss fewer events, or after to avoid duplicates.
5. Remove every leftover. Check Additional scripts, checkout.liquid and theme.liquid for the old SDK.
6. Compare. Make sure each event fires once and the Customer privacy settings match your old consent behavior.

Stores that missed the deadline were upgraded automatically, so their old scripts no longer run on those pages. If an upgrade notice still appears in Settings > Checkout, click Review in it; the upgrade guide groups your old scripts by purpose so you can replace each one.

How do you test customer events and custom pixels?

Shopify's testing guide uses the Shopify Pixel Helper, a tool Shopify launched in June 2024 that shows events as they arrive.

1. Check the status. In Settings > Customer events, the Status column should say Connected.
2. Open the helper. Click the custom pixel, then Test. Your store opens with the Pixel helper dialog.
3. Handle consent. "Pixel is awaiting consent" means it's waiting for permission. Accept in your banner or click Give consent to continue test. If it still doesn't load, review Settings > Customer privacy.
4. Walk the funnel. View a page, a product and the cart, start checkout and enter shipping details. Watch Events received. A green dot means the callback ran; a red dot means it failed, and expanding the event shows the error.
5. Complete a test purchase to see checkout_completed. Shopify's test orders guide covers a test payment gateway and Shopify Payments test mode. Customers can't place live orders while your payment providers are in test mode, so switch back afterwards.
6. Check the network. In developer tools, confirm the vendor's requests go out. For console errors in Chrome, select the pixel's iframe to filter logs.
7. Test consent both ways. From a consent region, in a private window, reject and confirm nothing reaches the vendor. Then accept and confirm events arrive. A test from outside your consent regions passes even when consent handling is broken.

The helper tests one custom pixel at a time, clears its log on each new page, and doesn't let you edit the pixel while it runs. It isn't compatible with headless stores or stores in private mode, and Shopify suggests turning private mode off while you test.

To check what the destination received, use its own debug view. Our GA4 conversion tracking checklist covers DebugView and reconciling purchases with Shopify orders.

Why is a pixel not firing or counting twice?

After a migration, small dips are normal. The pixel migration guide expects single-digit percentage drops because some bots don't trigger the sandbox, and says larger gaps are worth investigating. In consent regions, part of a larger drop can be visitors who declined, but first rule out a banner that doesn't sync with the Customer Privacy API.

Frequently asked questions

Do I need Shopify Plus to track checkout with pixels?

No. Shopify's pixels overview says pixels load automatically on checkout, the Thank you page and the Order status page, and its script tag docs say web pixels work on any store. checkout.liquid was the Plus-only option, and it no longer runs on any checkout page.

Which staff permissions does someone need to manage pixels?

Shopify's store permissions list has two under Store settings. View customer events lets a staff member see app pixels and custom pixels. Manage and add custom pixels lets them create and change custom pixels. Give an agency or vendor only the access its task needs.

Should I install Google Tag Manager as a custom pixel?

Only if you need it and can maintain it. Shopify's GTM tutorial says to review available apps first. Its example sets ad_storage, analytics_storage, ad_user_data and ad_personalization to granted, and Shopify notes this might not match your region's privacy law, so set consent from the visitor's real choice instead.

Sources

• Pixels overview — Shopify Help Center, accessed 26 October 2026.
• Custom pixels — Shopify Help Center, accessed 26 October 2026.
• Managing custom pixels — Shopify Help Center, accessed 26 October 2026.
• Creating custom pixel code — Shopify Help Center, accessed 26 October 2026.
• Testing custom pixels — Shopify Help Center, accessed 26 October 2026.
• Create a Google Tag Manager custom pixel — Shopify Help Center, accessed 26 October 2026.
• App pixels — Shopify Help Center, accessed 26 October 2026.
• Pixel migration — Shopify Help Center, accessed 26 October 2026.
• Non-Plus: Upgrading and replacing your Thank you and Order status pages — Shopify Help Center, accessed 26 October 2026.
• Upgrading and replacing your Thank you and Order status pages — Shopify Help Center, accessed 28 October 2026.
• Reviewing and replacing additional scripts on your Thank you and Order status pages — Shopify Help Center, accessed 28 October 2026.
• Placing a test order — Shopify Help Center, accessed 26 October 2026.
• Store permissions — Shopify Help Center, accessed 26 October 2026.
• Web pixels — Shopify developer documentation, accessed 26 October 2026.
• Web Pixels API — Shopify developer documentation, accessed 26 October 2026.
• Standard events — Shopify developer documentation, accessed 26 October 2026.
• checkout_completed — Shopify developer documentation, accessed 26 October 2026.
• DOM events — Shopify developer documentation, accessed 26 October 2026.
• Emitting data — Shopify developer documentation, accessed 26 October 2026.
• Pixel privacy — Shopify developer documentation, accessed 26 October 2026.
• Customer Privacy API — Shopify developer documentation, accessed 26 October 2026.
• checkout.liquid — Shopify developer documentation, accessed 26 October 2026.
• Order status script tags — Shopify developer documentation, accessed 26 October 2026.
• Events — Shopify developer documentation, accessed 26 October 2026.
• Web pixels now support checkout error events — Shopify developer changelog, accessed 26 October 2026.
• Protected customer data scopes required for web pixel PII access starting on December 10th — Shopify developer changelog, accessed 26 October 2026.
• The checkout.liquid theme file is being deprecated — Shopify Changelog, accessed 26 October 2026.
• Shopify Pixel Helper — Shopify Changelog, accessed 26 October 2026.
• New default setting for marketing pixel data sharing — Shopify Changelog, accessed 26 October 2026.
• Measure pageviews — Google for Developers, accessed 26 October 2026.
• RequestInit — MDN Web Docs, accessed 26 October 2026.