Developer

External checkout pixels

Attribute purchases from third-party checkout or booking platforms with Apex handover and a confirmation-page pixel.

Use external checkout pixels when the purchase happens on a provider domain where the Apex SDK is not loaded, but the provider lets you add JavaScript to a confirmation page.

Runtime pattern

Configure external tracking handover for the provider domain in Apex runtime settings.
Choose the handover query parameter, for example drip_bucket or ref.
Generate a provider snippet from /api/external-pixels/snippet.
Install the snippet on the provider confirmation page.
Call the generated global function with the provider's booking or order variables.

The SDK appends the handover payload only when a visitor clicks or submits toward a configured external domain. It can append to links and forms. The default handover parameter is drip_bucket, the default TTL is 120 seconds, and signed handover is enabled unless disabled in runtime settings.

Generate the snippet

http

POST /api/external-pixels/snippet
Content-Type: application/json
 
{
  "provider": "fareharbor",
  "handoverParam": "ref",
  "globalName": "trackFareHarborPurchase"
}

The response includes the shop ID, Worker endpoint, sanitized provider, handover parameter, global name, and the snippet. handoverParam keeps only letters, numbers, underscores, and dashes. globalName must be a valid JavaScript identifier or Apex falls back to apexExternalPurchase.

Provider-side call

Adapt the generated function call to the provider's variables:

trackFareHarborPurchase({
  ref: booking.onlineRef,
  revenue: booking.totalInCents / 100,
  currency: booking.currency,
  bookingId: booking.pk,
  orderId: booking.order && booking.order.uuid,
  itemId: booking.item && booking.item.pk,
  itemName: booking.item && booking.item.name,
  metadata: {
    channel: "external_checkout"
  }
});

The snippet also reads the configured handover query parameter from location.href when ref or onlineRef is not passed.

Attribution formats

The snippet accepts:

Format	Notes
Apex base64url payload	Decodes `visitorId` and `assignments` from the SDK handover payload.
Compact legacy format	`apex:visitorId:experimentId:variationId`.
Direct function inputs	`experimentId` and `variationId` can be passed directly when no handover reference is available.

When no assignment exists, the snippet still sends one unattributed event using visitorId: "external_pixel" and sessionId: "external_pixel".

Event sent to Apex

The generated snippet posts to {endpoint}/events with _shopId and _signature:

json

{
  "events": [
    {
      "type": "goal",
      "data": {
        "goalId": "__revenue__",
        "revenue": 129,
        "currency": "EUR",
        "orderId": "booking_demo_1001",
        "bookingId": "booking_demo_1001",
        "provider": "fareharbor",
        "externalRef": "handover_payload_here",
        "source": "external_pixel"
      },
      "shopId": "11111111-1111-4111-8111-111111111111",
      "visitorId": "visitor_demo_123",
      "sessionId": "external_pixel",
      "experimentId": "22222222-2222-4222-8222-222222222222",
      "variationId": "33333333-3333-4333-8333-333333333333",
      "url": "https://checkout.example.com/confirmation",
      "ts": 1783502400000
    }
  ],
  "_shopId": "11111111-1111-4111-8111-111111111111",
  "_signature": "px_signed_ingest_token_here"
}

goalId defaults to __revenue__. revenue accepts numbers, numeric strings, or totalInCents divided by 100. metadata keys are copied into the event data.

What this does not cover

External checkout pixels fire only where the provider runs the snippet. Funnel intent events such as checkout-step views, add-to-cart, or form friction still need provider events, postMessage, custom storefront JavaScript, or a native integration.