Conversion setup

Use the Ads API to configure conversion measurement for the current ad account. These endpoints create the resources that the JavaScript Pixel and Conversions API use to send events.

Pixel management and Conversions API key creation must be enabled for the ad account. If /conversions/pixels or /conversions/api_keys returns 404 with Not found, contact your OpenAI partner representative. A Client data source not found response from event-setting creation means that source_ids references a source that does not exist in the current ad account.

Create a pixel

Create a web conversion source and its Pixel ID.

POST /conversions/pixels

curl -X POST "https://api.ads.openai.com/v1/conversions/pixels" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme website",
    "client_type": "web"
  }'

{
  "id": "clidsrc_123",
  "client_type": "web",
  "name": "Acme website",
  "pixel_id": "134534..."
}

Use id as a source_ids value when you create an event setting. Use pixel_id to initialize the JavaScript Pixel and when you send Conversions API events.

Create a Conversions API key

Create a key that can send server-side events for the current ad account.

POST /conversions/api_keys

curl -X POST "https://api.ads.openai.com/v1/conversions/api_keys" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme production conversions"
  }'

{
  "name": "Acme production conversions",
  "api_key": "<CONVERSIONS_API_KEY>"
}

Caution: Store the returned key in a server-side secret manager. Never place it in browser code, client-visible environment variables, logs, or source control.

Create an event setting

Create a conversion definition and connect it to one conversion source.

POST /conversions/event_settings

curl -X POST "https://api.ads.openai.com/v1/conversions/event_settings" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Purchases",
    "event_type": "order_created",
    "attribution_window_days": 30,
    "source_ids": ["clidsrc_123"]
  }'

{
  "id": "ces_123",
  "name": "Purchases",
  "event_type": "order_created",
  "custom_event_name": null,
  "attribution_window_days": 30,
  "ad_account_id": "adacct_123",
  "source_ids": ["clidsrc_123"],
  "sources": [
    {
      "id": "clidsrc_123",
      "name": "Acme website"
    }
  ],
  "campaigns": [],
  "archived": false,
  "version": 1
}

List event settings

List conversion definitions for the current ad account.

GET /conversions/event_settings

curl -X GET "https://api.ads.openai.com/v1/conversions/event_settings?limit=20&order=desc" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY"

Send events

After setup, use the returned Pixel ID and Conversions API key to implement server-side event delivery. For browser measurement, use the JavaScript Pixel. If both sources send the same event, use a shared event ID so OpenAI can deduplicate it.