OpenAI Conversions API Tag for Google Tag Manager (server-side)

The OpenAI Conversions API Tag allows advertisers to send web events from their tagging server directly to the OpenAI Ads Conversions API. It reads the standard GA4 event schema, converts it to the OpenAI event format, normalizes and hashes user identifiers, and forwards click and browser attribution data.

Background

OpenAI Ads offers two ways to measure conversions from ChatGPT campaigns: the OpenAI pixel in the browser and the Conversions API from your server. OpenAI states that the Conversions API is a more reliable source than the pixel alone and recommends using it whenever possible. This tag lets you do so from a GTM server container without writing code, and can run alongside the pixel with proper event deduplication.

Follow our complete guide on the OpenAI CAPI setup.

How does the Addingwell tag work?

This template is a tag that reads the standard GA4 event schema sent from the client running on a tagging server. It then:

• maps GA4 event names to OpenAI standard event types (see the mapping table) and sends anything else as a custom event named after the GA4 event;
• builds the data object with the shape OpenAI requires for each event type (contents, customer_action, plan_enrollment or custom), converting GA4 decimal values to integer minor units and mapping items to contents;
• normalizes and hashes emails, phone numbers, external IDs, first names and last names following OpenAI's rules, and forwards geographic fields raw;
• captures the oppref click reference from the landing URL, or reads the pixel __oppref cookie, and persists it server-side in the first-party FPOPPREF cookie for 365 days;
• reads the pixel __obref browser reference, or generates a UUID v4 in the pixel's format when none exists, and persists it server-side in the first-party FPOBREF cookie for 365 days so it outlives browser-side cookie limits;
• sends integration_source: addingwell_sgtm on every request and supports validate_only for testing.

The tag never writes the pixel's own __oppref and __obref cookies. The tag supports only the GA4 client.

Tag configuration

Field	Description
Event Name Setup Method	Inherit from client maps GA4 events automatically. Override lets you pick a standard OpenAI event or type a custom event name.
Conversions API Key	Bearer token provisioned in the Conversions tab of OpenAI Ads Manager.
Pixel ID	Sent as the pid query parameter. Use the same Pixel ID as your pixel so deduplication works.
Action Source	Where the conversion occurred. Defaults to web. Other values: mobile_app, offline, physical_store, phone_call, email, other.
Validate only	true makes OpenAI validate the event without recording it. Accepts a variable. Defaults to false.
Opt Out	true excludes the event from user-level personalization. Accepts a variable. Defaults to false.
Server Event Data Override	Force timestamp_ms, source_url or oppref.
User Data Override	Provide or replace identifiers: email, phone, external ID, first name, last name, city, region, postal code, country, obref, IP address, user agent, Android advertising ID. Plain values are normalized and hashed; SHA-256 values are forwarded as-is.
Event ID Deduplication	Force the event id. Defaults to the GA4 event_id, otherwise a generated value.
Custom Data Override	Force amount (integer minor units), currency, plan_id, contents, or add custom fields for custom events.
Items Data Override	Change which GA4 items fields feed contents (id, group_id, name, content_type, quantity, amount).

GA4 to OpenAI event mapping

GA4 event	OpenAI event	data.type
page_view, gtm.dom	page_viewed	contents
view_item	contents_viewed	contents
add_to_cart	items_added	contents
begin_checkout	checkout_started	contents
purchase	order_created	contents
generate_lead	lead_created	customer_action
sign_up	registration_completed	customer_action
schedule	appointment_scheduled	customer_action
subscribe	subscription_created	plan_enrollment
start_trial	trial_started	plan_enrollment

Any other GA4 event is sent as type: custom with custom_event_name set to the GA4 event name, where characters outside A-Z, a-z, 0-9, _ and - are replaced by _.

Limitations

• Minor units: amount is computed as value × 100. For zero-decimal currencies (JPY, KRW, VND, ...) or three-decimal currencies (KWD, BHD, OMR, ...), override amount in the Custom Data Override table.
• Currency: no default is applied. If an amount is sent without a currency (from GA4 currency, items[].currency, or the Custom Data Override table), OpenAI rejects the event and the tag reports a failure in preview.
• Event ID: when the client does not send event_id, the tag generates one that cannot match the pixel. To deduplicate with the OpenAI pixel, send the same event_id from the browser.
• Consent: the tag does not gate identifiers or cookies on consent. Configure your triggers so the tag only fires when measurement consent is granted.
• Deduplication with the pixel requires the same Pixel ID, event name and event ID on both sides. For custom events, custom_event_name must match as well.
• App lifecycle events (app_installed, app_opened) are accepted through the Override method; set Action Source to mobile_app for them.

Implementation

You can follow our step-by-step instructions.

How to check received data

Set Validate only to true to have OpenAI validate your events without recording them, and inspect the outgoing request and the API response in the GTM server preview. Follow our guide on testing events sent to OpenAI.

Reporting Bugs/Feedback

Please raise any issues on GitHub or contact us directly at support@addingwell.com.

Open Source

The OpenAI Conversions API Tag for GTM Server-Side is developed and maintained by Addingwell under the Apache 2.0 license.