OpenAI Ads

Send conversions to OpenAI’s Conversions API so their algorithm can optimize your campaigns

The OpenAI Ads integration sends conversion events to OpenAI’s Conversions API (CAPI) so their optimization algorithm gets the signal it needs — even for purchases that happen days after the click, on a different device, or through a server-side checkout.

What Gets Sent

Conversion Data (To OpenAI):

• Purchases with revenue
• Subscription starts and trial starts
• Lead form submissions, signups, demo bookings
• Add to cart, checkout started, page viewed
• Any custom event you configure

We do not currently sync OpenAI ad spend or campaign data into the DATALYR dashboard — view your OpenAI campaign performance in OpenAI Ads Manager directly.

How It Works

Conversion Flow

1. User Clicks OpenAI Ad

User clicks OpenAI ad
OpenAI appends oppref to URL
URL: https://yoursite.com/?oppref=op_xyz...

2. DATALYR Captures Click ID

DATALYR tracking script captures:
- oppref: op_xyz... (from the URL on landing)
Persists in visitor's session attribution + first-touch profile.
Subsequent events from this visitor carry oppref automatically
for the next 90 days.

3. User Browses and Converts

User views products, adds to cart
User completes purchase: $99.99

4. Conversion Sent to OpenAI CAPI

DATALYR sends server-side conversion:
- type: order_created
- amount: 9999 (cents)
- currency: USD
- oppref: op_xyz... (from Day 1)
- event id matches client pixel event_id for dedup

5. OpenAI Attributes Conversion

OpenAI matches oppref to the original ad click,
attributes the $99.99 to your campaign,
and feeds the signal back into bid optimization.

Result: Purchase correctly attributed even days later, cross-device, or from a server-side webhook.

Setup

1. Connect OpenAI Ads Account

1. Open OpenAI Ads Manager → Settings → Conversions
2. Click + Create to add a Data Source (this is what DATALYR calls the Pixel ID). Copy the Data Source ID — it looks like NKWGVw...
3. Click Manage conversion keys → + Create new key. The generated value is what DATALYR calls the API Key. Copy it.
4. In DATALYR, go to Sources → Connect next to OpenAI Ads
5. Paste the Conversion Key into the API Key field and the Data Source ID into the Pixel ID field
6. Click Connect — DATALYR fires a validate_only: true request to OpenAI to verify the credentials before saving. If anything’s wrong, the modal surfaces the error inline.

Unlike Meta or TikTok, there’s no OAuth redirect — OpenAI uses static API keys.

Don’t install OpenAI’s browser pixel script separately. OpenAI Ads Manager will offer you a <script> snippet that loads oaiq.min.js and fires events directly from the browser. With DATALYR’s Conversions API integration you don’t need it — DATALYR captures the oppref click ID and fires every conversion server-side, including events from Stripe, Shopify, and other backend webhooks. Installing both would create duplicate events unless you carefully match event_id on every call.

2. Configure Conversion Events

1. Go to Settings → Conversion Rules
2. Map your DATALYR events to OpenAI event types:
   • purchase / order_completed → order_created
   • add_to_cart → items_added
   • checkout_started → checkout_started
   • lead → lead_created
   • complete_registration → registration_completed
   • subscribe → subscription_created
   • start_trial → trial_started
   • Anything else → custom (set the custom_event_name in rule config)
3. Set the value path (e.g. properties.value) for events with revenue.

3. Test Your Setup

Toggle Test mode on a conversion rule. While enabled, every event we send to OpenAI includes validate_only: true — OpenAI validates the payload but does not record it for attribution. Use this to confirm the wire format without polluting your campaign signal. Disable test mode once you’re confident.

Supported Event Types

OpenAI type	Data shape	Notes
order_created	contents	Money in cents, currency required
checkout_started	contents
items_added	contents
contents_viewed	contents
page_viewed	contents
lead_created	customer_action
registration_completed	customer_action
appointment_scheduled	customer_action
subscription_created	plan_enrollment	Set plan_id if available
trial_started	plan_enrollment
custom	custom	Requires custom_event_name

Deduplication With OpenAI’s Browser Pixel

If you also install OpenAI’s oaiq.min.js browser pixel directly, OpenAI deduplicates browser-pixel events with our server-side CAPI events using the tuple (pixel_id, event_name, event_id). DATALYR sends the DATALYR event ID as the OpenAI event id. As long as your client-side pixel calls use the same event_id, you won’t double-count.

If you only use DATALYR (no OpenAI pixel on the page), there’s nothing to dedupe — every event is server-side.

Privacy & Consent

• oppref is OpenAI’s privacy-preserving click identifier — it’s opaque, not cross-advertiser linkable, and rotates on OpenAI’s side. It’s the only attribution signal we send by default.
• No PII is sent by default. OpenAI’s Conversions API documents user{} as “optional user fields” with no schema or hashing rules, and their example payload doesn’t include user data. We mirror that design — oppref carries the connection.
• For users who opt out (via your consent banner), we send opt_out: true so OpenAI excludes the event from personalization while still counting it for aggregate measurement.

Optional: send hashed user data

If OpenAI publishes a user{} schema or you want to test with hashed PII as a match-rate fallback for cross-device conversions:

• Set send_user_data: true in the conversion rule’s config object, OR
• Set the Cloudflare worker secret OPENAI_SEND_USER_DATA=1 (fleet-wide)

When enabled, we send SHA-256-hashed email, phone, first_name, last_name, city, state, postal_code, country, external_id plus raw ip and user_agent. Field names and hashing format are guesses based on industry convention until OpenAI documents the schema — verify with the canary script before flipping on for real customer traffic.

Troubleshooting

The connection fails to save with “Invalid API key” Re-generate the key in OpenAI Ads Manager → Conversions and paste the fresh value. Old keys revoke immediately on regeneration.

Conversions don’t appear in OpenAI’s events feed Disable Test mode on your conversion rule — validate_only: true validates the payload but doesn’t record events for attribution. Then trigger a fresh conversion.

Events get rejected with a timestamp error OpenAI rejects events older than 7 days or more than 10 minutes in the future. Server-side webhooks that arrive late (e.g. delayed Stripe/Shopify webhooks) will be silently dropped — that’s expected and won’t appear as a failure in your postback log.

Numbers don’t match OpenAI’s dashboard exactly OpenAI’s reporting has its own attribution windows and modeling. Conversions sent via CAPI will appear, but the exact attribution credit depends on OpenAI’s last-click vs. modeled attribution settings.

Next Steps

Meta Ads

Send conversions to Facebook

Google Ads

Track Google Ads performance

TikTok Ads

Track TikTok ad performance

Conversion Rules

Configure conversion mapping

Customer Journeys

View attribution paths

Need Help?

Questions about OpenAI Ads integration? Check our troubleshooting guide or contact support.