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). |
| 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.
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 item 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