Guide de migration du Pixel vers l'API de Conversions OpenAI Ads

If your ad account is still running on a standalone browser pixel, you are measuring yesterday's web.

Between Safari's 24-hour cookie limits, Firefox Enhanced Tracking Protection, and aggressive ad blockers, browser-only tracking loses 20% to 35% of total conversion volume. To maintain competitive bidding on OpenAI Ads, migrating to a hybrid CAPI architecture is no longer optional. It is mandatory.

Migrating from a pixel-only setup to a hybrid CAPI architecture requires care.

If you simply turn on CAPI without configuring deterministic event deduplication, every conversion will be counted twice. If you rip out the browser pixel entirely, you lose essential client context like IP addresses, browser screen resolutions, and session navigation tokens.

Here is the step-by-step migration blueprint to upgrade your ad account from a brittle client pixel to a resilient hybrid CAPI architecture without dropping a single day of data.

The 4-Phase Migration Roadmap

[ Phase 1: Client Prep ] ---> [ Phase 2: Server Prep ] ---> [ Phase 3: Dual Validation ] ---> [ Phase 4: Full Production ]
Add event_id to oaiq        Build CAPI with              Run with                      Disable validate_only,
(No server events yet)       validate_only: true         identical event_ids           verify deduplication

Phase 1: Client-Side Deduplication Readiness

Before touching server infrastructure, update your frontend tracking scripts to emit a deterministic event_id alongside every conversion event.

For an ecommerce order, use your internal transaction ID or order number:

// Updated client-side event call
const orderId = "109482";

window.oaiq('event', 'order_created', {
  amount: 8500, // $85.00 in minor units
  currency: 'USD',
  order_id: orderId,
  event_id: 'ord_' + orderId // Deterministic deduplication key
});

Deploy this update to your production website. Since the server CAPI integration is not yet active, this change has zero effect on your reporting, it simply lays the required deduplication foundation.

Phase 2: Server-Side Pipeline Build (validate_only: true)

Construct your server-side payload formatter, queue worker, or webhook relay (e.g., using Node.js, Python, or Cloudflare Workers).

During this phase, configure the payload with "validate_only": true:

{
  "validate_only": true,
  "events": [
    {
      "id": "srv_evt_test_01",
      "type": "order_created",
      "timestamp_ms": 1726650000000,
      "action_source": "website",
      "event_id": "ord_109482",
      "user_data": {
        "em": "5885e35f79901981437bd82f3c73e9f45618f1a4e698ef75c7dd88b8e0bb8f32",
        "client_ip_address": "198.51.100.42"
      },
      "data": {
        "amount": 8500,
        "currency": "USD",
        "order_id": "109482"
      }
    }
  ]
}

Send this payload to https://bzr.openai.com/v1/events?pid=<PIXEL-ID>. Verify that:

1. The endpoint returns 200 OK.
2. No schema errors or parameter warnings are returned.
3. Your Ads Manager conversion count remains unaffected.

Phase 3: Live Dual-Tracking Activation

Once schema validation passes, switch "validate_only": false on your server pipeline:

1. Simultaneous Emission: When an order occurs, the browser fires oaiq('event', 'order_created', { event_id: 'ord_109482' }) and the server sends a CAPI event with event_id: 'ord_109482'.
2. Platform Deduplication: OpenAI Ads checks incoming events. If both client and server events arrive within 48 hours, OpenAI merges the rich browser session context with the reliable server conversion data and counts exactly one conversion.
3. Recovery Verification: If an ad blocker prevents the browser event from reaching OpenAI, the server event ensures the conversion is still recorded.

Phase 4: Reconciliation and Bidding Monitoring

During the first 72 hours of live dual-tracking:

• Monitor Total Conversions: Verify that the reported conversion count matches your actual backend database orders (with a standard 2-5% attribution margin).
• Check for Duplication: If conversion volume spikes to approximately 200% of your real order volume, immediately inspect your event_id values, this indicates that the client and server keys do not match character-for-character.
• Observe Campaign CPA: As previously unrecorded conversions are recovered, your reported CPA will drop, giving algorithmic bidding models stronger signals to identify new customers.

For professional migration support with end-to-end verification, explore our Conversions API Setup service.