OpenAI Ads Conversions API
Forward your AxiTrace server-side events to OpenAI Ads (ads.openai.com, the ad platform behind ChatGPT) - the same way Facebook CAPI, TikTok Events API and Reddit CAPI already work. You paste two values from OpenAI Ads Manager, and AxiTrace sends every tracked event to your OpenAI Ads account in real time, server-side: immune to ad blockers and browser privacy features.
Merchant prerequisites
Before you can connect, you need:
- An OpenAI Ads account at ads.openai.com. If OpenAI's own account or pixel setup flow shows a category-eligibility error, that error comes from OpenAI, not AxiTrace.
-
A "Web" data source created in Ads Manager. Creating it issues a Pixel ID
- this is the
pidquery parameter the Conversions API call requires. -
A Conversions API key, issued in Ads Manager. It is an OpenAI secret key - usually a
service-account key starting
sk-svcacct-- and is the Bearer token AxiTrace uses for server-to-server calls.
AxiTrace needs none of the above beyond the Pixel ID and API key: no OpenAI partner or app review, no OAuth consent screen, and no client secret rotation.
Official OpenAI documentation:
Copy your Pixel ID
- Open OpenAI Ads Manager.
- Go to Data Sources and open (or create) your Web data source.
- Copy the Pixel ID shown there - this is the value AxiTrace sends as the
pidquery parameter on every event.
Generate a Conversions API key
- From the same Web data source, click Generate API key.
- Copy the key immediately - it is shown only once. It starts with
sk-; service-account keys look likesk-svcacct-…. If you lose it, generate a new one.
Connect in AxiTrace
- In your AxiTrace workspace, go to Connections and open Setup OpenAI Ads Connection.
- Paste the Pixel ID and the Conversions API key.
- Click Test Connection - AxiTrace sends a real test event to OpenAI Ads and shows the result immediately.
- Pick the events to forward (all are enabled by default) and set the status to Active, then save.
Event mapping
AxiTrace events map to OpenAI's Conversions API type values automatically:
| AxiTrace event | OpenAI Conversions API type |
|---|---|
page.view | page_viewed |
product.view | contents_viewed |
product.addToCart | items_added |
initiate_checkout | checkout_started |
transaction.charge | order_created |
lead (a form.submit that captured an email) | lead_created |
complete_registration (a form.submit recognised as an account sign-up form) | registration_completed |
subscribe | subscription_created |
start_trial | trial_started |
| any other marketing event | custom (original name preserved as custom_event_name) |
Form submissions are classified before they are forwarded: a login form, a search box or a checkout step
is never sent (the funnel already carries search, checkout_started and
order_created for those), an account sign-up form becomes registration_completed,
and every other form that captured an email becomes lead_created. See
how form submissions are classified.
With every event AxiTrace sends the available match keys: SHA-256 hashed email, phone, external ID, first and last name, plus the unhashed region/postal code/city/country, IP address, user agent, the page URL, and - for revenue events - currency, value, item count and the item list.
Click-ID attribution and the measurement pixel
AxiTrace captures the OpenAI Ads click identifier (oppref) from ad-click URLs, stores it in a
first-party, capped-age cookie, and attaches it to every server-side event AxiTrace sends for that
visitor - the same pattern used for Reddit's rdt_cid and Google's gclid.
If you also run OpenAI's own measurement pixel (oaiq) on your site, its first-party
__obref cookie is picked up read-only by the AxiTrace SDK and forwarded as
events[].user.obref alongside the click ID - OpenAI documents this as improving match quality.
AxiTrace never generates or synthesizes an obref value; it only relays what the pixel already
set.
custom_event_name for custom events), and event ID. AxiTrace always sends a
stable, deterministic event ID with every server-side call, so if you also fire the same event from the
browser pixel with a matching ID, OpenAI treats them as one conversion rather than counting it twice.
Match quality tips
-
Capture email wherever possible. Hashed email is the strongest match key AxiTrace can
send OpenAI Ads for visitors who never click through with a trackable
oppref- for example, a merchant collecting email at checkout or newsletter signup. -
Run the OpenAI measurement pixel alongside server-side tracking (see above) so
obrefis available as a second, independent match signal. - Keep the connection's event checkboxes broad - the more event types you forward, the more chances OpenAI has to match a conversion back to an ad click.
Campaigns and spend
Separately from the Conversions API above, AxiTrace can also import your OpenAI Ads campaigns, ad groups, ads and daily spend and attribute orders and leads to them - the same way it already does for Google Ads, Meta, Microsoft Ads and TikTok. This uses a different key: an Ads Manager API key (Ads Management API), not the Conversions API key above. The two keys are issued in different places in Ads Manager and are never interchangeable.
Create an Ads Manager API key
- Open OpenAI Ads Manager.
- Go to Settings > API keys.
- Create a key with access to the Ads Management API. Copy it - like the Conversions API key, it is shown
only once and starts with
sk-(service-account keys look likesk-svcacct-…).
Connect in AxiTrace
- In your AxiTrace workspace, go to Connections > Ad accounts > OpenAI Ads.
- Paste the Ads Manager API key and save. AxiTrace validates it against your OpenAI ad account and stores the account's id, name, currency and time zone.
Tracking template
OpenAI Ads needs a query string template on each campaign so AxiTrace can tell which campaign and ad a click
came from. Paste this into each campaign's tracking parameters in Ads Manager (without a leading
?):
utm_source=chatgpt&utm_medium=cpc&oai_campaign_id={campaign_id}&oai_ad_id={ad_id}
oppref to every ad click by itself - never add it to the template
yourself, it would be duplicated. And use utm_source=chatgpt exactly as shown, never
utm_source=chatgpt.com: the latter is what ChatGPT already sends on organic (non-ad) traffic, so
AxiTrace would read the click as organic, not as a paid ad click.
Tracking check
AxiTrace never changes anything in your OpenAI Ads account: it only reads campaigns, ad groups, ads and spend. You paste the template yourself, at campaign level, in Ads Manager. Once the account is connected, the OpenAI Ads card on the connection page reads every campaign's template and tells you whether the tracking parameters are there, how many campaigns lack them, and whether your paid visits can be tied to a campaign. A campaign you create later needs the template too: add it whenever you launch a new campaign, or whenever the card flags campaigns without tracking parameters.
The same check is available to an AI assistant connected to AxiTrace's MCP server
(get_integrations_health, get_tracking_setup_status) and to your own integration
through the public API (GET .../integrations/openai_ads/tracking). It is read only and needs the
integrations:read scope. See
Tracking check in the API reference.
What is imported
- Campaigns, ad groups and ads, with their names and statuses.
- Daily spend, impressions and clicks, per campaign, ad group and ad.
OpenAI's Ads API does not report conversions or attributed sales, so AxiTrace imports none from OpenAI: the orders and revenue you see next to an OpenAI campaign are AxiTrace's own attribution of your store's orders.
Orders and leads whose click carried the tracking template's oai_campaign_id/oai_ad_id
are attributed to that campaign and ad. A click that reaches your site with OpenAI's own
oppref but without the template still counts as an OpenAI Ads visit; it appears under
Untracked in your campaign reports because AxiTrace cannot tell which campaign it belongs to.
Cadence and backfill
- Campaign-level spend refreshes every hour.
- Ad group and ad-level spend refresh every 6 hours.
- Every refresh re-checks the last 7 days, to catch spend OpenAI finalizes a little after the fact.
- When you connect, AxiTrace automatically backfills the last 180 days of history. If you need more, ask for a manual backfill of up to 365 days.
Attribution windows
OpenAI reports no conversions through its API, so no OpenAI attribution window applies. Orders are attributed to OpenAI campaigns by AxiTrace, with the attribution model of your workspace, like every other ad platform.
Troubleshooting
| Error | What it means | What to do |
|---|---|---|
| 401 Invalid key | The key is wrong, was revoked, or was mistyped. | Generate a new Ads Manager API key in Ads Manager and paste it again on the connection page. |
| 403 No access | The key does not have access to this ad account, or lacks Ads Management API permission. | Create the key from the correct ad account in Ads Manager, with Ads Management API access. |