What you need to know about OpenAI’s Conversions API

OpenAI’s Measurement Pixel and Conversions API docs are explicit that the two are meant to run together. The pixel lives in the browser, the API on your server, and they share one Pixel ID so events can be deduplicated. What they don’t address is what happens when there’s no browser at all, a backend job, a webhook, or a CRM update days after the visit.

At that point there’s nothing to read an attribution cookie from, and no cookie means nothing to match the event to a click.

The Conversions API depends on identity data the pixel captures automatically. Skip the pixel, or lose it before a conversion is confirmed, and you’d have to capture that click reference yourself. You’d also need to send enough matching data, a hashed email, phone or IP address, for OpenAI to connect it to a click.

OpenAI itself doesn’t warn you about this directly. We covered the broader setup process in Part 1 of this series. This guide goes deeper on conversion tracking itself, the one piece most setups get wrong.

Practical steps if you’re setting this up today

1. Create a data source in OpenAI Ads Manager and save its Pixel ID. You need it whether you send events from the browser, the server, or both.
2. Install the base Measurement Pixel on every page, inside the <head>, before any server-side event is sent. This is the step teams skip, and the one that breaks attribution silently. (See our guides for Shopify and WordPress and WooCommerce if you haven’t already.)
3. Decide which events need to be server-side. Anything your backend confirms later than the page load, a lead qualifying, a trial converting, a purchase settling, is a candidate.
4. Match IDs across both channels. If an event could be sent by the pixel and the server, give it the same event ID in both so OpenAI deduplicates rather than double-counts.
5. Create a conversion event setting for each event you want reported. Mark the ones you want as optimisation goals as standard events. Custom events are reporting-only.
6. Attach the setting to the campaign, and if you’re bidding on conversions, make sure exactly one active standard event setting is selected at campaign creation.
7. Validate before you go live. Send a validate_only request for each event type, fix anything it flags, then send one real test event and confirm it appears in the Conversions tab within a few minutes.

How OpenAI tracking is structured

OpenAI Ads splits conversion tracking into two integrations, built on one shared container called a data source which receives your events. It’s identified by a pixel_id, used when sending events, and a separate id, used when configuring which events count as conversions.

1. Measurement Pixel. The browser-side script. It fires from the customer’s own browser and captures the ad-click reference first.
2. Conversions API (CAPI). The server-side integration. It sends events your own backend already knows about, a confirmed order, a completed signup, rather than relying on the browser to report them.

The rule that ties it together is the conversion event setting. It tells a campaign which event from a data source counts as a conversion, and, for standard events, as an optimisation goal. Standard events, like lead_created or order_created, can be used as optimisation goals. Custom events, named with your own custom_event_name, are reporting-only.

There are two separate keys that gate access, an Advertiser API key for managing campaigns, and a Conversions API key purely for sending events. Both are live on your server, with neither belonging near page code.

If you’re also running product feed campaigns, pair this with our guide to getting your feed live on OpenAI Ads.

The two cookies, and where each one goes

The pixel sets two first-party cookies, and they do different jobs. __oppref stores the ad-click reference from the landing page URL, and expires 30 days after it’s last written. __obref stores a randomly generated browser reference for your site, and lasts 365 days whether or not another ad click refreshes it.

They also go in different places in the event payload. oppref sits at the top level of the event, while obref goes inside the user object, as user.obref.

Mixing these up, or sending both in the same place, is one of the more common reasons a server event fails to match.

None of this happens automatically for a server event sent without a browser in the loop. OpenAI’s Conversions API docs do let you pass oppref yourself, and supply a hashed email, phone number, IP address or user agent to help matching. A pixel-free setup isn’t impossible, though it’s meaningfully harder to get right than reading two cookies the pixel already wrote for you.

How deduplication actually works

Because the same conversion can, in theory, be reported twice, once by the pixel and once by your server, OpenAI deduplicates on matching fields: the Pixel ID, the event name, and an event ID. The pixel’s event_id and the Conversions API’s id are the same field under two names, and have to match exactly for OpenAI to recognise them as one event. Custom events add a fourth matching field, the custom_event_name.

This is also how retries are meant to work. Each event needs a timestamp_ms within the last seven days and no more than ten minutes in the future, so send events close to real time rather than batching them later.

If a request fails and you resend it, reuse the same event ID. OpenAI keeps the first event it saw for that Pixel ID, event name and ID, and silently drops the repeat.

How we’re approaching this for a client

We’re setting this up for an Addesu client with a lead-to-subscription funnel. The conversion that funds the business happens weeks after the first form fill, first at the trial stage, then again at the paid plan.

The base pixel sits on every page and handles attribution. On top of it, three server-side events carry the story forward. A Lead event fires when someone first converts, a Trial event when they start a free trial, and a Paying Subscriber event when they convert to a paid plan.

Each event carries an estimated value, sent as a whole number in the currency’s minor unit, (i.e.pence instead of pounds). That way, each stage will show up with its own value in OpenAI’s reporting, rather than being lumped into one generic lead count.

The attribution values the pixel captures at the lead stage get stored against that person’s record, then reused on the later events. A backend or webhook event has no browser to read cookies from, so those values need storing at lead capture.

The Conversions API key that authorises all of this lives on the server only. Every event type goes through a validate_only check first, the recommended way to catch a bad payload before anything real reaches OpenAI.

The result we’re after → instead of one lead count, the funnel will report three distinct stages with their own values in OpenAI Ads Manager, each one correctly attributed back to the ad click that started it. If your own funnel has more than one conversion that matters, the same pattern applies. Capture the click reference early, store it, and send it back downstream with whichever event reflects the value to your business.

Part of our OpenAI Ads series

If you haven’t set everything else up yet, our guide on what you need to know before you set up OpenAI Ads covers the basics, and our guide on getting your product feed live on OpenAI Ads covers product feed campaigns specifically. For installing the base pixel itself, see our guides for Shopify and WordPress and WooCommerce.