Shopify Web Pixels API: What It Can and Can't Do for Tracking

Since October 1, apps can no longer create new script tags, and Shopify stops loading the existing ones on March 1, 2027. For tracking, the replacement is the Shopify Web Pixels API. It is better than script tags for privacy and performance, but it works differently enough that a straight port of an old tracking snippet will fail.

This guide covers how web pixels work, what they can do, what they can't, how to build and activate one, and when to reach for something else. It is written for developers and for the technical marketers who inherit the results.

What is the Shopify Web Pixels API, and how does it work?

As a customer browses the online store, they trigger customer events that Shopify publishes to a data layer, or event bus. Your pixel subscribes to those events, reshapes each payload to match your data collection endpoint, and sends it on. Shopify says pixels can securely reach all surfaces, including the storefront, checkout and post-purchase pages, without the merchant pasting tracking code.

There are two kinds of pixel, and the difference decides what you can build:

Shopify's own guidance is to build an app and have merchants install it instead of relying on custom pixels, because an app gives you a cleaner integration and a version you control. Custom pixels are the right call for a single store with a one-off tag.

What can a Shopify web pixel do?

A pixel gets a small, deliberate toolbox called the Standard API. For app pixels it has four parts:

• analytics: subscribe to Shopify's customer events, and publish your own.
• browser: asynchronous access to cookies, localStorage and sessionStorage, which run in the top frame on your behalf.
• init: a snapshot of the page at render time, including its context and the cart and customer data.
• settings: the merchant's configuration, set through the GraphQL Admin API (app pixels only).

The events you subscribe to are standard events, grouped here by where they fire in the funnel:

You can subscribe to several events at once with all_events, all_standard_events, all_custom_events or all_dom_events. Treat those groups with care, because Shopify says their contents change as events are added or modified. Subscribe to named events in production.

You can also publish custom events from your theme, for example Shopify.analytics.publish("special_email_signup", { email_campaign_id: 123 }), and subscribe to them the same way as standard events. Here is a complete app pixel that sends completed orders to your own endpoint and keeps consent state current:

import { register } from "@shopify/web-pixels-extension";

register(({ analytics, init, settings, customerPrivacy }) => {
  // Start from the consent state at page render, then keep it current.
  let consent = init.customerPrivacy;
  customerPrivacy.subscribe("visitorConsentCollected", (event) => {
    consent = event.customerPrivacy;
  });

  analytics.subscribe("checkout_completed", async (event) => {
    const checkout = event.data.checkout;
    await fetch(`https://collect.example.com/v1/${settings.accountID}`, {
      method: "POST",
      keepalive: true,
      body: JSON.stringify({
        eventId: event.id,
        name: event.name,
        orderId: checkout.order?.id,
        total: checkout.totalPrice?.amount,
        currency: checkout.currencyCode,
        consent,
      }),
    });
  });
});

Your endpoint must support CORS, because the pixel's fetch behaves like any cross-origin browser request.

What can't a Shopify web pixel do?

This is the section most teams find out about the hard way. Each limit below comes from how the sandbox is built, and each has a workaround.

Two more are worth saying plainly. Pixels run in the visitor's browser, so anything that interrupts the browser (a blocked request, a closed tab mid-send) can drop an event. And on a headless storefront, a pixel only sees events that get published to Shopify's event bus, so your storefront code has to publish them. Check how your framework handles customer events before you rely on a pixel there.

Shopify also asks that pixels not log content to the console in production. Remove your debug output before you deploy.

How do Shopify web pixels handle customer consent?

Consent is part of the design, not an add-on. Pixels honor the consent signals the visitor chose, and you read them in two ways:

• At page render: init.customerPrivacy holds the starting status.
• When it changes: subscribe to visitorConsentCollected and update your local copy. The status object tells you whether analytics processing, marketing, preferences processing and sale of data are allowed.

For an app pixel, you also declare in shopify.extension.toml that the pixel requires analytics permission (customer_privacy with analytics = true). New custom pixels require both Marketing and Analytics permissions by default, which is why a custom pixel can stay quiet for visitors who accepted only one.

The practical rule: include the consent status in what you send, and let your backend decide what to do with it. That keeps you correct if a regulation or a visitor's choice changes.

How do you build and activate a Shopify app web pixel?

1. Scaffold the extension. From your app, run shopify app generate extension and choose the web pixel template.
2. Configure it. The extension's shopify.extension.toml sets the name, the sandbox and the privacy declaration, plus any merchant-facing settings:

   name = "my-tracking-pixel"
   type = "web_pixel_extension"
   runtime_context = "strict"
   
   [customer_privacy]
   analytics = true
   
   [settings]
   type = "object"
   
     [settings.fields.accountID]
     name = "Account ID"
     description = "The account events are sent to"
     type = "single_line_text_field"

3. Subscribe to events. Write the register function as in the example above.
4. Add the access scope. Request read_customer_events in shopify.app.toml.
5. Deploy. Run shopify app deploy. The pixel appears in the store's App pixels list with a Disconnected status.
6. Activate it per store. Run the webPixelCreate mutation on each store, passing the merchant's settings. Until that runs, the pixel isn't created or configured, and it isn't subscribed to any customer events.

Step 6 is the one that burns afternoons. A deployed extension that shows Disconnected is working as designed. It is waiting for a web pixel record. Build the mutation into your app's install or onboarding flow so merchants never see that state.

Test on a development store and trigger a real checkout end to end, because events from the checkout fire only once you reach those steps. One timing note: tracking changes made inside the Black Friday freeze, November 16 through Cyber Monday on November 30, are the ones most likely to be wrong and noticed last. Ship pixel changes before November 13, or wait until December 2.

When should you use a web pixel, and when something else?

If you are evaluating vendors, ask whether their tracking ships as a web pixel, and whether it also sends a server-side purchase event. If you need ad platform tracking audited or rebuilt, our marketing app integrations team does that work. Custom app builds that include a pixel sit with bespoke app development. And if you are weighing who should own this, our guide on how to choose a Shopify development agency lists the questions to ask.

Common questions about the Shopify Web Pixels API

What is the difference between an app pixel and a custom pixel in Shopify?

An app pixel is a web pixel extension shipped inside an app and runs in a strict sandbox. A custom pixel is code a merchant pastes into Settings > Customer events and runs in a lax iframe sandbox. App pixels get a settings object for merchant configuration, while custom pixels don't, and Shopify recommends apps over custom pixels where possible.

Can a Shopify web pixel access the DOM or change my page?

No. App pixels run in a web worker with only a few guaranteed globals, so they can't read or write the DOM. Custom pixels run in a sandboxed iframe that can't reach the top frame. To draw anything on the page, use an app embed block instead.

Why isn't my Shopify web pixel firing?

The usual causes are that no web pixel record exists yet (the extension shows Disconnected until the webPixelCreate mutation runs), the visitor hasn't given the consent your pixel requires, or the event isn't one you subscribed to. Orders placed in Copilot or Google AI Mode direct checkout also don't fire client-side pixels. Check the Customer events page, then test a full checkout on a development store.

Do Shopify web pixels respect customer consent?

Yes. In regions that require consent, pixel callbacks run only after the visitor agrees, and earlier events are replayed. In regions where tracking is on by default, callbacks run until the visitor opts out. Your pixel can read the current status from init.customerPrivacy and update it through the visitorConsentCollected event.

Are web pixels replacing script tags for tracking on Shopify?

Yes, for analytics and conversion data. Apps can no longer create or update script tags as of October 1, 2026, and Shopify stops injecting them into storefronts on March 1, 2027. A script that only collects data should move to a web pixel, and anything that draws on the page should move to an app embed block.

Can an agency migrate our Shopify tracking to web pixels?

Yes. BrainBox Infoway provides Shopify development and AI automation for ecommerce from Ahmedabad, India, with ~20 specialists serving merchants and agencies in the US, EU, AUS, and CAN. The team audits your current tags, rebuilds them as web pixels, and adds server-side purchase events where accuracy matters. Agencies can hand the work over under a white-label arrangement, or you can get a free quote for your store.