How to Configure the ChatGPT Ads Conversion API
The ChatGPT Ads Conversion API (CAPI) lets Cometly send your conversion events directly to OpenAI server-to-server, so ChatGPT Ads can report and optimize on your conversions even when browser-based tracking is blocked or incomplete. It sends the events you already track in Cometly to ChatGPT Ads, matched to the ad click that drove them.
For most spaces, setup is two clicks: pick a data-sharing mode and click Save. Cometly finds your pixel, creates the Conversions API key and maps your standard events. This article walks through what happens and the few cases that need a decision from you.
How it works
ChatGPT Ads adds a click reference called oppref to your landing page every time someone clicks one of your ads. When Cometly records a conversion, it looks for the ChatGPT ad click that drove it and sends the event to OpenAI with that click reference, along with hashed email, phone, and name so OpenAI can match it.
A visitor clicks your ChatGPT ad and converts on your site.
Cometly attributes the conversion to that ad.
Cometly sends the mapped event to OpenAI's Conversions API server-to-server, using the pixel of the ad account that ran the ad.
For an event to be sent, the Cometly event must be mapped to an OpenAI event type (see Step 4). Events you don't map are never sent.
Note: The Conversion API uses its own credentials: a pixel (a web data source) and a Conversions API key, both from the Conversions tab in ChatGPT Ads Manager. The key is different from the Ads API key you used to connect the ad account. Cometly reads your pixels and creates the key for you.
Before you start
An active ChatGPT Ads account connected in Cometly (Integrations → ChatGPT Ads). See ChatGPT Ads Integration.
A web data source (pixel) on each ad account, created in ChatGPT Ads Manager under the Conversions tab. If you don't see the Conversions tab, ask your OpenAI ads representative to enable conversion tracking for your account.
Cometly's URL parameters on your ChatGPT campaigns, so conversions can be attributed to the right ad:
comet_source=chatgpt&comet_campaign={campaign_id}&comet_ad_group={ad_group_id}&comet_ad_id={ad_id}
Step 1: Open the Conversion API settings
Go to Events Manager, open the Conversion API tab, and expand ChatGPT Ads.
Step 2: Choose a data-sharing mode
At the top you'll see the Master Data Sharing Settings. Pick one:
Turn off data sharing: no events are sent to ChatGPT Ads.
Send only attributed events (Recommended): send only events that Cometly can attribute to a ChatGPT ad click.
Send all events: send all events, including unattributed ones, which OpenAI matches on hashed email, phone, and name.
Step 3: Check the pixel and key for each ad account
Under Pixel and Conversions API key per ad account, every connected ChatGPT Ads account has its own row. Usually there is nothing to do here:
Pixel: Cometly lists the account's web data sources by name, with each Pixel ID underneath. If the account has one pixel, Cometly selects and stores it for you. If it has several, choose the one your site uses.
Conversions API key: created for you when you click Save. If you'd rather use a key you created in ChatGPT Ads Manager, paste it into the field instead.
Default account: the account that receives events Cometly can't attribute to a specific ChatGPT ad. With a single account, it is already selected. With several, select Use this account for unattributed events on one of them.
The line under each account name tells you where it stands: Pixel and key saved means the account is ready, Key created when you save means Save will finish it, and Click Save to store your changes means you've picked or pasted something that isn't stored yet. A stored key shows as dots in the key field; the key itself is never displayed.
💡 Tip: If the pixel field says the list isn't available for your account, choose Enter a Pixel ID manually and paste the Pixel ID from the Conversions tab of ChatGPT Ads Manager. If a key was revoked or rotated in Ads Manager, click Replace with a new key and Cometly creates and stores a new one, or paste a new key over the dots.
Step 4: Check the event map
Your standard Cometly events are already mapped to OpenAI's event types, and one map covers every ChatGPT Ads account in your space. Review it, add a row with Add mapping for anything missing, and remove rows you don't want sent.
OpenAI event type | Use it for |
Order created (purchase) | Purchases and orders. The order amount and currency are sent too. |
Lead created | Leads and form fills |
Registration completed | Sign-ups and account registrations |
Subscription created | New paid subscriptions |
Trial started | Free trial starts |
Checkout started | Initiated checkouts |
Items added (add to cart) | Add to cart |
Contents viewed | Product or content views |
Page viewed | Key page views |
Appointment scheduled | Booked calls and demos |
Custom event | Anything else. Enter a name in lowercase, using |
Step 5: Save
Click Save at the bottom of the ChatGPT Ads section. Cometly stores your pixels, creates a Conversions API key for every account that doesn't have one yet, saves the event map, and turns the Conversion API on with your data-sharing mode and default account.
Event mapping rules
One map covers the whole space. Every connected ChatGPT Ads account uses the same event map.
Multiple Cometly events can map to the same OpenAI event type.
Only mapped events are sent. If a Cometly event isn't mapped, it is never sent to ChatGPT Ads.
Pick a standard event where one fits. Send purchases as Order created and leads as Lead created, and use Custom event only for anything else.
Good to know
Once active, Cometly sends mapped conversions to ChatGPT Ads going forward. It does not backfill past events.
OpenAI only accepts events from the last 7 days. A conversion recorded later than that, such as a deal closed in your CRM weeks after the click, is not sent.
Each conversion is sent to the pixel of the ad account whose ad drove it. Events Cometly can't attribute go to your default account when you choose Send all events.
If you also run OpenAI's own pixel and it tracks the same event, don't map that event here too. OpenAI only removes duplicates that share an event ID, and the pixel's IDs won't match Cometly's, so the conversion would be counted twice.
Troubleshooting
No conversions showing up in ChatGPT Ads
Confirm your data-sharing mode isn't set to Turn off data sharing.
Confirm the Cometly event is mapped to an OpenAI event type (Step 4). Unmapped events are never sent.
Confirm the ad account shows Pixel and key saved (Step 3).
Confirm your campaigns carry Cometly's URL parameters so conversions can be attributed.
The pixel field says the list isn't available, or shows no pixels
OpenAI enables pixel management per ad account; until then Cometly can't list them. Choose Enter a Pixel ID manually and paste the Pixel ID from the Conversions tab of ChatGPT Ads Manager. If the account has no pixel yet, create one there first.
Saving says "OpenAI has not enabled Conversions API key creation for this ad account"
Everything else is saved. Create a key in the Conversions tab of ChatGPT Ads Manager, paste it into the key field and click Save again, or ask your OpenAI ads representative to enable key creation for the account.
An account shows "Choose a pixel" or "Not set up yet"
Pick the pixel (or enter its ID), then click Save. No events are sent for an account until both a pixel and a key are stored.
Events show "Authentication failed, check the Conversion API key"
OpenAI no longer accepts the stored key. Click Replace with a new key under the key field, or paste a new key over the dots, then click Save.
Some events show "no source url"
OpenAI requires the address of the page where the conversion happened. Events that arrive without one, such as some server-side or CRM events, use your space's first allowed domain instead, so make sure your domain is added in Cometly.
"No active ChatGPT Ads accounts in this space"
Connect a ChatGPT Ads account under Integrations → ChatGPT Ads first.
My custom event isn't showing in ChatGPT Ads
Create a conversion event in ChatGPT Ads Manager with exactly the same name you entered in Cometly.