Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt

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

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 URL)
- __oppref cookie (first-party, set by OpenAI's pixel if present)
Stores in visitor profile: anon_abc123
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 → Conversions
  2. Create or select your pixel — copy the pixel ID
  3. Generate an API key under the Conversions tab — copy it
  4. In DATALYR, go to Sources → Connect next to OpenAI Ads
  5. Paste the API key and pixel ID
  6. Click Connect — DATALYR fires a validate_only: true request 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.

​
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 typeData shapeNotes
order_createdcontentsMoney in cents, currency required
checkout_startedcontents
items_addedcontents
contents_viewedcontents
page_viewedcontents
lead_createdcustomer_action
registration_completedcustomer_action
appointment_scheduledcustomer_action
subscription_createdplan_enrollmentSet plan_id if available
trial_startedplan_enrollment
customcustomRequires 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.
  • 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.