Install reference · Shopify Customer Events · ~8 minute read · Updated April 30, 2026 · By Admaxxer Team

Install the Admaxxer Web Pixel on Shopify — capture checkout_completed

If your Shopify storefront is connected to Admaxxer but your dashboard shows "Shopify vs Admaxxer Revenue: +100% gap" or your Match Score is low, the most common cause is that the Admaxxer Web Pixel App Extension never registered on your shop. The Web Pixel is what captures checkout_completed from Shopify's sandboxed checkout pages — the only place a pixel can “see” the order being placed. This guide explains why the Web Pixel matters, how the auto-install works, and the two recovery paths when it didn't.

Why Admaxxer needs the Web Pixel App Extension

Shopify isolates the checkout pages from the rest of the storefront. A “script tag” pixel installed via theme.liquid (the legacy Admaxxer install path) loads on collection pages, product pages, and the cart — but Shopify deliberately strips it from the checkout funnel. This is by design: checkout is a high-trust surface, and arbitrary script execution there is a fraud / data-leak risk.

The supported way to receive checkout events is the Customer Events API. A Customer Events pixel runs in a sandboxed Web Worker, subscribes to events via analytics.subscribe(eventName, callback), and POSTs to your collector. Admaxxer ships a Web Pixel App Extension that does exactly this — see the source at shopify-app/extensions/admaxxer-pixel/src/index.ts and the architecture deep-dive at /documentation/architecture/shopify-pixel.

Without a working Web Pixel, Admaxxer captures pageviews (via the legacy script_tag install) but not the checkout. That is why the dashboard reports a 100% revenue gap and a low Match Score: the visitor session is recorded, the product views are recorded, but the order itself never reaches the pixel. The daily Shopify polling fallback (GL#313) eventually fills the dashboard tiles 24+ hours later, but real-time attribution — the join from ad-click to revenue — never happens.

The Web Pixel subscribes to all 15 standard Shopify Customer Events, including checkout_completed, checkout_started, payment_info_submitted, and product_added_to_cart. Each event is POSTed to https://collect.admaxxer.com/v1/shopify/collect with keepalive: true so the request survives the post-checkout redirect.

How the Web Pixel auto-installs

Admaxxer ships the Web Pixel as part of its Shopify App / Custom App bundle. When you connect a Shopify shop to Admaxxer (Settings › Connections › Shopify), the OAuth callback fires the webPixelCreate Admin GraphQL mutation, which registers the bundled extension on your shop with your workspace's accountID wired into the pixel settings.

For this auto-install to succeed, the Custom App / Shopify App MUST have the write_pixels Admin API access scope granted. Read-only Custom Apps (the typical paste-token install where the merchant only granted read_orders, read_customers, etc.) cannot register the pixel; the mutation returns ACCESS_DENIED and the install proceeds without the Web Pixel. Pageviews still fire (they don't require write_pixels), but checkout events do not.

When auto-install succeeds, the Web Pixel is visible in Shopify Admin › Settings › Customer events. Status reads “Connected” with a green dot, and the “Account ID” setting shows your Admaxxer workspace's pixel website_id (e.g., admx_abc123).

How to verify the Web Pixel is installed

  1. Open your Shopify Admin and go to Settings › Customer events.
  2. Look for an entry titled “Admaxxer Pixel” (or similar, depending on your install path) under “App pixels.”
  3. Click the entry and confirm the status is Connected and the Account ID setting is populated with a value that starts with admx_.
  4. Place a test order on your storefront. Within 10–30 seconds, your Admaxxer dashboard should show the order in the Live Visitor stream (Settings › Pixel › Live), and within ~5 minutes the order should appear in visitor_payments.

If you administer multiple shops, you can also run an audit from the command line. The script scripts/verify-shopify-web-pixel.ts queries every active Shopify connection for your workspace and reports the pixel registration state. Recovery (--register-missing) re-runs webPixelCreate on any shop where the scope allows it.

Manual install / re-install

If the auto-install didn't run (because the Custom App lacked write_pixels) or you want to install Admaxxer without going through the Shopify App at all, you can paste the Custom Pixel snippet directly:

  1. In Admaxxer, open /integrations/shopify. Copy the snippet displayed under “Custom Pixel snippet” — it's pre-filled with your workspace's Admaxxer account ID. (Programmatic access: GET /api/integrations/shopify/custom-pixel-snippet.)
  2. In Shopify Admin, go to Settings › Customer events.
  3. Click Add custom pixel. Name it “Admaxxer”.
  4. Set Customer privacy to require Analytics consent (and Marketing consent if you operate in GDPR regions). Without these, the pixel is gated off in compliant regions.
  5. Paste the snippet into the Code editor. Click Save first. Then click Connect. Saving before connecting is required — if you click Connect first, the snippet is lost. (See /documentation/architecture/shopify-pixel for the full sandbox model and the destructure pattern that satisfies Shopify's ESLint dot-notation rule.)

The Custom Pixel snippet uses the same analytics.subscribe() API as the App Extension. The only difference is install path: the App Extension is bundled with the Admaxxer Shopify App and registered via API; the Custom Pixel snippet is a copy of the same logic that lives in the merchant's Customer Events configuration directly.

If you previously had the App Extension installed but want to remove it before pasting the Custom Pixel manually (to avoid double-counting), uninstall the Admaxxer Shopify App from Shopify Admin › Apps › Apps and sales channels first. The App Extension is removed automatically when the parent app is uninstalled.

Scope recovery — adding write_pixels to a Custom App

If you connected Admaxxer via a Custom App (Shopify Admin › Apps › Develop apps for your store), the access scopes are baked into the app at creation time. To allow Admaxxer to auto-install the Web Pixel on a future reconnect, add write_pixels and read_pixels to the Admin API access scopes:

  1. In Shopify Admin, go to Apps and sales channels › Develop apps.
  2. Click your Admaxxer Custom App.
  3. Under Configuration › Admin API integration, click Configure.
  4. In the Admin API access scopes picker, search for and check both write_pixels and read_pixels.
  5. Click Save. Shopify will prompt you to reinstall the app to apply the new scopes. Reinstall.
  6. Reconnect from /connections on Admaxxer. The OAuth callback re-runs webPixelCreate with the new scope, and the App Extension activates.

Alternatively, if changing the Custom App is not possible (e.g., your developer who created it is unavailable), the manual Custom Pixel paste described above achieves the same result without requiring any scope changes.

Related Admaxxer documentation

FAQ

Why is my Match Score low / Shopify-Admaxxer revenue gap +100%?

The most common cause is that the Admaxxer Web Pixel App Extension never registered on your shop. The legacy script_tag pixel only fires on storefront pages; Shopify isolates the checkout from script_tag pixels, so checkout_completed never reaches Admaxxer's collector. Your daily Shopify polling fallback (GL#313) fills dashboard tiles 24 hours later, but real-time attribution — the join from the visitor's original ad click to revenue — never happens. Install the Web Pixel via either the auto-install path or the manual Custom Pixel paste described in this guide.

How do I install the Admaxxer Web Pixel on Shopify?

Two install paths: auto-install via the Admaxxer Shopify App / Custom App (requires write_pixels scope; Admaxxer fires webPixelCreate at OAuth time), or manual install via Shopify Admin › Settings › Customer events › Add custom pixel (paste the snippet from /integrations/shopify; click Save before Connect). Either path subscribes to the same Customer Events; auto-install is faster, manual install requires no scope changes.

What is the Web Pixel App Extension?

It is an App Extension bundled with the Admaxxer Shopify App that runs in Shopify's sandboxed Web Worker on every storefront and checkout page. It subscribes to all 15 standard Shopify Customer Events (page_viewed, product_viewed, cart_viewed, checkout_started, checkout_completed, etc.) via analytics.subscribe(eventName, callback) and POSTs each event to collect.admaxxer.com/v1/shopify/collect tagged with the workspace's account ID. Source: shopify-app/extensions/admaxxer-pixel/src/index.ts.

Why did the auto-install fail with ACCESS_DENIED?

The Admin API access scope write_pixels was not granted on the Custom App / Shopify App used to connect Admaxxer. Shopify's webPixelCreate mutation requires write_pixels; read-only Custom Apps that only granted read_orders / read_customers / etc. cannot register the pixel via API. Recovery: either add the scope and reinstall the app (see “Scope recovery” section above), or use the manual Custom Pixel paste path.

Will pageviews still work without the Web Pixel?

Yes. The legacy script_tag pixel install path (theme.liquid) loads on every storefront page (collections, products, cart) and captures pageviews, sessions, click IDs, and UTMs. Shopify only isolates the checkout from script_tag pixels — so without the Web Pixel you'll see traffic, sessions, and visitor profiles but no checkout_completed events and a 100% gap on real-time order revenue. The daily polling fallback eventually fills the order count and revenue tiles, but real-time attribution is broken.

How do I verify the Web Pixel is firing?

In Shopify Admin, go to Settings › Customer events and confirm there is an entry whose status reads “Connected” and whose Account ID setting starts with admx_. Place a test order; within ~30 seconds the order should appear in your Admaxxer dashboard's Live Visitor stream, and within ~5 minutes in the visitor_payments Tinybird table. Programmatic check: run tsx scripts/verify-shopify-web-pixel.ts --workspace=<your-workspace-id>.

Can I uninstall the Web Pixel App Extension?

Yes. Uninstall the Admaxxer Shopify App from Shopify Admin › Apps › Apps and sales channels. The App Extension is removed automatically with the parent app. To stop checkout events without uninstalling the App, go to Settings › Customer events, click the Admaxxer Pixel entry, and click Disconnect. Reconnect at any time.

Does the Web Pixel respect customer privacy / GDPR consent?

Yes. The extension manifest declares customer_privacy.analytics = true and customer_privacy.marketing = true. Shopify gates pixel firing on these consent categories — in GDPR regions, the pixel does not execute until the visitor grants both Analytics and Marketing consent. The same applies to the manual Custom Pixel install, where you set the consent requirements at the Customer Event level.

Connect Shopify and start seeing checkout-completed in real time

If you haven't connected your Shopify yet, the auto-install handles everything: paste your Custom App credentials at /integrations/shopify, click Connect, and within 60 seconds your storefront and checkout pages are wired. If you already connected and your Match Score is low, run scripts/verify-shopify-web-pixel.ts against your workspace or follow the manual Custom Pixel paste recovery above.

Connect Shopify · Browse all install paths · Read the architecture deep-dive