ChatGPT Ads

ChatGPT Ads has a beta Ads Manager, a JavaScript Measurement Pixel, and a server-side Conversions API. Use the documented surfaces below. Do not infer vendor fields from another OpenAI API. See Ads Manager, Measurement Pixel, and Conversions API.

Use ad-conversion-hub for the canonical event envelope, consent gate, identity rules, retry policy, and adapter contract. Use ad-experiments for one-audience tests, seed sizing, and authorization before exporting customer data.

Account and access

OpenAI provides self-serve Ads Manager access in supported countries. The availability page is the authority for the current country list. If a country is not available for self-service, OpenAI directs advertisers to sign up and wait for availability; larger advertisers can contact the OpenAI Ads team. See Ads Manager availability and Advertise in ChatGPT.

Create the advertiser account at Ads Manager. The setup flow requires an OpenAI account, business details, account verification, billing, and a payment method. Campaigns do not deliver until required setup steps finish. See Ads Manager Beta Account Setup.

The Ads API key is issued in Ads Manager Settings. Each Ads API key is scoped to one ad account. Provision the Conversions API key in the Ads Manager conversions area. Send Ads API requests with Authorization: Bearer to https://api.ads.openai.com/v1. See Ads API authentication, Ads API overview, and Conversion setup.

Store local adapter names CHATGPT_ADS_API_KEY, CHATGPT_ADS_CAPI_KEY, and CHATGPT_ADS_PIXEL_ID in the server secret store. See Conversion setup.

Client-side OpenAI Measurement Pixel

The Measurement Pixel is a browser SDK. Initialize it with a Pixel ID, then call oaiq("measure", ...) when the measured action occurs. Load the official SDK near the top of the page <head>. See Measurement Pixel:

<script>
  (function(w,d,s,u){if(w.oaiq)return;var q=function(){q.q.push(arguments)};q.q=[];
  w.oaiq=q;var js=d.createElement(s);js.async=true;js.src=u;
  var f=d.getElementsByTagName(s)[0];f.parentNode.insertBefore(js,f);
  })(window,document,"script","https://bzrcdn.openai.com/sdk/oaiq.min.js");
  oaiq("init",{pixelId:"<CHATGPT_ADS_PIXEL_ID>"});
</script>

OpenAI requires pixelId for initialization. See Measurement Pixel.

If consent is required, set Pixel consent before initialization. A denial blocks measurement pings, and blocked events are not replayed after consent:

oaiq("consent", false);
oaiq("init", { pixelId: "<CHATGPT_ADS_PIXEL_ID>" });
oaiq("consent", true); // Call after measurement consent.

The Pixel defaults consent to true unless code sets false or it finds a stored denial. Apply the hub's consent decision before hashing or dispatching ad-user data. See Pixel consent and Conversion Measurement.

Rule setup and event mapping

Create a web Pixel source and an event setting in Ads Manager. For programmatic setup, call POST /conversions/pixels with name and client_type: "web". Then call POST /conversions/event_settings with name, event_type, attribution_window_days: 30, and one source_ids value. The response's id is the source ID; pixel_id is used by the Pixel and Conversions API. If these operations are unavailable, contact the OpenAI partner representative. See Conversion setup.

Map the hub events to OpenAI's supported event names. Send only names and data shapes from Supported Events:

Other supported names include appointment_scheduled, items_added, trial_started, and custom. Use custom only when no standard event fits. The list has no refund event. App events app_installed and app_opened are CAPI-only and require action_source: "mobile_app". See Supported Events.

For event data, type must match the data shape; include currency with amount. Monetary values use integer minor units, such as 2599 for USD 25.99. See event data shapes.

Server-side Conversions API

Send Conversions API events from your server only. The documented endpoint is POST https://bzr.openai.com/v1/events?pid=<PIXEL_ID>. Use the Conversions API key as the bearer credential. See Conversions API:

curl -X POST "https://bzr.openai.com/v1/events?pid=<CHATGPT_ADS_PIXEL_ID>" \
  -H "Authorization: Bearer <CHATGPT_ADS_CAPI_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "validate_only": false,
    "events": [{
      "id": "<CANONICAL_EVENT_ID>",
      "type": "order_created",
      "timestamp_ms": <EVENT_TIMESTAMP_MS>,
      "oppref": "<OPPREF>",
      "source_url": "https://shop.example.com/checkout/confirmation",
      "action_source": "web",
      "user": {"emails_sha256": ["<SHA256_EMAIL>"]},
      "data": {"type": "contents", "amount": 2599, "currency": "USD"}
    }]
  }'

Each event requires id, type, timestamp_ms, and data. A web event requires source_url when action_source is web. oppref is optional and must remain unchanged when sent. The event timestamp must be within the last seven days and no more than ten minutes in the future. See Conversions API event structure.

The request supports validate_only; true validates without saving. A batch can contain up to 1,000 events, but one failed event fails the batch. Use the hub's bounded retry and dead-letter policy. Reuse the same event ID on safe retries. See Conversions API.

Identity and consent

Require measurement: true before sending any event. Require ad_user_data: true before hashing or sending email, phone, external ID, or name identifiers. The hub owns that gate; the adapter must not bypass it.

OpenAI accepts emails_sha256, phone_numbers_sha256, external_ids_sha256, first_names_sha256, and last_names_sha256. Trim and lowercase email. Normalize phone to 8–15 digits with its country calling code. Trim external IDs and preserve case. Lowercase names and remove whitespace and ASCII punctuation. Hash the normalized UTF-8 value with SHA-256 and send lowercase 64-character hexadecimal text. Do not send raw identifiers. See Conversions API identity guidance and Pixel user data.

Geographic values are sent as raw strings in the documented user object. Send only fields that the event and consent record permit. Keep raw identifiers inside the server boundary and delete temporary normalized values after dispatch. See Conversions API user data.

The Pixel accepts an optional user object only at oaiq("init", ...). The Conversions API puts user inside each event. Use opt_out: true to opt an event out of future user-level personalization. See Pixel user data and Conversions API event fields.

Click ID and first-party cookie

OpenAI's click reference is named oppref. It appears at the end of the landing-page URL. Preserve it through redirects and landing-page navigation. The Pixel captures oppref in a first-party cookie, and server events may include the original value. See Conversion Measurement.

Do not invent or depend on an OpenAI cookie name. Capture oppref at first landing, persist it using the hub's first-party storage rules, and attach the value to the canonical event when consent permits. Do not require oppref before sending a confirmed purchase; OpenAI documents it as an optional CAPI field. See Conversions API event structure.

Deduplication

When the Pixel and Conversions API send the same conversion, put the same canonical ID in Pixel option event_id and CAPI field id. OpenAI uses the shared ID to deduplicate the copies. Reuse it when retrying the conversion. See Measurement Pixel events, Conversions API events, and Conversion Measurement.

Do not create a new ID for browser and server copies. An accepted request is not attribution proof. Reconcile platform reporting with payment-provider truth.

Ads Manager settings that override code

• Attach the event setting to the campaign before traffic starts. A sent event can show zero when its event type does not match the campaign configuration. Custom events require Event type: Custom and an exact custom event name. Historical mismatches do not backfill. See Measure Results.
• A Conversions-objective campaign selects oCPC and one standard conversion event. Custom events are not supported for oCPC, and the objective and event cannot change after campaign creation. See Conversion-optimized Campaigns.
• Ads Manager's Conversions total is click-through conversions. Where available, one-day view-through conversions appear separately, and a qualifying click takes precedence. See Measure Results and Measurement Pixel attribution.
• Billing for oCPC remains based on valid clicks. The bid cap guides conversion-oriented delivery; it is not a guaranteed cost per conversion. See Conversion-optimized Campaigns.

Audience data

OpenAI documents custom audiences for customer or prospect lists. The Ads API supports creating, adding, removing, replacing, merging, listing, retrieving, and archiving custom audiences. Custom audiences are not supported for EEA or Switzerland campaigns while personalized ads are unavailable. See Custom Audiences.

Upload only first-party data that you have the right to use for ads. The custom-audience guide supports raw email, raw E.164 phone, SHA-256 email, SHA-256 phone, and GAID formats with documented normalization rules. Require a human authorization under ad-experiments before any customer-list export. See audience data rights and formats.

Verification

For browser testing, call GET /conversions/events?pid=<PIXEL_ID> on the Ads API with the Ads API key. The stream returns up to 50 Pixel events received during the previous 15 minutes. It is available only to enabled accounts and proves Pixel receipt, not attribution or reporting. See Conversion setup event stream.

For platform proof, inspect the Ads Manager reporting tables or CSV export. OpenAI says attributed conversions may take 24–48 hours to appear. Compare the same date range and time zone. For business proof, reconcile conversions, orders, subscriptions, and refunds with your own server and payment records. See Measure Results.

Common pitfalls and security

• Do not send CAPI events to api.ads.openai.com; that host is for the Ads API. Send conversion events to the documented bzr.openai.com endpoint.
• Do not put CHATGPT_ADS_API_KEY or CHATGPT_ADS_CAPI_KEY in browser code, client-visible configuration, URLs, logs, screenshots, or source control. OpenAI explicitly requires server-side storage for the Conversions API key. See Conversions API key setup.
• Use HTTPS and the exact documented field names: event_id in Pixel options, id in CAPI events, timestamp_ms, oppref, and source_url.
• Use lowercase SHA-256 hexadecimal hashes. Never send raw email, phone, name, or external ID values. Never hash an already hashed value again.
• Keep a durable dispatch record with the canonical ID, adapter event name, consent decision, attempt time, redacted result, and retry count. A failed ad dispatch must not roll back a successful payment.
• Do not put chat content or unrelated profile data in conversion events. Send only documented event and user fields after consent.

Official sources checked (2026-08-31)

• Advertise in ChatGPT · Ads Manager availability · Account setup
• Ads API authentication · Ads API overview · Conversion setup
• Measurement Pixel · Conversions API · Supported Events
• Conversion Measurement · Measure Results · Conversion-optimized Campaigns
• Custom Audiences