OpenAI Ads Connection
What you can do
- Conversion events — send server-side events (page_viewed, order_created, lead_created, checkout_started, etc.) from your Signals to an OpenAI Ads Pixel, so OpenAI can attribute them to your ads in ChatGPT and use them for optimisation.
The OpenAI Ads connection is available for Signals only. It cannot be used as an audience destination.
It uses OpenAI's Conversions API, which sends events straight to OpenAI from BPP — independent of the OpenAI Pixel on your website.
Prerequisites
- An OpenAI Ads account with access to Ads Manager.
- An OpenAI Ads Pixel — you need its Pixel ID.
- A Conversions API key, created from the Conversions tab in OpenAI Ads Manager.
- Your event table must have an event date in the last 7 days for the events you want to send — OpenAI rejects older events. See Things to know.
Find your credentials
All the values the connection needs are in OpenAI Ads Manager.
| Value | Where to find it | Required |
|---|---|---|
| Conversions API Key | Ads Manager → Conversions tab. Create a key (key icon in top right section) and copy it. | Yes |
| Pixel ID | Ads Manager → Conversions tab. | Yes |
| Advertiser API Key | Ads Manager → Settings page. | No — for future support of Audiences and other BPP features |
Store the Conversions API key somewhere safe when you create it. BPP never shows it again once saved (see Updating credentials).
Setup
- Navigate to Connections and click New Connection.
- Give the connection a Connection Name.
- Select OpenAI Ads as the Connection App.
- Under OpenAI Ads Credentials, fill in:
- Conversions API Key — the key from the Conversions tab.
- Pixel ID — the ID of an OpenAI Ads Pixel that this key can send events to.
- Advertiser API Key (optional) — leave it empty unless you have a reason to add it. Signals do not use it.
- Click Add Connection.
BPP verifies the connection right after you save it — there is no separate "Test" button. It sends a single validation-only test event to OpenAI's Conversions API using your key and Pixel ID. OpenAI checks the request but does not record the event, so nothing shows up in your reporting. If you entered an Advertiser API Key, BPP also checks that key against your OpenAI Ads account.
- Active (connected) — OpenAI accepted the key and Pixel ID.
- Error (disconnected) — OpenAI rejected the key, the Pixel ID, or the Advertiser API Key (if provided). See Troubleshooting.
Why is the Pixel ID asked for twice? The Pixel ID on the connection is only used to verify the API key. The Pixel that actually receives your events is chosen per destination when you add OpenAI Ads to a Signal. That way, one connection can feed several Pixels from different signals.
How it works
- BPP reads the events that match your signal's trigger filters from your data warehouse.
- BPP drops events whose event date is older than 7 days or more than 10 minutes in the future — OpenAI does not accept them.
- For each remaining event, BPP:
- Collects the user identifiers you mapped, normalising and hashing them where OpenAI requires it (see User identifiers).
- Computes the conversion amount (value) using the provided value or formula.
- Builds an OpenAI event with the event type, timestamp, action source, value, currency, and user identifiers.
- BPP sends the events to OpenAI in batches of up to 1 000 events per request.
- The sync result is saved to Sync History.
What to configure in BPP
When you add an OpenAI Ads destination to a Signal (Signal Destinations → Add Destination → Destination App: OpenAI Ads):
| Field | Required | What it does |
|---|---|---|
| OpenAI Ads Account | Yes | The OpenAI Ads connection to use. Cannot be changed after the destination is created. |
| Event Type | Yes | The OpenAI event type — see Event types. |
| Pixel ID | Yes | The OpenAI Ads Pixel that receives these events. It does not fall back to the Pixel ID specified in the Connection. |
| Custom Event Name | Required if Event Type is set to Custom | Shown only when Event Type is Custom. The name of your custom event. Use 1–64 letters, digits, underscores or hyphens, starting and ending with a letter or digit. |
| Action Source | Yes | Where the conversion took place — see Action sources. |
| Source URL Field | Required if Action Source is set to Web | Shown only when Action Source is Web. The column holding the page URL where the event happened (e.g. https://example.com/checkout). Must include the scheme and host. |
| Attribution Reference Field (oppref) | No | The column holding the OpenAI-provided attribution reference (oppref) for the event. Similar to gclid or fbclid. It is sent exactly as stored, without any normalization or hashing. |
| Order ID Field | No | The column that uniquely identifies each conversion (e.g. an order or transaction ID). Strongly recommended when available — see Deduplication. |
| Conversion Value | Yes | A scalar value or formula that computes the value of each event (e.g. the order total). Enter the value in the normal currency unit — e.g. 42.00 for $42.00. BPP automatically converts it to the minor unit OpenAI expects. |
| Currency Code | Yes | The currency applied to every event from this destination (e.g. EUR, USD). |
| User Identifiers | At least one | The identifier columns used to match the event to an OpenAI user — see User identifiers. |
Event types
For a complete description and up-to-date information refer to the
OpenAI Ads Supported Events documentation.
Note that you do not have to specify the Data type. BPP Automatically maps it to the corresponding Event type.
Action sources
| Action Source | Notes |
|---|---|
| Web | Requires a Source URL Field. |
| Mobile App | Required for App Installed and App Opened. |
| Offline | E.g. a deal closed in your CRM. |
| Physical Store | In-store purchase. |
| Phone Call | Conversion that happened over the phone. |
| Conversion that happened via email. | |
| Other | Anything else. |
User identifiers
Under User Identifiers, click + Add Parameter and map each identifier you have to a column in your data. You need at least one. The more you map, the better OpenAI can match events to users.
| Parameter | How BPP sends it |
|---|---|
| Hashed Email | Trimmed, lowercased, then SHA-256 hashed. |
| Hashed Phone | Spaces, brackets, dots, dashes, a leading + and leading zeros are removed, then SHA-256 hashed. Must end up 8–15 digits, otherwise the value is ignored — store numbers with the country code (e.g. +14155552671). |
| Hashed External ID | Trimmed, lowercased, then SHA-256 hashed. |
| Hashed First Name | Trimmed, lowercased, then SHA-256 hashed. |
| Hashed Last Name | Trimmed, lowercased, then SHA-256 hashed. |
| Country | Sent as stored. Use the two-letter ISO code (e.g. US, IT). |
| Region | Sent as stored. |
| City | Sent as stored. |
| Postal Code | Sent as stored. |
| IP Address | Sent as stored. |
| User Agent | Sent as stored. |
| Android Advertising ID | Sent as stored. |
| User Attribution Reference (obref) | The OpenAI-provided user attribution reference, sent as stored — do not hash or edit it. |
Notes:
- Already hashed? If a value is already a SHA-256 hash (64 lowercase hex characters), BPP sends it unchanged instead of hashing it again.
- Raw email, phone, first name, last name never leave BPP. They are always hashed before sending.
- Multiple values: if a column holds a list (e.g. several emails for one user), BPP sends up to 3 values per identifier (limitation of OpenAI)
- Events with no usable identifier are skipped and counted as failed.
Deduplication
OpenAI deduplicates events that share the same Pixel, event type, and event ID. BPP builds the event ID for you from the event type, the BPP user, the event date, and — if mapped — the Order ID Field.
- Map an Order ID Field whenever you can. Without it, two conversions of the same type from the same user on the same event date get the same ID, and OpenAI keeps only the first.
- BPP's event IDs do not match the IDs your website Pixel sends. If the same conversion is tracked by both the OpenAI Pixel on your site and a BPP signal, OpenAI will count it twice. Send a given conversion from one source only — for example, use BPP for offline or back-office conversions that the Pixel cannot see.
- BPP only picks up events newer than the last successful push, so the same event is never sent twice by BPP itself (see How Signal Syncs Work).
Tips
- Run a Preview first. Before doing a real run, trigger a Preview Mode run and inspect the generated CSV to confirm the events, values, and identifier columns are correct. Note that the CSV shows your identifier columns before BPP hashes them.
- Keep your data fresh. Only events from the last 7 days are accepted. Make sure your event table is updated at least daily and that the signal is enabled, or events will age out before they are sent.
- Map several identifiers. Hashed email plus IP address and user agent (for web events) or Android Advertising ID (for app events) give OpenAI the best chance of matching.
- Store timestamps in UTC. The 7-day window is checked against the event date in UTC.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Connection shows Error right after saving | The Conversions API Key is wrong or revoked, the Pixel ID is wrong, or the key cannot send events to that Pixel. If you entered an Advertiser API Key, it may be the one that's invalid — remove it (Signals don't need it) and save again. |
| "Add Destination" button stays disabled | A required field is missing: Pixel ID, Event Type, Action Source, Conversion Value, Currency Code, at least one identifier, a Custom Event Name (for Custom), or a Source URL Field (for Web). An identifier row with a parameter but no value also blocks saving. |
| Action Source dropdown is greyed out | The Event Type is App Installed or App Opened, which always use Mobile App. |
| Sync is Skipped with "No valid events created (…, stale=N)" | All selected events were older than 7 days (or more than 10 minutes in the future). Check that your event table is up to date and timestamps are in UTC. |
| "Uploaded X/Y events" with rows dropped | Some rows had no usable identifier, a missing event date, or (for Web) an empty source URL. They are skipped individually; the rest are sent. |
| A whole batch failed with "OpenAI Ads responded 4xx: …" | OpenAI rejects a batch as a whole if any one event in it is invalid — the message includes OpenAI's reason. Fix the offending data (e.g. a malformed source URL or custom event name) and the next run will pick the events up if they are still within 7 days. |
| Fewer conversions in OpenAI than in BPP | Events without an Order ID Field from the same user, type, and day were deduplicated into one. Map an Order ID Field. |
| More conversions in OpenAI than expected | The same conversions are also tracked by the OpenAI Pixel on your website. See Deduplication. |
| Conversion values are 100× too large or too small | The Conversion Value formula must return the value in the normal currency unit (e.g. 42.00), not in cents. |
Things to know
- Only the last 7 days. OpenAI accepts events with a timestamp in the last 7 days and at most 10 minutes in the future. BPP skips anything outside that window automatically.
- One bad event fails its batch. OpenAI validates each batch of up to 1,000 events as a unit. If one event is rejected, the whole batch is rejected; other batches in the same run are still sent. Failed batches are not retried within the run.
- Partial runs show as Complete. If some events were sent and others failed, the destination still shows Complete — check the Sync History message (e.g. "Uploaded 950/1000 events") for the details.
- Currency is fixed per destination. The currency you choose applies to every event from the destination. Currencies without decimals (e.g.
JPY) and with three decimals (e.g.KWD) are converted correctly. - No conversion analysis yet. Conversion Analysis is not available for OpenAI Ads destinations.
Updating credentials
OpenAI Ads connections use a static API key — there is no OAuth login and nothing expires on its own. After saving, the API key fields stay empty and show Leave blank to keep the current key.
- To keep the stored key, leave the field blank.
- To replace it (e.g. after rotating the key in Ads Manager), type the new key and click Update Connection.
All signals using the connection pick up the new key on their next run.