Documentation Index

Fetch the complete documentation index at: https://help.branch.io/llms.txt

Use this file to discover all available pages before exploring further.

Enable OpenAI Ads (New)

New
  • Updated on Jul 30, 2026
  • Published on Jul 28, 2026
Prev Next

Overview

OpenAI Ads lets advertisers reach people in ChatGPT as they research products, compare options, and make decisions. Connect OpenAI Ads to Branch to measure campaign-driven activity and forward eligible conversion events to OpenAI’s Conversions API for reporting and optimization in OpenAI Ads Manager.

As a cross-platform measurement provider, Branch can attribute and ingest conversions across app, mobile web, desktop, offline, and other customer touchpoints, including server events sent through the Branch Events API. When the OpenAI Ads integration is enabled, Branch forwards eligible conversion signals and associated OpenAI click data back to OpenAI, allowing advertisers to evaluate campaign performance across both Branch and OpenAI Ads Manager.

For more information about integrating ad partners in general, visit our Ad Partner Integration Guide.

Note: Branch attribution and OpenAI conversion forwarding

Use a Branch Ad Link as the destination URL in your OpenAI ad campaigns. Branch records the resulting click and attributes downstream conversions according to your Branch attribution settings. Branch also captures the OpenAI click identifier, oppref, from the Branch Ad Link and forwards it with eligible conversion events to support OpenAI’s conversion matching, reporting, and optimization.

Partner capabilities

Capability

Details

Supported event sources

Branch Mobile/Web SDK, Server-to-server (S2S)

Platforms

Web, iOS, Android, Desktop

Click reference sharing

Supported via OpenAI's oppref click reference

Advanced matching

Supported

Attribution support

Deterministic & Probabilistic Click-through

Cost data

In progress; please reach out to your Branch representative for more information

Before you begin

To set up the OpenAI Ads integration, you need:

  • Branch's Performance Product enabled for your Branch account. Contact your Branch account manager or visit https://branch.io/pricing.

  • The Branch Mobile SDK (iOS | Android) implemented in your app, and/or the Branch Web SDK implemented on your website, with event tracking configured — or conversion events sent via server-to-server (S2S) ingestion.

  • An active OpenAI Ads Manager account with a campaign running in ChatGPT.

  • A Branch Ad Link placed as the destination URL in your OpenAI ad campaigns, so Branch can attribute the resulting conversions.

Enable OpenAI Ads

To begin, navigate to Configuration > Ad Partners > Integrations > OpenAI Ads in Branch.

OpenAI Ads requires a Pixel ID and Conversions API Key from your OpenAI Ads Manager account. Follow the steps below to retrieve these credentials and enable Conversions API forwarding in Branch.

Step 1: Retrieve your Pixel ID

  1. Sign in to OpenAI Ads Manager.

  2. Navigate to the Conversions tab.

  3. Select an existing data source, or create one, and copy its Pixel ID.

Step 2: Generate a Conversions API key

  1. In the Conversions tab, select the Conversion Keys dropdown (or Generate API Key if a key already exists for the account).

  2. Copy the generated key immediately. OpenAI shows the key only once. Store it in a secure location if you cannot enter it into Branch right away.

Step 3: Enter credentials in Branch

  1. Enable the OpenAI Ads partner under Configuration > Ad Partners > Integrations > OpenAI Ads in Branch.

  2. Select the Postbacks tile, then enter the Pixel ID and Conversions API Key from Steps 1 and 2.

  3. Select Next and Save & Go to Postback config to continue setting up your Events.

Configure postbacks

Conversion events are forwarded to OpenAI's Conversions API based on your postback configuration. Branch maps these to OpenAI's supported event types as follows:

OpenAI event type

Branch Event

app_installed

INSTALL

app_opened

OPEN

order_created

PURCHASE

items_added

ADD_TO_CART

contents_viewed

VIEW_ITEM

checkout_started

INITIATE_PURCHASE

registration_completed

COMPLETE_REGISTRATION

subscription_created

SUBSCRIBE

trial_started

START_TRIAL

lead_created

RESERVE

page_viewed

PAGEVIEW, WEB_SESSION_START

custom

Any other Branch Event, forwarded with a sanitized {custom_event_name}

Enable Send all events on the Postback config tab to forward all conversion events Branch receives, not just events attributed to OpenAI campaigns. This gives OpenAI the broadest possible signal for measurement and optimization.

To add postbacks for additional events or to customize behavior, follow the steps in the Configure postbacks section of the general Ad Partner Integration Guide.

Create Conversion Events in OpenAI Ads Manager

Entering credentials in Branch only opens the channel; OpenAI will not report, optimize against, or show identifier coverage for events until you also define matching Conversion Events in the Ads Manager and link them to your campaign.

  1. In OpenAI Ads Manager, navigate to Conversions > Conversion Events and select Create conversion events.

  2. For each Branch Event you plan to send, choose the matching Base Event from the dropdown (for example, Order created, App opened, Registration completed).

  3. Select the Branch data source you created when retrieving your Pixel ID in Step 1.

  4. Set the Click-through attribution window for the event and select Create. Ensure the window selected matches your Branch attribution window.

    1. Click to Session Start = app_opened

    2. Click to Install = app_installed

    3. Click to Conversion Event = Downstream events (order_created, registration_completed , etc)

  5. Repeat for each event type, then link the conversion events to your campaign so OpenAI can optimize delivery and report results against them.

Note

Branch will forward events to OpenAI as soon as credentials are saved and postbacks are configured, regardless of whether matching Conversion Events exist on the OpenAI side. Skipping this step is the most common reason advertisers see events flowing in Branch Liveview but no reporting activity in OpenAI Ads Manager.

A Branch Ad Link is required to record the OpenAI ad click, attribute conversion events, and capture the oppref used when forwarding events to the Conversions API.

Follow the Create a Branch Ad Link documentation to build your Destination URL.

Once created, split the link across two fields in your Ad Group or Ad Sets:

  • Ad Destination URL: the base link only, e.g. https://yourapp.app.link/1GGERvH4a5b?%243p=a_openai

  • Landing page query parameters: the macro portion Branch appends, e.g. ~ad_id={ad_id}&~ad_set_id={ad_group_id}&~campaign_id={campaign_id}

At serving time, the URL will look like:

https://yourapp.app.link/1GGERvH4a5b?%243p=a_openai&~ad_id=<actual_ad_id>&~ad_set_id=<actual_ad_group_id>&~campaign_id=<actual_campaign_id>

OpenAI only fills in macros placed in the Landing page query parameters field — macros left in the Destination URL won't populate.

Attribution and click matching

When a user clicks your OpenAI ad and lands on your Branch Ad Link, Branch attributes the resulting install, session, or conversion using its own Persona graph. This is the same click-through attribution Branch uses across other partners. This is Branch's primary attribution mechanism for OpenAI Ads and does not depend on OpenAI's own click reference.

Independently, OpenAI appends its own privacy-preserving click reference, calledoppref, to the destination URL whenever a user clicks an ad in ChatGPT (e.g., https://yourapp.app.link/?oppref=gAAAAAb123). Branch automatically retrieves oppref from Branch Ad Links and then includes it on every Conversions API event for that user, so OpenAI can also connect the conversion back to the originating ad click within its own systems and reporting.

If oppref is not present on an event (for example, because the campaign's destination URL was not a Branch Ad Link), Branch omits the field rather than sending an empty value.

Verify your data

After saving your credentials and configuring postbacks, verify that events are flowing correctly:

  • In Branch Liveview: confirm that conversion events appear in real time. Filter for ad partner (3p) = a_openai to isolate events being forwarded to OpenAI.

  • In OpenAI Ads Manager: navigate to Conversions > Conversion Events and confirm Used by and Identifier coverage are populated for each event, or check the Event Stream tab for raw incoming events from your Branch data source.

  • In Branch Analysis dashboards: review attributed installs and events where Ad Partner Name = OpenAI Ads, confirming Branch's own attribution is crediting clicks from your Branch Ad Link.

  • In OpenAI Ads Manager campaign reporting: confirm the Conversions metric reflects forwarded events within the configured attribution window.

Conversions API data mappings

Branch maps the following fields from your events to the OpenAI Conversions API payload:

CAPI Field

Notes

id

Branch's own event identifier. Used with type to deduplicate events on OpenAI's side.

type

A supported OpenAI standard event name, or custom. See the event mapping table above.

custom_event_name

Present only when type is custom. Lowercased and truncated to fit OpenAI's naming requirements.

timestamp_ms

Event time in milliseconds.

oppref

Omitted if OpenAI's click reference was not captured for the event.

source_url

Included only when the event originates from a web platform.

action_source

web for web platforms, mobile_app for iOS/Android app platforms, other otherwise.

user.ip_address

Captured from the originating request.

user.user_agent

Captured from the originating request.

user.country

Derived from IP address server-side.

user.city

Derived from IP address server-side.

user.zip_code

Derived from IP address server-side.

user.email_sha256

When present on the event, advertiser must send this value already SHA-256 hashed

user.external_id_sha256

When present on the event, advertiser must send this value already SHA-256 hashed. If user_data.developer_identity isn't currently SHA-256 hashed, reach out to your Branch representative

data.amount

Revenue, converted to minor units (*100) as required by OpenAI.

data.currency

Included when revenue is present on the event.

data.plan_id

Included on subscription_created and trial_started events only.

data.contents[].id

Branch SKU data.

data.contents[].name

Branch Product Name.

data.contents[].quantity

Rounded to the nearest integer, as required by OpenAI.

data.contents[].amount

Price, converted to minor units (*100).

data.contents[].currency

Falls back to the event-level currency if not set on the item.

These field mappings can be customized to send additional advertiser-specific values. Reach out to your Branch representative to configure custom mappings

Troubleshoot

Follow the steps below to troubleshoot common issues with the OpenAI Ads integration.

Events not appearing in OpenAI Ads Manager

If forwarded events are not appearing in OpenAI Ads Manager:

  • Confirm that your Pixel ID and Conversions API Key are entered correctly in Branch. An invalid key causes OpenAI to reject all events from that source.

  • Confirm that events are being tracked through the Branch SDK or S2S and are appearing in Branch Liveview. Branch can only forward events it has received.

  • Confirm that Send all events is enabled on the Postback config tab, or that the specific events you expect are included in your active postbacks.

  • Confirm that a matching Conversion Event exists in OpenAI Ads Manager under Conversions > Conversion Events, with the Branch data source selected and linked to your campaign. See Create conversion events in OpenAI Ads Manager above — events can be received successfully by OpenAI and still not appear in reporting if no Conversion Event is configured for that type.

Branch attribution not crediting OpenAI clicks

  1. Confirm that a Branch Ad Link (not a plain destination URL) is configured for your OpenAI ad campaigns. Without a Branch Ad Link, Branch has no click to attribute against. Visit Create a Branch Ad Link for more information.

  2. Confirm that the Branch Ad Link is placed correctly in the ad's destination URL field in OpenAI Ads Manager, and that it has not been altered or wrapped by another redirect before OpenAI serves it.

Duplicate conversions in OpenAI reporting

If you’re using OpenAI Pixel alongside Branch's Conversions API forwarding and you see higher-than-expected conversion counts, deduplication may not be working.

Confirm that:

  1. The identifier used as id in Branch's Conversions API events matches the event_id passed in your OpenAI Pixel call for the same conversion.

  2. Both the Pixel event and the API event use the same event type. OpenAI requires both to match for deduplication.