OpenAI Offline Conversions API

Overview

OpenAI Offline Conversions API reports conversions that happened away from your website, so ChatGPT Ads campaigns can be attributed to outcomes recorded in your own systems.

That covers a sale completed in a shop, an order taken over the phone, a booking confirmed by email, or an opportunity marked won in a CRM. Signals reads the outcome from the source and reports it against your OpenAI pixel.

For conversions that happen on the website itself, use OpenAI Conversions API.

Platform documentationOpenAI Ads Conversions API

Supported sources

Sources supported by OpenAI Offline Conversions API

Category	Supported
API	Datahash API
CRM	ActiveCampaign Agile Apptivo Attio Bexio Bitrix24 Capsule Close Coevera Copper Freshsales HubSpot Insightly Kommo LeadSquared Microsoft Dynamics Monday Odoo Pipedrive Salesforce VTiger Zithara Zoho
Database	Apache Cassandra ClickHouse CockroachDB Couchbase CouchDB IBM DB2 MariaDB Microsoft SQL Server MongoDB MySQL Oracle PostgreSQL
File & storage	Files - AWS S3 Files - GCP Files - FTP Google Drive Microsoft OneDrive Box Dropbox Filebase BackBlaze Cloudian DigitalOcean Linode MinIO OVHcloud Tencent Vultr Wasabi
Warehouse	Amazon Redshift Google BigQuery Snowflake

Prerequisites

Before connecting OpenAI Offline Conversions API, make sure you have:

• A ChatGPT Ads account with access to OpenAI Ads Manager.
• Brand review approved on that ad account. An account cannot serve ads until it is, and conversions reported against a campaign that is not running will not show anything useful.
• A Pixel ID and a Conversions API key, both provisioned from the conversions tab in Ads Manager.
• Pixel and Conversions API key creation enabled on the ad account. This is gated by OpenAI, so if the conversions tab will not create either one, contact your OpenAI representative.
• A source connected in the same Datahash project holding the conversion data.
• Conversions no older than seven days in the data you are sending. OpenAI rejects events with a timestamp outside that window, which rules out most historical backfills.
• A Datahash Studio account with the target project selected.

ChatGPT Ads is a beta product and Ads Manager is not available everywhere. At the time of writing OpenAI lists Australia, Canada, Japan, Korea, New Zealand, the United Kingdom and the United States. Check OpenAI’s availability page rather than this one, since the list is expanding.

Authentication

In Studio, open Destinations, find OpenAI, and click the Offline Conversions API tile. This connector uses credentials rather than a sign-in.

1. Enter the Pixel ID.
2. Enter the API Key.
3. Click Next.

Field	Where to find it
Pixel ID	Provision it from the conversions tab in OpenAI Ads Manager, where a pixel is created as a data source. Ads Manager shows two values against a data source; the Pixel ID is the one used for sending events, not the internal source ID.
API Key	Provision it from the same conversions tab. This is the Conversions API key, which is not the same thing as an OpenAI platform API key used for model access, and not the same as the Ads API key used for campaign management. Only the Conversions API key will authenticate here.

Caution

The API key is a credential. Never share it outside the Datahash setup screen, and note that OpenAI shows it once when it is created.

If the conversions tab will not let you create a pixel or a key, the feature is not yet enabled on your ad account. That is a permission OpenAI grants, so it needs raising with your OpenAI representative rather than retried.

Configuration

Event source

1. Choose the Event Source. It sets the action source OpenAI records against every event on the instance.

Offline suits conversions read out of a CRM, a file or a warehouse. Pick a more specific value such as physical store or phone call if your list offers one, since it applies to the whole instance and cannot vary per record.

Event name mapping

Mapping is optional, but leave it empty and your source event names pass through as they are. OpenAI matches conversions to a campaign on the event name, so a name it does not recognize reports zero and will not backfill once corrected. Map them unless your source already uses OpenAI’s names.

1. Pick an OpenAI Event Name, then type the Source Event Name it corresponds to.
2. Add rows with the plus icon, remove one with the bin icon, reset one with the refresh icon.
3. Click Finish. Go Back returns you to the credentials step.

The dropdown holds the events OpenAI accepts, including order created, items added, checkout started, lead created and a custom option. Studio shows them in sentence case where OpenAI’s API uses underscores, so order created and order_created are the same event.

Manage instance

To add another, open Manage Instances and click Add Instance. To change one, open it from Manage Instances, use the menu in the top right and choose Edit, update the fields and click Finish. Cancel keeps the previous configuration running, so updates apply only after you finish.

Data & identifiers

Signals sends the fields your source maps. Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach OpenAI.

Required

Field	When it is required
Event ID	Always. Your own unique reference for the event. It is also what OpenAI matches on to discard duplicates.
Event name	Always. It has to resolve to one of the event names OpenAI accepts. See Configuration.
Event time	Always. It has to fall within the last seven days and no more than ten minutes in the future.
Action source	Always. Set during configuration rather than per record.

Recommended

These are the identifiers OpenAI uses to match a conversion to someone who saw an ad. Email and external ID are hashed; the rest are sent as they are.

Field	Format
Email address	One address. Trimmed and lowercased before hashing.
External ID	A stable pseudonymous ID of your own, such as a customer number. Hashed.
Country	Two-letter ISO 3166-1 code.
City	Trimmed and lowercased.
Postcode	Letters, numbers, spaces or hyphens.
Client IP address	IPv4 or IPv6.
Client user agent	The browser user agent string.

OpenAI does not accept a phone number, in raw or hashed form. It is prohibited rather than merely unsupported, so there is no point mapping one. Email and external ID are the two identifiers worth getting right.

There is one identifier specific to OpenAI worth knowing about. When someone clicks an ad in ChatGPT, OpenAI appends a click reference called oppref to the landing page URL, and the browser pixel stores it in a first-party cookie. The server side does not capture it for you. If you can carry that value through to the record you send, matching improves considerably; if you cannot, the other identifiers still work.

The full field specification is published by OpenAI at developers.openai.com/ads/conversions-api, and it is the authority on what is accepted rather than this page.

Best practices

• Map your event names rather than letting them pass through, unless your source already uses OpenAI’s. This is the single most common reason an offline instance looks healthy and reports nothing.
• Check the age of your data before the first run. OpenAI rejects anything with a timestamp older than seven days, so a monthly export will mostly be refused.
• Send a stable event ID derived from something that does not change, such as a transaction reference. Without one, a re-read of the same file reports the same conversions again.
• Validate the file before sending a large batch. OpenAI accepts up to a thousand events at a time and fails the whole batch if one event in it is invalid, so a single malformed row can take out everything around it.
• Map email and external ID. They are the two identifiers that drive matching, and phone is not accepted at all.
• Choose the event source deliberately. It applies to the whole instance, so use two instances if you have both shop sales and call center orders.
• Allow a day or two before judging the numbers. OpenAI states that attributed conversions can take 24 to 48 hours to appear in Ads Manager.

Troubleshooting & FAQ

Credentials are rejected at the Next step. Check the Pixel ID is the sending value from the conversions tab rather than the internal source ID, and that the key is a Conversions API key rather than a platform or Ads API key.

The conversions tab will not create a pixel or a key. The feature is not enabled on your ad account. OpenAI gates it, so contact your OpenAI representative.

Events are accepted but Ads Manager shows zero. The event name does not match the conversion configured on the campaign. Either add a mapping row or correct the one you have. Events sent before the fix will not backfill.

A whole batch failed. OpenAI fails an entire batch if any single event in it is invalid. The usual culprits are a timestamp outside the seven day window and a malformed email.

Older conversions are not being accepted. They are outside the seven day window. There is no way to widen it, so the export has to run more often.

Duplicate conversions. Usually a replayed batch or a re-read file with a newly generated event ID.

Nothing is arriving. Confirm a source is connected in the same project and sending, and that the setup was finished rather than left at the mapping step.

Delivery stopped. The API key may have been revoked or the pixel deleted in Ads Manager. Provision a fresh key and reconnect.