DOCS
Checkout•
HomeAPI reference Checkout REST API Facebook 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:

  • A custom event named zonos-checkout-... (via fbq('trackCustom', ...)) for full-funnel custom audiences.
  • The matching Meta standard event (via fbq('track', ...)) for built-in optimization, e.g. InitiateCheckout, AddPaymentInfo, and Purchase.

Native integrations don't need this guide. If <zonos-checkout> renders directly on your site (no iframe), Zonos calls your page's window.fbq in place — just enable Facebook Pixel in the Zonos dashboard under Checkout settings → Tracking and make sure your usual Meta Pixel base code is loaded on the page. The relay setup below is only required when Checkout is hosted in an iframe on a different origin.

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):

  1. 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.
  2. 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.
  3. Events are forwarded -- As shoppers progress through checkout, each analytics event is sent via postMessage to your page, where the relay script forwards it to fbq with the appropriate track / trackCustom mode.

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.

1<!-- Meta Pixel Code -->
2 
3<script>
4 !(function (f, b, e, v, n, t, s) {
5 if (f.fbq) return;
6 n = f.fbq = function () {
7 n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments);
8 };
9 if (!f._fbq) f._fbq = n;
10 n.push = n;
11 n.loaded = !0;
12 n.version = "2.0";
13 n.queue = [];
14 t = b.createElement(e);
15 t.async = !0;
16 t.src = v;
17 s = b.getElementsByTagName(e)[0];
18 s.parentNode.insertBefore(t, s);
19 })(
20 window,
21 document,
22 "script",
23 "https://connect.facebook.net/en_US/fbevents.js",
24 );
25 fbq("init", "YOUR_PIXEL_ID");
26 fbq("track", "PageView");
27</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 fbq function.

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:

1<script>
2 window.Zonos.facebookPixelId = "YOUR_PIXEL_ID";
3</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.

1<script
2 async
3 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"
4></script>

Complete example

Here's what the full setup looks like in your page's <head>:

1<head>
2 <!-- ... your existing head tags ... -->
3 
4 <!-- Meta Pixel Code -->
5 
6 <script>
7 !(function (f, b, e, v, n, t, s) {
8 if (f.fbq) return;
9 n = f.fbq = function () {
10 n.callMethod
11 ? n.callMethod.apply(n, arguments)
12 : n.queue.push(arguments);
13 };
14 if (!f._fbq) f._fbq = n;
15 n.push = n;
16 n.loaded = !0;
17 n.version = "2.0";
18 n.queue = [];
19 t = b.createElement(e);
20 t.async = !0;
21 t.src = v;
22 s = b.getElementsByTagName(e)[0];
23 s.parentNode.insertBefore(t, s);
24 })(
25 window,
26 document,
27 "script",
28 "https://connect.facebook.net/en_US/fbevents.js",
29 );
30 fbq("init", "YOUR_PIXEL_ID");
31 fbq("track", "PageView");
32 </script>
33 
34 <!-- Zonos analytics relay for iframe checkout -->
35 
36 <script
37 async
38 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"
39 ></script>
40</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 openszonos-checkout-startInitiateCheckout--
Shopper enters customer infozonos-checkout-customer-infonone--
Shopper selects a shipping methodzonos-checkout-shipping-infononeserviceLevelId
Shopper enters payment detailszonos-checkout-payment-infoAddPaymentInfopaymentMethod
Payment attempt failszonos-checkout-payment-failnone--
Order completes successfullyzonos-checkout-successnoneorder_id, currency, value, contents, content_ids
Order completes (e-commerce event)purchasePurchaseorder_id, currency, value, contents, content_ids
Shopper closes checkoutzonos-checkout-closenone--

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↕
valueTotal order value
currencyThree-letter currency code (e.g., USD)
order_idZonos order ID or checkout session ID
contentsArray of cart items, each with id, quantity, and item_price
content_idsArray of item IDs (the SKU, product ID, or product name fallback)
content_typeAlways "product"
num_itemsTotal quantity across all items

Debugging 

To enable debug logging for the relay script, add the zonosDebug=1 query parameter to your page URL:

1https://www.yourstore.com/checkout?zonosDebug=1

Open 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 fbq with the expected track / trackCustom mode.

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.

Was this page helpful?

Get support·Legal docs·© 2026 Zonos
On this page:
  • Facebook Pixel for iframe Checkout
  • How it works
  • Prerequisites
  • Setup
  • Meta Pixel events reference
  • Debugging
  • Common questions