Shopify custom pixel for purchase tracking: how to add one, test it and know its limits

This guide covers the purchase event.

What a custom pixel is

A custom pixel is a piece of JavaScript that you add in your Shopify admin under Settings > Customer events. Shopify says custom pixels collect customer events on more pages of your store, including the checkout and post-purchase pages, without changes to your theme.

Three things about it matter for purchases:

It runs in a lax sandbox. Shopify's developer documentation says custom pixels load in a lax sandbox, which is an iframe that cannot read or change the page. Code that expects to find the page around it will not.
It hears events, it does not send them. Your code subscribes to Shopify's events, such as checkout_completed, and passes the data on to the platform's code. Shopify's help says Meta's pixel code does not send data from a custom pixel on its own.
It is your code. Shopify says adding and using custom pixels is unsupported by Shopify, and that compliance, consent, code security, troubleshooting and updates are your responsibility.

Before you add one

Remove the old purchase code first. Shopify's help asks you to take existing pixel code out of places such as theme.liquid and the checkout's Additional scripts, so that events are not counted twice.

Then list what already sends purchases. Open Settings > Customer events and look at both the app pixels and the custom pixels. The Facebook & Instagram app and the Google & YouTube app each add their own app pixel. A custom pixel that sends Purchase next to one of them is a second sender.

Add the pixel

These are the steps in Shopify's help:

1In your Shopify admin, go to Settings > Customer events.
2Enter a unique name for the pixel.
3Click Add pixel to open the event editor.
4In the Customer privacy section, check Permission and Data sale (see below).
5Paste your code into the Code window.
6Click Save, then Connect pixel to start tracking.

Shopify's sandbox supports only JavaScript. Any HTML in the code a platform gives you has to come out. A <script src=...> tag becomes JavaScript that creates the script element.

The purchase code

Shopify fires checkout_completed once for each checkout, typically on the Thank you page. When the store has an upsell or post-purchase offer, it fires on the first upsell page instead, and not again on the Thank you page.

For Meta, the pattern in Shopify's help looks like this, after Meta's base code:

analytics.subscribe("checkout_completed", (event) => {
  const checkout = event.data.checkout;
  fbq('track', 'Purchase', {
    currency: checkout.currencyCode,
    value: checkout.totalPrice.amount,
  });
});

Shortened from Shopify's example.

The same event carries the order. Shopify's reference says checkout.order.id is filled only on checkout_completed, and that checkout.lineItems lists the items. If a server also sends this purchase to Meta, pass an event ID as the fourth argument of fbq. The Meta event ID with a Shopify custom pixel covers that step.

For Google Analytics 4, send the purchase event with a transaction_id. Google's event reference marks transaction_id and items as required, says currency is required when you set value, and says the transaction ID helps you avoid duplicate events for a purchase. Use the order's ID, so each order has one value everywhere.

Also check the value. totalPrice includes duties, taxes and discounts. Google's reference asks for the sum of price times quantity of the items, without shipping and tax. Pick the field your reports expect.

The consent settings it starts with

Shopify's help says a new custom pixel requires the Marketing and Analytics permissions by default, and qualifies as data sale by default. You change both under Customer privacy in the pixel's details.

Shopify's pixels overview says that in markets that require consent, a pixel runs only when the visitor has given the permissions it needs. So a buyer who declined does not run your custom pixel. That is expected. Lowering the permission to make more purchases arrive is a legal decision, not a tracking fix.

Test it with the Shopify Pixel Helper

Shopify has its own tester for custom pixels:

1Go to Settings > Customer events and click the custom pixel.
2Click Test. Your store opens with the Shopify Pixel Helper.
3If the helper says "Pixel is awaiting consent", accept tracking on your cookie banner.
4Go through the store and place an order. Watch Events received.

Shopify says a green dot means the event was subscribed to and your callback ran, and a red dot means the callback failed. Expand an event to see its data and any error. The helper tests one custom pixel at a time, clears its log when you move to a new page, and has no close button: close its tab to stop. It does not work on headless stores or stores in private mode.

The helper shows what Shopify handed to your code. To see what the platform received, check there too: Test events in Meta Events Manager, Realtime or DebugView in GA4. For a full one-order test of each platform, see Meta Pixel purchase event not firing and GA4 purchase event not firing.

What a custom pixel cannot catch

A custom pixel is still a browser pixel. Each of these stops it:

The page does not load. Shopify's reference says that if the page where checkout_completed should fire fails to load, the event is not triggered at all. A buyer who closes the tab early can be one of these.
Ad blockers and browser privacy settings. They act on the platform's code and its requests in the browser.
Declined consent. As above, and correctly so.
Orders without a checkout in the browser. Point of sale sales, draft orders and orders other apps create never pass through your storefront.

If your platform shows clearly fewer purchases than your paid online orders, and declined consent does not explain the gap, a better pixel will not close it. A server copy of each paid order will. See Server-side tracking for Shopify: what it fixes.

For the server side of the same purchase, see setting up the Conversions API on Shopify.

FAQ

Can I paste my old Thank you page script into a custom pixel?

Not as it is. Remove the HTML, load the base code with JavaScript, and move the purchase call inside analytics.subscribe("checkout_completed", ...).

Will the custom pixel fire on the order status page when the buyer comes back?

Shopify documents checkout_completed as once per checkout. If you see a second purchase on a reload, it comes from other code. See The purchase event fires again when the order page is reopened.

Do I need both an app pixel and a custom pixel?

Only if they send different events. Two senders of Purchase to the same platform count the order twice, unless both copies share one event ID that the platform uses to keep one.

Where Tikra fits

Tikra sends each paid online order of your store from our server to Meta, Google Analytics 4, Google Ads, TikTok, Pinterest, Snapchat, ChatGPT Ads and Klaviyo, and keeps a record for each order: what was sent, when, and the platform's answer. No theme changes and no app embed: Tikra uses Shopify's web pixel and writes nothing to your orders. Its own pixel sends no purchases to any platform, so it does not compete with your custom pixel. For Google Analytics 4, the record says the order was sent, because Google gives no confirmation per order.

Tikra applies your customers' consent choices to every order, and in Strict mode an order is sent only with the buyer's consent. A written guarantee in our Terms covers eligible orders: at least 97 % reach each platform, fixed within 12 hours or a month's fee credited (Terms of Service, section 8).

The free diagnosis sends none of your orders anywhere. It shows your paid orders of the last 7 full days, how many came from a Meta, Google or TikTok ad, and, after a full day and 10 paid online orders, how many your shoppers' browsers reported. With a key that can read your pixel's statistics, it also shows Meta's count.

Run the free diagnosis