> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the ChatGPT Ads Conversion API

> Set up the ChatGPT Ads Conversion API in Cometly so OpenAI receives your leads and sales server-to-server, matched to the ad click that drove them.

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 (leads, sales and other conversions) to ChatGPT Ads, matched to the ad click that drove them.

This matters because ChatGPT Ads can only report and optimize on the conversions it knows about. With the Conversion API on, the leads and sales Cometly records, including ones a blocked or incomplete browser pixel would miss, show up against the ChatGPT ad that produced them, so you can judge each campaign on real results.

## 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.

1. A visitor clicks your ChatGPT ad and converts on your site.
2. Cometly attributes the conversion to that ad.
3. 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 [Check the event map](#set-up-the-chatgpt-ads-conversion-api)). 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** > **Ad Platforms** > **ChatGPT Ads**). See [ChatGPT Ads integration](https://docs.cometly.com/integrations/ad-platforms/chatgpt-ads.md).
* 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:

  ```text theme={null}
  comet_source=chatgpt&comet_campaign={campaign_id}&comet_ad_group={ad_group_id}&comet_ad_id={ad_id}
  ```

## Set up the ChatGPT Ads Conversion API

For most spaces (a space is your workspace in Cometly, with its own settings, integrations and data), 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. The steps below explain what happens and the few cases that need a decision from you.

**1. Open the Conversion API settings**

Go to **Events Manager**, open the **Conversion API** tab, and expand **ChatGPT Ads**.

**2. Choose a data-sharing mode**

Under **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.

To make one event behave differently from the master setting, use **Custom Rules for Specific Events** further down the section. Events without a custom rule follow the master setting.

**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**: the account is ready.
* **Key created when you save**: clicking **Save** finishes it.
* **Click Save to store your changes**: 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.

**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. Under **Map events to OpenAI conversion events**, review the map, 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 `_` or `-` between words, that isn't the name of a standard event above, and create a conversion event with the same name in ChatGPT Ads Manager. |

**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.

## Check it worked

After you click **Save**, the **ChatGPT Ads** row on the **Conversion API** tab shows an **Active** badge instead of **Inactive**, and each ad account under **Pixel and Conversions API key per ad account** reads **Pixel and key saved**. From then on, Cometly sends new mapped conversions to ChatGPT Ads.

## 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

> [accordion] 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. Unmapped events are never sent.
> * Confirm the ad account shows **Pixel and key saved**.
> * Confirm your campaigns carry Cometly's URL parameters so conversions can be attributed.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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**.

> [accordion] 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 (**Setup** > **Install the Cometly pixel** > **Add domains**).

> [accordion] No active ChatGPT Ads accounts in this space
>
> Connect a ChatGPT Ads account under **Integrations** > **Ad Platforms** > **ChatGPT Ads** first.

> [accordion] 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.

## Frequently asked questions

### Should I wait before turning on the ChatGPT Ads Conversion API?

Yes, if your event tracking is new. Cometly recommends waiting at least 7 days after you set up event tracking, so you can verify that your events are accurate before they are sent to an ad platform. The **Conversion API** tab shows a banner that tells you when your event data is ready.

### What data does Cometly send to ChatGPT Ads?

Cometly sends the mapped event and, for purchases, the order amount and currency. To help OpenAI match the conversion, it also sends the ChatGPT click reference when there is one, plus hashed email, phone and name, and the visitor's IP address, browser user agent, country and postal code when Cometly has them.

### Does Cometly create a ChatGPT Ads pixel for me?

No. Cometly reads the pixels (web data sources) that already exist on your ad account and creates the Conversions API key, but it never creates a pixel. A second pixel would split your conversions across two data sources, so create one in the **Conversions** tab of ChatGPT Ads Manager and select it in Cometly.

## Next steps

* [Connect or manage your ChatGPT Ads account](https://docs.cometly.com/integrations/ad-platforms/chatgpt-ads.md)
* [Exclude an event from the Conversion API after an opt-out](https://docs.cometly.com/guides/conversion-api/exclude-an-event.md)
* [Confirm Cometly received an event in the Events Log](https://docs.cometly.com/support/troubleshooting/general/event-log.md)
* [Learn how events work in Cometly](https://docs.cometly.com/guides/events/how-events-work.md)
* [Set up the Conversion API for another ad platform](https://docs.cometly.com/guides/conversion-api/overview.md)

Still have questions or need a hand? We're happy to help. Reach our team at [support@cometly.com](mailto:support@cometly.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.