Track Conversions in GA4 and Meta

How it works

Where the purchase event fires depends on which checkout surface you use. In the embed, your page hosts the pixels; on the hosted page, Throttle injects them.

Embed recipe

Protocol v1.4 additively extends throttle.completed with total (minor units), currency, and lineItems. Convert minor units to major ( total / 100) before handing values to analytics.

import { CheckoutEmbed } from '@usethrottle/checkout-react';
<CheckoutEmbed
  sessionId={sessionId}
  parentOrigin="https://shop.example.com"
  onSucceeded={({ orderId, total, currency, lineItems }) => {
    const value = (total ?? 0) / 100; // minor units -> major
    const items = lineItems ?? [];
    // GA4 purchase
    window.gtag?.('event', 'purchase', {
      transaction_id: orderId,
      value,
      currency: currency ?? 'USD',
      items: items.map((item) => ({
        item_id: item.sku ?? item.id ?? item.name,
        item_name: item.name,
        quantity: item.quantity,
        price: item.unitPrice / 100,
      })),
    });
    // Meta pixel purchase — eventID enables CAPI dedup
    window.fbq?.(
      'track',
      'Purchase',
      {
        value,
        currency: currency ?? 'USD',
        content_type: 'product',
        content_ids: items
          .map((item) => item.sku ?? item.id)
          .filter((id): id is string => Boolean(id)),
      },
      { eventID: orderId },
    );
    router.push(`/thank-you?order=${orderId}`);
  }}
/>;

Hosted setup

For the hosted checkout page, configure tracking once per application and environment via GET/PUT /api/v1/tracking-settings. Only the public ids reach the buyer's browser; secrets stay server-side and come back masked from GET.

curl -X PUT https://api.usethrottle.dev/api/v1/tracking-settings \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ga4MeasurementId": "G-XXXXXXXXXX",
    "metaPixelId": "1234567890123456",
    "requireConsent": true
  }'

Server-side conversions

Browser pixels miss buyers with ad blockers and tabs closed mid-redirect. Set serverSideEnabled plus the per-channel secrets and Throttle forwards the purchase from its backend at the payment moment: card payments at capture, Net-N invoices at authorization (issuance), and subscription renewal charges skipped — renewals are not new acquisitions.

curl -X PUT https://api.usethrottle.dev/api/v1/tracking-settings \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "serverSideEnabled": true,
    "ga4ApiSecret": "your-ga4-mp-api-secret",
    "metaCapiAccessToken": "your-meta-capi-access-token"
  }'

• GA4 Measurement Protocol — sends a purchase event with transaction_id set to the order id, using the captured gaClientId / gaSessionId when available. Requires ga4MeasurementId + ga4ApiSecret (create the API secret under the GA4 data stream's Measurement Protocol settings).
• Meta Conversions API — sends a Purchase event with event_id set to the order id and user_data built from the SHA-256-hashed buyer email, server-stamped IP address and user agent, and the fbp / fbc cookies from clientContext. Requires metaPixelId + metaCapiAccessToken.

Attribution capture (clientContext)

POST /api/v1/checkout/sessions accepts an optional clientContext attribution blob. The hosted page also auto-captures what it can at completion (UTMs, click ids, GA and Meta cookies, landing page, referrer) and Throttle merges the two per key — completion-time values win — then server-stamps ipAddress and userAgent. The merged snapshot lands on order.clientContext (merchant order GET) and on the order.created webhook payload.

// Your server, at session create time
const session = await checkout.createSession({
  applicationId: process.env.THROTTLE_APPLICATION_ID!,
  cartId: cart.id,
  returnUrl: 'https://shop.example.com/checkout/success',
  cancelUrl: 'https://shop.example.com/cart',
  clientContext: {
    landingPage: 'https://shop.example.com/spring-sale?utm_source=google',
    referrer: 'https://www.google.com/',
    utmSource: 'google',
    utmMedium: 'cpc',
    utmCampaign: 'spring-sale',
    gclid: 'Cj0KCQjw...',
    gaClientId: '123456789.1700000000',
    gaSessionId: '1700000000',
    fbp: 'fb.1.1700000000000.1234567890',
    fbc: 'fb.1.1700000000000.IwAR2...',
    consent: { analytics: true, marketing: true }
  }
});

Accepted keys: landingPage, referrer, utmSource, utmMedium, utmCampaign, utmTerm, utmContent, gclid, fbclid, msclkid, ttclid, gaClientId, gaSessionId, fbp, fbc, and consent ( { analytics?, marketing? }). Unknown keys are rejected; ipAddress / userAgent are server-stamped and rejected as client input.