Chapter 09 — The Conversions API

The Conversions API (CAPI) is the server-to-server companion to the pixel. OpenAI explicitly calls it a more reliable tracking source than the pixel alone and recommends running both when possible.

Endpoint

POST https://bzr.openai.com/v1/events?pid=<PIXEL-ID>
Authorization: Bearer <API-KEY>
Content-Type: application/json

Note the host: bzr.openai.com, not api.ads.openai.com. Conversions and Advertiser API live on different domains.

Value	Required	Description
`pid` (query string)	Yes	Pixel ID.
`validate_only` (body)	No	When `true`, validates events without saving them.
`events` (body)	Yes	Array of events. Up to 1,000 per batch.

Batch failure semantics

If one event in a batch fails, the entire batch fails. Build retry logic accordingly. Two options:

Send small batches (10–50 events) so a single bad event doesn’t kill a large batch.
Validate first — set validate_only: true, identify the bad event, fix or drop it, then send for real.

In production, both. Validate periodically; send small batches.

Provisioning

Pixel ID and Conversions API key are both created from the Conversions tab inside Ads Manager. The Pixel ID is shared between pixel and CAPI — same identifier, both transports. The API key is a separate secret used only by CAPI.

Key difference from the pixel

The pixel captures oppref automatically. The Conversions API does not. The advertiser is responsible for capturing oppref from the landing page (or from the __oppref cookie the pixel stored) and passing it on the server-side event.

The standard pattern on a Shopify store:

User clicks ad → lands on PDP. URL contains oppref query parameter.
Pixel captures oppref, writes it to __oppref cookie.
Server-side checkout webhook fires. Backend reads oppref from session/cart metadata (which was populated from the cookie or query string at landing).
Backend sends order_created to Conversions API with oppref included.

Without that bridge, server-side events lose the click attribution.

Example event

curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL-ID>" 
  -H "Authorization: Bearer <API-KEY>" 
  -H "Content-Type: application/json" 
  --data '{
    "validate_only": false,
    "events": [{
      "id": "order_12345",
      "type": "order_created",
      "timestamp_ms": 1773892800000,
      "oppref": "oppref_abc",
      "source_url": "https://shop.example.com/checkout/confirmation",
      "action_source": "web",
      "data": {
        "type": "contents",
        "amount": 2599,
        "currency": "USD",
        "contents": [{
          "id": "sku_123",
          "name": "Starter bundle",
          "content_type": "product",
          "quantity": 1
        }]
      }
    }]
  }'

Server event metadata fields

Field	Required	Description
`id`	Yes	Unique event identifier. Used with `type` to deduplicate.
`type`	Yes	Standard event name or `custom`.
`timestamp_ms`	Yes	Event time in ms. Within last 7 days, no more than 10 minutes ahead.
`custom_event_name`	Conditional	Required when `type` is `custom`.
`oppref`	No	OpenAI privacy-preserving identifier. Forward when available.
`source_url`	Conditional	Required when `action_source` is `web`.
`action_source`	No	One of `web`, `mobile_app`, `offline`, `physical_store`, `phone_call`, `email`, `other`.
`user`	No	Optional user fields that improve attribution accuracy.
`opt_out`	No	`true` opts the event out of future user-level personalisation. Defaults to `false`.
`data`	Yes	Event data matching the `type`. See Chapter 11.