The OpenAI Ads Conversions API Tag for Google Tag Manager Server-Side allows you to send conversion event data from your server container directly to the OpenAI Ads Conversions API. This server-to-server integration provides a more reliable and privacy-compliant way to track conversions for OpenAI (ChatGPT) ad campaigns compared to pixel-only setups.
Features
- Server-to-Server Events: Sends conversion data directly from the GTM Server Container to the OpenAI Ads Conversions API.
- Flexible Event Mapping: Supports standard OpenAI event types, inherits and maps from GA4 event names automatically, or sends fully custom event names.
- Automatic Data Mapping: Intelligently maps parameters from incoming GTM event data for server event data, user identifiers, and event parameters.
- Click ID Cookie Management: Automatically reads and sets the
__oppref(Click ID) cookie server-side to improve attribution. - PII Hashing: Automatically hashes email addresses and User IDs using SHA-256 before sending. Pre-hashed values are accepted and will not be re-hashed.
- Consent Mode Support: Integrates with Google Consent Mode, checking for
ad_storageconsent before sending data.
Installation
- Import the template from the GTM Template Gallery:
- Add the OpenAI Ads Conversions API by Stape tag to your GTM container from the GTM Template Gallery.
- Import to GTM Server Container:
- In your GTM Server Container, navigate to the Templates section.
- Click New under the Tag Templates section.
- Click the three-dot menu in the top right and select Import.
- Select the downloaded
template.tplfile and click Save.
- Create a New Tag:
- Go to Tags and click New.
- Select the newly imported “OpenAI Ads Conversions API by Stape” template.
Tag Configuration
Base Configuration
| Parameter | Description |
|---|---|
| Event Name Setup Method | Choose Standard to select a predefined event type, Inherit from client to automatically map from GA4 event names, or Custom to enter a custom event name. Regardless of the method chosen, the resulting event name is always checked against the Standard Event Types list below: if it matches, the event is sent as that Standard Event; if it doesn’t, the event is sent as a Custom Event (custom_event_name set to that value). |
| Pixel ID | Your OpenAI Pixel ID from your ad account. |
| API Key | Your OpenAI API Key, provided by the OpenAI Account team. |
| Action Source | Where the event occurred: Web, Mobile App, Offline, Physical Store, Phone Call, or Email. |
| Validate Only | If true, the event is sent in test mode and excluded from measurement. |
| Use Optimistic Scenario | If enabled, the tag fires gtmOnSuccess() immediately without waiting for the API response, speeding up server response time. |
Standard Event Types
| Event Name |
|---|
page_viewed |
app_installed |
app_opened |
appointment_scheduled |
checkout_started |
contents_viewed |
items_added |
lead_created |
order_created |
registration_completed |
subscription_created |
trial_started |
This list applies no matter which Event Name Setup Method is used: whenever the resolved event name (from Standard, Inherit from client, or Custom) matches one of the names above, the event is sent as that Standard Event; otherwise, it is sent as a Custom Event with custom_event_name set to the resolved name.
GA4 → Conversions API Event Name Mapping (Inherit from client)
When using Inherit from client, the following GA4 event names are mapped:
| GA4 Event Name | OpenAI Conversions API Event Type |
|---|---|
page_view |
page_viewed |
view_item |
contents_viewed |
add_to_cart |
items_added |
begin_checkout |
checkout_started |
purchase |
order_created |
generate_lead |
lead_created |
sign_up |
registration_completed |
| Any other GA4 event that matches a Standard Event Type | that Standard Event Type |
| Any other GA4 event | custom (with custom_event_name set) |
Custom Event Name Requirements
- Maximum 64 characters
- Accepted characters: lowercase alphanumeric,
_, and- - If the entered name matches a Standard Event Type, it is sent as that Standard Event instead of a Custom Event
Click ID Cookie Settings
Controls how the tag handles the OpenAI Click ID (oppref).
| Parameter | Description |
|---|---|
| Set Click ID cookie | If true, the Click ID is sent in the request and stored as the __oppref cookie by server GTM. If false, the Click ID is still sent if found but not stored as a cookie. |
| Cookie Domain | Override the cookie domain. Defaults to auto, which resolves via page_location, Referer, or Host headers. |
| Cookie SameSite | None, Lax (default), or Strict. |
| Cookie HTTP Only | Whether to set the HttpOnly flag on the cookie. Defaults to false. |
| Cookie Expiration | Number of days until the cookie expires. Defaults to 30. |
The Click ID (oppref) is sourced in the following priority order:
- User Identifiers Parameters section (manual override)
opprefURL parameter__opprefcookiecommon_cookie.__opprefEvent Data parameter__opprefEvent Data parameteropprefEvent Data parameter
Server Event Data Parameters
| Parameter | Description |
|---|---|
| Opt Out | When true, the event is marked as opted out. |
| Automap Server Event Data Parameters | If enabled, automatically sets Event Timestamp (Unix timestamp in ms), Source URL (from eventData.page_location), Event ID (from eventData.event_id or eventData.eventId), and Click ID (from oppref sources). |
| Autogenerate an Event ID if none is found | Enabled by default. Unlike Meta/TikTok, OpenAI’s Conversions API requires an Event ID on every request; if none is found in Event Data, the tag generates a random one so CAPI-only events aren’t rejected. Applies independently of Automap Server Event Data Parameters and never overrides a real Event ID. If you’re also sending events via Pixel, either disable this option, or leave it enabled and pass your own Event ID manually or via Event Data to keep Pixel/CAPI deduplication working. |
| Server Event Data Parameters | Manually override or add Event Timestamp, Event ID, Click ID, and Source URL. Manual values always take precedence over auto-mapped ones. |
Note:
Timestampcannot be more than 7 days in the past or 10 minutes into the future.Source URLis required when Action Source is set toWeb.Event IDis always required — the request fails validation if none is available and Autogenerate an Event ID if none is found is disabled.
User Data Parameters
| Parameter | Description |
|---|---|
| Automap User Data Parameters | If enabled, automatically maps Email, Phone Number, City, ZIP Code, Region, Country, First Name, Last Name, External ID, IP Address, User Agent, and Android Advertising ID from the Event Data. |
| User Identifiers Parameters | Manually specify user identifiers. Supported fields: Email Addresses, Phone Numbers, External ID, External IDs SHA256 Hashed, First Names, Last Names, Cities, ZIP Codes, Regions/States, Countries, IP Address, User Agent, Android Advertising ID (GAID). |
Email, Phone Number, External ID, First Name, Last Name, City, ZIP Code, Region, and
Country all accept more than one value: auto-mapping preserves every value found when
the underlying Event Data field is an array (for example, more than one user_data.address
record), and a manual entry can be bound to a variable that returns an array instead of a
single string. IP Address, User Agent, Browser ID, and Android Advertising ID
only ever accept a single value.
Auto-mapping sources:
| Field | Event Data Sources |
|---|---|
email, email_address, user_data.email, user_data.email_address, user_data.sha256_email_address |
|
| Phone Number | phone_number, user_data.phone_number |
| External ID | user_id |
| First Name | user_data.address.first_name |
| Last Name | user_data.address.last_name |
| City | user_data.address.city |
| ZIP Code | user_data.address.postal_code |
| Region | user_data.address.region |
| Country | user_data.address.country |
| IP Address | ip_override |
| User Agent | user_agent |
| Android Advertising ID | x-ga-resettable_device_id (only when x-ga-platform is android; an all-zero GUID is ignored) |
The tag automatically hashes the following fields using SHA-256 before sending: Email,
Phone Number, External ID, First Name, Last Name. Pre-hashed values (64-character hex
strings) are detected and will not be re-hashed. City, ZIP Code, Region, and Country are
sent as plain values, not hashed.
Event Parameters
| Parameter | Description |
|---|---|
| Automap Event Parameters | If enabled, automatically maps Amount (from eventData.value or sum of items price × quantity), Currency (from eventData.currency or items), and Contents (from eventData.items, including item_group_id as group_id). |
| Custom Item ID Key | Optional. Override the item ID field key used when mapping items. Defaults to item_id. Useful for WooCommerce setups. |
| Event Parameters | Manually specify Amount, Currency, Contents, and Plan ID. |
Note:
Currencyis required whenAmountis used. Each content inContentsmust havecontent_typedefined.
Useful Resources
- Advertising in ChatGPT: how to track ChatGPT Ads’ performance
- OpenAI Docs: OpenAI Ads Conversions API
- OpenAI Docs: Supported Events
Open Source
The OpenAI Ads Conversions API Tag for GTM Server-Side is developed and maintained by the Stape Team under the Apache 2.0 license.
Not listed