ChatGPT Ads pixel and Conversions API: setting up conversion tracking
Last updated: August 24, 2026, verified against official OpenAI documentation. The event and parameter names quoted here come from OpenAI's developer documentation and may change during the beta.
Without conversion measurement, a ChatGPT Ads campaign is blind: you know what you spend, not what you get. More importantly, you cannot turn on conversion optimization at all. This page covers both official methods, the browser pixel and the server-side Conversions API, and how to run them together. The broader picture is in our ChatGPT Ads guide.
AI engines covered on this page
- ChatGPT
Why measurement is a prerequisite, not an option
Three reasons, one of them blocking:
- Blocking: conversion optimization (oCPC) requires tracking to already be set up, with the JavaScript pixel, the Conversions API, or both. With no signal, the system has nothing to optimize against.
- Ads Manager reporting includes a conversions column that stays empty if nothing is wired up.
- Your cost-per-acquisition math depends entirely on this data: without it you steer on CPC, which is spend, not outcome.
The general principle OpenAI sets out is simple: you create a data source in Ads Manager, then send conversion events to it using the pixel, the API, or both.
Pixel or Conversions API: which one?
| JavaScript pixel | Conversions API | |
|---|---|---|
| Where it runs | In the visitor's browser | From your server, only |
| Setup | One script in the head | Back-end development |
| Robustness | Sensitive to blockers and browser restrictions | OpenAI calls it a more reliable tracking source than the pixel alone |
| OpenAI's guidance | Starting point | Use when possible, for more accurate insights |
The pragmatic answer isn't "one or the other" but "both, with deduplication". The pixel goes in inside an hour and gets campaigns measuring immediately; the API goes in afterwards and makes measurement durable.
Installing the measurement pixel
The ChatGPT Ads Measurement Pixel is a browser SDK for measuring website events that can be attributed to ads in ChatGPT. The script loads asynchronously from https://bzrcdn.openai.com/sdk/oaiq.min.js, placed in the <head>, and initializes with your Pixel ID:
oaiq("init", { pixelId: "YOUR-PIXEL-ID" });
The pixelId parameter is mandatory and is created in Ads Manager. An optional debug parameter logs SDK activity to the browser console, useful during QA.
All measurement then flows through a single command: oaiq("measure", eventName, eventData, options).
Standard events, custom events and their constraints
Each standard event expects a data object whose type field has to match. OpenAI's developer documentation groups them like this:
| Family | Events | Expected type field |
|---|---|---|
| Commerce | order_created, items_added, checkout_started | contents |
| Content | page_viewed, contents_viewed | contents |
| Lead and registration | lead_created, registration_completed, appointment_scheduled | customer_action |
| Subscription | subscription_created, trial_started | plan_enrollment |
For contents events, the documented fields include amount, currency and a contents array of entries carrying id, name, content_type and quantity. plan_enrollment events expect a plan_id. The documentation specifies using integer values for amount and quantity.
When no standard event fits, a custom event is declared with a third argument plus an options object:
oaiq("measure", "custom", { type: "custom" }, { custom_event_name: "quote_requested" })
Custom event names follow strict rules: 1 to 64 characters, letters, numbers, underscores and dashes only, and they must start and end with an alphanumeric character.
Watch one structural limit: a custom event cannot be an oCPC optimization goal. If your business conversion needs to drive optimization, it has to be reported as a standard event.
Wiring the server-side Conversions API
The API is used from your server, only. The documented implementation points:
- You create a web conversion source and its Pixel ID via the
POST /conversions/pixelsendpoint. - You create a key that can send server-side events for the current ad account.
- That key must be stored in a server-side secret manager. The documentation is categorical: never place it in browser code, client-visible environment variables, logs or source control.
- The API accepts batches of up to 1,000 events. Critical for your error handling: if one event in the batch fails, the full batch fails.
That last rule deserves handling at design time: a batch rejected wholesale because of one malformed field on one order can wipe 999 valid conversions out of your reporting.
Deduplicating pixel and API: the rule not to miss
If you send the same conversion from the pixel and from the Conversions API, you have to tell the system, or you count it twice. The documented method:
- Reuse the same value as the API id and the pixel event_id.
- Send both events with the same Pixel ID.
- For custom events, use the same custom_event_name on both sides.
On the pixel side that looks like: oaiq("measure", "order_created", {...}, { event_id: "order_12345" }). Matching uses the Pixel ID, the event name and the event_id; for a custom event, custom_event_name replaces the event name in that logic.
In practice: use your order or lead ID as the deduplication key, it's the only value naturally available on both sides.
oppref: preserving it through to conversion, not just capturing it
The pixel captures oppref, OpenAI's click reference, and stores it in a first-party cookie (__oppref). Documenting that it gets captured is not enough: the official documentation stresses a point many implementations miss, oppref has to be preserved across redirects and navigation all the way to the page where the conversion is actually measured. A checkout flow that passes through a payment subdomain, a redirect after a form, or a cart that switches domains will lose the cookie along the way if nothing is set up to carry it forward.
Second point often missed: the Conversions API does not capture oppref for you, unlike the pixel. If you call the API server-side, it is up to your code to go fetch the oppref value (typically dropped by the pixel in a cookie or passed as a URL parameter) and include it explicitly in the call, when it is available. Without this step, an event sent only through the API loses its link to the ad click that preceded it.
The architecture OpenAI recommends comes down to three parts: the pixel on every page to capture oppref and lightweight events, the Conversions API for high-value events sent from your back-end (where you have the order, and where nothing can block the call), and both channels sending the same conversion with the same event_id.
Automatic advanced matching
Automatic advanced matching (AAM) helps connect website conversions to your ads when a click identifier is unavailable. The pixel automatically detects supported customer information from recognizable forms and other sources on your website, normalizes it, and securely hashes it using SHA-256 in the browser. The documentation specifies that no raw data is transmitted.
You can also supply hashed identifiers yourself in the user object at initialization: email_sha256, phone_number_sha256, external_id_sha256, first_name_sha256, last_name_sha256, plus non-hashed country, city, region and postal_code fields.
This feature touches personal data: enabling it should be decided with whoever owns data protection at your organization, especially in Europe.
Consent, GDPR and controlling the pixel
The SDK exposes a consent command, to be called before initialization so measurement is blocked until the user accepts:
oaiq("consent", false); then oaiq("init", { pixelId: "..." }); then oaiq("consent", true); once consent is granted.
Two things to remember. First, consent defaults to true unless explicitly set to false or a stored denial exists: on a European site you therefore need to call oaiq("consent", false) explicitly up front rather than relying on the default. Second, when the value is false, measurement events are not sent.
An opt_out parameter additionally excludes an event from user-level personalization; it defaults to false. The SDK also handles a privacy-preserving identifier, oppref, captured from the URL and stored in an __oppref cookie.
Context reminder: personalized ads are not initially available in the European Economic Area or Switzerland. That does not remove any obligation to handle consent for the measurement itself.
Content Security Policy: the hosts to allow
The most common silent failure on sites running a strict CSP: the SDK is blocked before it even initializes. The documented directives:
| Directive | Source to allow | Purpose |
|---|---|---|
| script-src | https://bzrcdn.openai.com | Load the SDK |
| connect-src | https://bzr.openai.com and https://bzrcdn.openai.com | Send and fetch events |
| img-src | https://bzr.openai.com | Image request fallback |
If the pixel reports nothing even though the code is in place, open the console with the debug parameter enabled: a CSP error shows up immediately.
What the pixel cannot do
One explicit limit, worth knowing before you design your tagging plan: the Measurement Pixel does not support app_installed or app_opened. Those events have to be sent server-side, via the Conversions API.
OpenAI also documents measurement partner integrations, including mobile measurement partner (MMP) integrations, for advertisers whose conversion happens inside an app.
One more thing to watch: using multiple Pixel IDs on the same site requires special configuration, documented separately by OpenAI.
Attribution: what gets counted, and how
OpenAI evaluates conversion events against the conversion events configured for your campaign and the applicable attribution window. Two rules to know:
- Click-through attribution uses the applicable configured click window.
- View-through conversions use a fixed one-day window after an eligible ad impression, independent of your configured click-through window.
And the reading rule that prevents math errors: the main Conversions column includes click-through conversions only. View-through conversions are separate supplemental reporting which, per OpenAI, should not be added to Conversions or used for core performance metrics like CPA.
Pre-launch QA checklist
- Data source created in Ads Manager, Pixel ID retrieved.
- Script loaded in the head, init called with the correct Pixel ID.
- Consent wired before init on European sites.
- Standard events firing in the right places, with the correct type field.
- Deduplication in place if you double up with the API: same value as id and event_id, same Pixel ID.
- CSP updated for all three directives.
- Debug mode on during QA, then off.
- Landing page reachable by OAI-AdsBot: a blocked page can get the ad rejected regardless of how good your tagging is. Our ChatGPT Ads landing page checker tests exactly that.
- One single active standard event chosen as the goal if you're going for oCPC, knowing it cannot be changed after campaign creation.
Frequently asked questions
Is conversion tracking mandatory on ChatGPT Ads?
Does the Conversions API capture oppref on its own?
Do I have to choose between the pixel and the Conversions API?
How do I avoid counting a conversion twice?
Can a custom event be an oCPC goal?
Does the pixel respect user consent?
My pixel isn't reporting anything, what do I check first?
How do I measure an app install?
What is the attribution window?
SEO score, GEO score, performance and responsive: 49 analyses checked, instant AI Overviews verdict.
Related guides
ChatGPT Ads: the complete 2026 guide to advertising on ChatGPT
How ChatGPT Ads works, where it's available, how to set up an account, structure a campaign, target with context hints, and budget for it: the reference guide, kept continuously updated.
Read the guideChatGPT Ads pricing: bids, budgets and what a campaign really costs
What a ChatGPT Ads campaign actually costs: the three bidding models, OpenAI's recommended starting bid, the documented daily minimum, and why there is still no reliable industry benchmark.
Read the guideChatGPT Ads for ecommerce: running campaigns from a product feed
How a merchant connects a catalog to ChatGPT Ads: the three feed upload methods, item expiry, the is_ads_eligible field, and how ads differ from organic product results.
Read the guide