How it works
Because the Zonos Checkout runs inside an iframe on a different origin, it
cannot directly access your page's fbq function. The relay system solves this
with a two-step handshake (steps 1-2) followed by event forwarding (step 3):
- Checkout pings the parent -- When the checkout loads inside the iframe, it sends a message to the parent window indicating it's ready to relay events, including the Pixel ID.
- Parent acknowledges -- The relay script on your page receives the ping, detects (or injects) your Meta Pixel base code, and signals back that it's ready to receive events.
- Events are forwarded -- As shoppers progress through checkout, each
analytics event is sent via
postMessageto your page, where the relay script forwards it tofbqwith the appropriatetrack/trackCustommode.
All messages are validated against trusted Zonos origins (zonos.com and
iglobalstores.com) over HTTPS only.
Prerequisites
- A Meta Pixel with a Pixel ID (a numeric string, typically 15-16 digits). You can create one in Meta Events Manager.
- A legacy Checkout integration that loads Zonos Checkout in an iframe on your page.
- Facebook Pixel enabled in your Zonos Checkout settings (in the Zonos dashboard, under Checkout settings -> Tracking).
Setup
Step 1: Add the Meta Pixel base code to your page
If you don't already have Meta Pixel installed on your site, add the standard
Pixel base code to the <head> of the page that hosts the Checkout iframe.
Replace YOUR_PIXEL_ID with your own numeric Pixel ID.
<!-- Meta Pixel Code --> <script> !(function (f, b, e, v, n, t, s) { if (f.fbq) return; n = f.fbq = function () { n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments); }; if (!f._fbq) f._fbq = n; n.push = n; n.loaded = !0; n.version = "2.0"; n.queue = []; t = b.createElement(e); t.async = !0; t.src = v; s = b.getElementsByTagName(e)[0]; s.parentNode.insertBefore(t, s); })( window, document, "script", "https://connect.facebook.net/en_US/fbevents.js", ); fbq("init", "YOUR_PIXEL_ID"); fbq("track", "PageView");</script>Note: If your site already has Meta Pixel installed (e.g., through Google Tag Manager, Shopify's native integration, or a direct snippet), you can skip this step. The relay script will use your existing
fbqfunction.
You can find this snippet in your Meta Events Manager under your Pixel Settings -> Continue Pixel Setup -> Install code manually.
Step 2: Pass your Pixel ID to Zonos Checkout
Tell Zonos Checkout which Pixel ID to use by setting window.Zonos.facebookPixelId
inside your Checkout's customHTML. The Zonos dashboard exposes a
customHTML editor under Checkout settings -- add a <script> tag like this:
<script> window.Zonos.facebookPixelId = "YOUR_PIXEL_ID";</script>This value is sent to the parent during the relay handshake. If your parent
page doesn't already have fbq loaded, the relay script will inject the Meta
Pixel base code for you using this ID.
Step 3: Add the Zonos analytics relay script
Add the following script tag to the same page that loads the Checkout iframe, after the Meta Pixel base code. This is the same script used for Google Analytics 4 -- a single relay handles both providers, so if you've already added it for GA4, skip this step.
<script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"></script>Complete example
Here's what the full setup looks like in your page's <head>:
<head> <!-- ... your existing head tags ... --> <!-- Meta Pixel Code --> <script> !(function (f, b, e, v, n, t, s) { if (f.fbq) return; n = f.fbq = function () { n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments); }; if (!f._fbq) f._fbq = n; n.push = n; n.loaded = !0; n.version = "2.0"; n.queue = []; t = b.createElement(e); t.async = !0; t.src = v; s = b.getElementsByTagName(e)[0]; s.parentNode.insertBefore(t, s); })( window, document, "script", "https://connect.facebook.net/en_US/fbevents.js", ); fbq("init", "YOUR_PIXEL_ID"); fbq("track", "PageView"); </script> <!-- Zonos analytics relay for iframe checkout --> <script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js" ></script></head>That's it. Once both scripts are on your page, Facebook Pixel is enabled in your
Zonos dashboard, and customHTML sets the Pixel ID, the relay automatically
forwards all checkout funnel events to Meta.
Meta Pixel events reference
For each step in the funnel, Zonos Checkout fires both a custom event (so you
can build precise audiences) and the matching Meta standard event (so it shows
up in Meta's optimization and conversion reporting). All events include an
isTestMode flag and the checkoutSessionId.
| Trigger↕ | Custom event (fbq('trackCustom', ...))↕ | Standard event (fbq('track', ...))↕ | Additional metadata↕ |
|---|---|---|---|
| Checkout opens | zonos-checkout-start | InitiateCheckout | -- |
| Shopper enters customer info | zonos-checkout-customer-info | none | -- |
| Shopper selects a shipping method | zonos-checkout-shipping-info | none | serviceLevelId |
| Shopper enters payment details | zonos-checkout-payment-info | AddPaymentInfo | paymentMethod |
| Payment attempt fails | zonos-checkout-payment-fail | none | -- |
| Order completes successfully | zonos-checkout-success | none | order_id, currency, value, contents, content_ids |
| Order completes (e-commerce event) | purchase | Purchase | order_id, currency, value, contents, content_ids |
| Shopper closes checkout | zonos-checkout-close | none | -- |
Steps without a Meta standard equivalent (e.g. customer info, shipping info) only fire the custom
zonos-checkout-...event. You can target these in Meta Ads Manager via custom audiences using "Event =zonos-checkout-customer-info", etc.
Purchase event metadata
The Purchase standard event follows the
Meta Pixel Purchase event
schema. Cart items are mapped from the GA-style items array into Meta's
contents array:
| Field↕ | Description↕ |
|---|---|
value | Total order value |
currency | Three-letter currency code (e.g., USD) |
order_id | Zonos order ID or checkout session ID |
contents | Array of cart items, each with id, quantity, and item_price |
content_ids | Array of item IDs (the SKU, product ID, or product name fallback) |
content_type | Always "product" |
num_items | Total quantity across all items |
Debugging
To enable debug logging for the relay script, add the zonosDebug=1 query
parameter to your page URL:
https://www.yourstore.com/checkout?zonosDebug=1Open your browser's developer console to see detailed logs of the relay handshake and forwarded events. This is useful for verifying that:
- The relay script receives the ping from the checkout iframe.
- Meta Pixel is configured with the correct Pixel ID.
- Events are being forwarded to
fbqwith the expectedtrack/trackCustommode.
The Meta Pixel Helper Chrome extension is also helpful for inspecting Pixel calls in real time.
Common questions
Why are two events fired for the same step (e.g. zonos-checkout-start and InitiateCheckout)?
Meta's standard events power conversion optimization, ad reporting, and lookalike
audiences out of the box. The custom zonos-checkout-... events let you build
more granular custom audiences on the exact funnel step, even when no Meta
standard equivalent exists (e.g. customer info, shipping info). Firing both
gives you the best of both worlds without losing any signal.
What if I'm running both Google Analytics and Facebook Pixel?
You don't need two relay scripts -- the same analyticsRelayOnInit.js handles
both providers in a single handshake. Add the GA4 base tag and the Meta Pixel
base code to your <head>, set both window.Zonos.googleAnalyticId and
window.Zonos.facebookPixelId in customHTML, and enable both providers in
your Zonos dashboard. Each event is fanned out to whichever providers are
enabled.
What if my parent page doesn't have Meta Pixel installed?
If your customHTML sets window.Zonos.facebookPixelId and the relay script
detects no fbq on the page, it will inject the Meta Pixel base code for you
during the handshake using the Pixel ID you provided. You can also pre-install
the Meta Pixel base code yourself if you want to fire PageView and other
events outside the checkout funnel.
Are test orders tracked?
All events include an isTestMode field. When Checkout is in test mode, events
are still relayed to Meta but flagged with isTestMode: true. You can filter
these out in Meta Ads Manager or exclude them with custom conversion rules.
Does Conversions API (CAPI) replace this?
No -- this is a browser-side Pixel integration that runs in your shoppers' browsers. The Meta Conversions API is a separate server-to-server channel that some merchants use alongside the Pixel for redundancy. The two are complementary and Zonos's relay handles only the browser-side Pixel.
Facebook Pixel for iframe Checkout
Track the full checkout funnel with Meta (Facebook) Pixel when using an iframe-based legacy Checkout integration.
Merchants using the legacy Checkout integration (iframe hosted on
iglobalstores.com) can track Meta Pixel events across the full checkout funnel. Zonos Checkout automatically relays analytics events from the iframe to the parent page using the same lightweight relay script used for Google Analytics 4, so events appear in your Meta Events Manager as if they originated from your own site.For each funnel step, two events are emitted:
zonos-checkout-...(viafbq('trackCustom', ...)) for full-funnel custom audiences.fbq('track', ...)) for built-in optimization, e.g.InitiateCheckout,AddPaymentInfo, andPurchase.