Pixel & conversions

One installation, browser and server matching

GET /api/v1/tracking with a live campaigns:read key returns the exact installation snippet for this workspace, consent initialization, conversion examples, readiness, and API URLs. No private key belongs in browser code. Tracking becomes available after the owner approves setup and the brand workspace is provisioned; it does not require a live campaign.

Add install_snippet to the head of every funnel page on the approved origin, including checkout and thank-you pages. Load it before calling MarketingRouter. The script defines the SDK but does not load advertising tracking until consent is granted:

// Connect this to your existing consent manager.
// Call only when the site's advertising consent requirements are satisfied.
MarketingRouter.init({ consent: true });

Initial initialization records one page_view. For single-page apps, call MarketingRouter.track("page_view") after each client-side route change. Repeated initialization does not duplicate the initial page view. A Page on another origin cannot initialize this site’s SDK. Cross-domain checkout is not yet handled automatically.

To withdraw consent, call init({ consent: false }) to stop MarketingRouter SDK forwarding, then reload without granting consent to unload the underlying tracking library. The SDK does not replace a consent manager or delete another integration’s cookies.

Record actual business events

// Only after registration succeeds:
MarketingRouter.track("signup", { event_id: "registration_123" });

// Only after payment is confirmed:
MarketingRouter.track("purchase", {
  event_id: "order_123",
  value_cents: 4900,
  currency: "USD"
});

Use your own stable order or registration ID. Never count opening checkout as a purchase, never fabricate conversions to pass a readiness check, and never send a new random ID when retrying the same conversion. Only USD is currently supported. value_cents is an integer in minor units.

Server-side conversion events

Capture matching context at conversion time, preserving click IDs and the full URL:

const context = MarketingRouter.getContext();
// Returns anonymous_id, source_url, and browser context, or null.
// Pass context with the business event ID to your backend.

A null result means advertising consent or the visitor identity is unavailable. Do not invent an anonymous_id. Do not substitute your server’s IP address or user agent for the visitor’s. From your server, use an events:write live key:

POST /api/v1/tracking/events
{
  "event_id": "order_123",
  "type": "purchase",
  "source_url": "https://example.com/thanks?fbclid=original_click_id",
  "anonymous_id": "wuid_captured_visitor_id",
  "occurred_at": "2026-10-01T12:00:00Z",
  "value_cents": 4900,
  "currency": "USD",
  "context": { "user_agent": "<captured visitor user agent>" }
}

Use the real occurrence time within the past seven days. context optionally accepts captured visitor ip_address, user_agent, fbclid, fbp, and fbc. Treat these as visitor data and apply the site’s consent requirements.

Browser and server use the same event_id and type. MarketingRouter namespaces that ID to the site on both paths, allowing deduplication. The receipt returns tracking_event_id. Retries must use identical fields, including the original occurred_at; changed payloads return 409. Site event receipts remain unattributed and do not populate a particular campaign’s submitted-event totals. Use provider reconciliation for attributed campaign results.

Avoid forwarding purchases already recorded by the managed payment checkout. This endpoint is for external website conversions. Existing campaign events use the same site namespace for guided setups; legacy manually assigned advertisers retain their original event behavior.

Verify before campaign approval

POST /api/v1/tracking/validate with {} to check the approved product URL, or {"url":"https://example.com/another-path"} on the same origin. The response distinguishes:

• installed: the pixel was detected on the requested page.
• receiving: valid event data has been observed.
• conversion: the event required by the objective was observed on the destination hostname, or native tracking applies.
• ready: all checks required for that objective passed.

A static script tag is not proof of working tracking. Open the deployed page, grant the required consent, disable blockers for verification, and complete a genuine registration or purchase when that is the goal. Allow time for event processing before checking again. Traffic campaigns require a working page event; signup campaigns require complete_registration; purchase campaigns require purchase.

The check does not claim verified revenue accuracy, successful attribution, or ad delivery. Launch revalidates the exact campaign URL rather than trusting an old readiness result. The snippet must be permitted by your site’s Content Security Policy, including its loaded script and event transport. Browser blockers, consent, custom checkout domains, and third-party restrictions can limit matching.