OpenAI Ads (Conversions)

openai ads conversions api is openai's server side conversion api for chatgpt ads this destination sends conversion events directly from chord to openai, so measurement is unaffected by ad blockers, browser tracking restrictions and cookie expiry pair it with the openai ads pixel destination the two are complementary the pixel captures openai's oppref click identifier in the browser, which the conversions api needs but does not collect for itself getting started you will need pixel id — your openai ads pixel id api key — your openai ads conversions api key create both in openai ads manager under tools > conversions , which offers a conversion key and a pixel id use the conversion key — not the api key under settings ads manager exposes three credentials and only two of them belong here the key under settings authenticates openai's separate management api, and the conversions api rejects it as unauthorized chord never needs it the conversion key is per ad account, not per pixel — one key covers every pixel in the account optionally custom event mapping — routes a chord event that openai has no standard equivalent for onto a custom event you have registered in ads manager validate only — openai validates each event and records nothing use it to confirm an integration end to end without affecting reporting, then turn it off important if you are also using the openai ads pixel destination, both must be configured with the same pixel id and the same custom event mapping openai deduplicates on the combination of pixel id, event name and event id — with a different pixel id, one purchase is counted twice connecting to the openai ads conversions api cdp destination warning before connecting destinations in the chord cdp, please verify with all destination owners that all non chord cdp configured destinations are disabled running external destinations alongside configured chord cdp destinations can result in duplicate events downstream log into the chord data platform navigate to the cdp click the "add" button next to destinations select openai ads conversions api from the destination catalog enter the destination name, your pixel id and your api key optionally configure custom event mapping and validate only click "create" to connect verifying an integration enable validate only before sending live traffic openai will validate the full shape of every event and record nothing, so you can confirm the integration is correct against a production pixel without affecting reporting turn it off once you are satisfied deduplication every event carries id , set to the chord messageid openai deduplicates on the combination of pixel id , event name and event id , keeping the first event it receives for a matching key and ignoring later duplicates the openai ads pixel destination sends the same messageid as its event id , so a conversion reported by both the browser and your server is recorded once this also protects you if you are sending your own events to openai alongside chord reuse the chord messageid as your event id and openai will merge them rather than double counting event mapping openai accepts a fixed set of event names a chord event with no equivalent is skipped and logged — it is not forwarded under a made up name, because openai silently discards an unregistered event name, which is indistinguishable from a successful send chord event openai event data type page page viewed contents product viewed contents viewed contents product added items added contents checkout started checkout started contents order completed order created contents signed up registration completed customer action email captured lead created customer action subscription created subscription created plan enrollment to forward anything else, first create a custom event in chatgpt ads manager, then add a custom event mapping entry pointing your chord event name at it names are lowercased and spaces become dashes, so wishlist added becomes wishlist added ; the result must be 1–64 characters of lowercase letters, numbers, underscores or dashes event attributes openai attribute chord source (priority order) notes id messageid the deduplication key type — set from the event mapping table custom event name custom event mapping custom events only timestamp ms timestamp → receivedat milliseconds since epoch action source — always web source url context page url oppref properties oppref → the captured click identifier see attribution below data see below conversion data openai attribute chord source (priority order) notes type — set from the event mapping table required by openai amount properties total → properties revenue → properties value minor currency units see below currency properties currency defaults to usd required whenever amount is present contents properties products\[] omitted for customer action events, which do not accept it plan id properties subscription id → properties plan id subscription created only each entry in contents is built from a product openai attribute chord source (priority order) id properties products\[] product id → sku → id name properties products\[] name content type properties products\[] category quantity properties products\[] quantity (defaults to 1 ) amount properties products\[] price , in minor units currency the order currency amounts are sent in minor units openai expects every monetary amount as an integer in the currency's minor unit , so $129 99 is sent as 12999 chord converts this for you zero decimal currencies are handled correctly 1000 jpy is sent as 1000 , not 100000 this matters because openai accepts either value without complaint — a mistake here would silently report every conversion 100 times too high conversion matching visitor identifiers are sha 256 hashed before being sent plaintext pii is never transmitted openai attribute chord source (priority order) normalization emails sha256 context traits email → properties email trimmed and lowercased, then hashed phone numbers sha256 context traits phone → properties phone country code kept; whitespace, punctuation, a leading + and leading zeroes removed must be 8–15 digits external ids sha256 userid trimmed, case preserved , then hashed first names sha256 context traits first name → properties first name lowercased, whitespace and ascii punctuation removed, accents preserved last names sha256 context traits last name → properties last name same as first name cities context traits address city sent unhashed regions context traits address state sent unhashed postal codes context traits address zipcode sent unhashed countries context traits address country sent unhashed obref the obref cookie set by the openai ads pixel sent unhashed ip address requestip → context ip sent unhashed user agent context useragent sent unhashed a value that cannot be used is omitted rather than hashed — placeholders such as n/a or unknown , and phone numbers too short to be real, are dropped, since hashing them would send a digest that matches nobody a value that is already a sha 256 hash is passed through rather than hashed twice these normalization rules match the openai ads pixel destination exactly, so the same person produces the same digest on both surfaces note that the conversions api's field names are plural lists ( emails sha256 ) while the pixel's are singular ( email sha256 ) — both are correct for their own surface chord sends one value per identifier openai accepts up to three per list and ignores the rest android advertising ids are forwarded as android advertising id on android traffic only openai has no equivalent field for an ios advertising id, so one is omitted rather than sent in the wrong place attribution openai appends an oppref query parameter to ad click through urls, and openai's documentation is explicit that — unlike the pixel — the conversions api does not capture it for you chord handles this the browser library captures oppref from the landing page url, along with the oppref and obref cookies the openai ads pixel sets, and carries them on every subsequent event including the purchase installing the openai ads pixel destination alongside this one is therefore the recommended setup — without a source of oppref , server side conversions cannot be attributed to the ad that produced them if your storefront resolves the click identifier itself, send it as properties oppref and it will be used in preference timestamps openai rejects an event timestamped more than 7 days in the past or more than 10 minutes in the future if an event carries no parseable timestamp, chord falls back to the time it was received and then to the current time — an approximate time is better than a rejected batch, which would lose the event entirely retries rate limits ( 429 ) and openai server errors ( 5xx ) are retried a rejected event — a validation failure such as a malformed field — is not retried, because the same payload would be rejected again; it is logged instead so it appears in the cdp function logs property mappings openai validates each event against a closed schema the conversion data accepts only type , amount , currency , contents and plan id , and there is no custom data field an unrecognized field causes openai to reject the event, so chord forwards no custom properties to this destination mappings that change where a supported field is read from work normally — that is what the table below is for if you need to segment on a property openai has no field for, register a custom event in ads manager and route to it with custom event mapping instead use custom property mappings if the default field resolution does not match your data model destination path description properties email email for conversion matching properties phone phone for conversion matching properties first name first name for conversion matching properties last name last name for conversion matching properties total primary conversion value properties revenue fallback conversion value properties currency currency code (e g usd ) properties oppref openai click identifier, if your storefront resolves it properties subscription id plan id for subscription events properties products\[] product id product content ids properties products\[] price per item price properties products\[] quantity per item quantity properties products\[] name product display name properties products\[] category product content type troubleshooting no events appear in ads manager confirm the api key is the conversion key from the conversions section, not the api key from settings the settings key belongs to openai's management api and is rejected here confirm the pixel id and the key belong to the same ad account confirm validate only is switched off while it is on, openai validates events and records nothing check the cdp function logs for the response openai returned conversions are attributed to no campaign confirm the openai ads pixel destination is installed on the storefront, since it is what captures oppref confirm the oppref cookie is being set and is not blocked by a consent tool a conversion is counted twice confirm the openai ads pixel destination uses the same pixel id confirm any events you send to openai outside chord reuse the chord messageid as their event id an event is missing entirely check the cdp function logs for a "skipping unsupported event" warning openai accepts only the fixed event set above; anything else needs a registered custom event and a custom event mapping entry updated 31 august 2026