OpenAI pixel

An OpenAI pixel measures what people do on your site after a ChatGPT ad, through the platform-neutral tracking tags API on your openaiads account.

Read the tag

Every OpenAI pixel has two ids, and per-pixel calls accept either as tagId:

• tag.id is the API resource id (cds_...), which conversion event settings name as their source.
• tag.siteTagId (also returned as pixelId) is the pixel_id the on-site code and the Conversions API send.

OpenAI documents no single-pixel read. GET .../tracking-tags/{tagId} resolves the pixel from the list, and adds the official oaiq base code plus the pixel's conversion event settings as events.

const { data } = await zernio.trackingtags.getTrackingTag({
  path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d', tagId: 'cds_68e4f0a1b2c3d4e5f6a7b8c9' }
});

Response (200):

{
  "platform": "openaiads",
  "tag": {
    "id": "cds_68e4f0a1b2c3d4e5f6a7b8c9",
    "pixelId": "4Kx9TqLm2VbN7wRz1PsYcD",
    "siteTagId": "4Kx9TqLm2VbN7wRz1PsYcD",
    "name": "Acme website",
    "platform": "openaiads",
    "kind": "pixel",
    "status": "active",
    "code": "<script>...oaiq('init', '4Kx9TqLm2VbN7wRz1PsYcD')...</script>",
    "events": [
      { "id": "ces_68e4f0c9d8e7", "name": "Purchases", "type": "order_created", "siteEvent": "purchase", "siteEventId": "order_created", "status": "active", "clickWindowDays": 30 }
    ]
  }
}

Create the pixel

POST /v1/accounts/{accountId}/tracking-tags creates an OpenAI pixel and provisions a Conversions API key for it, in one call.

adAccountId is required by the endpoint and ignored here, because the API key already selects the ad account.

Pass defaultEventType to provision the conversion event setting that goal: "conversions" needs. It takes one of the OpenAI standard events listed under Conversion events.

const { data: createdTag } = await zernio.trackingtags.createTrackingTag({
  path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d' },
  body: { adAccountId: 'acct_abc123', name: 'Acme website', defaultEventType: 'order_created' }
});

console.log(createdTag.tag.id);

Response (201):

{
  "platform": "openaiads",
  "tag": {
    "id": "cds_68e4f0a1b2c3d4e5f6a7b8c9",
    "pixelId": "4Kx9TqLm2VbN7wRz1PsYcD",
    "siteTagId": "4Kx9TqLm2VbN7wRz1PsYcD",
    "name": "Acme website",
    "platform": "openaiads",
    "kind": "pixel",
    "status": "active"
  }
}

If the pixel is created but the key provisioning fails, the pixel stays live on OpenAI and the error names it.

An account holds one Zernio-created pixel. More pixels are managed in OpenAI Ads Manager.

Check the pixel fires

GET .../tracking-tags/{tagId}/stats returns the latest events OpenAI received, at most 50 from the last 15 minutes. It is a live "is the pixel firing" check, not a history.

• Pixel and Conversions API events both appear there.
• startTime/endTime answer 400. Use the ads insights conversion metrics for totals.

Conversion events

A pixel's conversion event settings are its events. GET .../tracking-tags/{tagId}/events lists the ones sourced on the pixel, and POST creates one.

The body takes only name, type and siteEvent. The attribution window is OpenAI's fixed 30 days.

type is one of:

• an OpenAI standard event: order_created, lead_created, items_added, contents_viewed, checkout_started, registration_completed, subscription_created, trial_started, appointment_scheduled, page_viewed, app_installed, app_opened
• for anything else, the custom event name itself (1 to 64 letters, digits, underscores or dashes, stored lowercase)

siteEvent picks the name the Shopify pixel sends. So search and add_payment_info become the custom events search and addpaymentinfo.

const { data: created } = await zernio.trackingtags.createTrackingTagEvent({
  path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d', tagId: 'cds_68e4f0a1b2c3d4e5f6a7b8c9' },
  body: { name: 'Searches', siteEvent: 'search' }
});

Response (201):

{
  "platform": "openaiads",
  "event": { "id": "ces_68e4f0d1e2f3", "name": "Searches", "type": "custom", "siteEvent": "search", "siteEventId": "search", "status": "active", "clickWindowDays": 30 }
}

Creating an event setting is not idempotent.

What you cannot change

OpenAI's conversion-setup API documents only list and create. Event updates and deletes answer 501, and DELETE on a pixel answers 405. The OpenAI endpoints answer 404/405 when probed:

Install on a site

POST .../tracking-tags/{tagId}/install puts the pixel on a connected Shopify store or WordPress site.

WordPress gets the official oaiq base code with a page_viewed call.

Shopify sends each storefront event through OpenAI's documented image tag (GET https://bzr.openai.com/v1/sdk/events). Each carries the event id for deduplication, and amounts in the currency's minor unit.

The landing page's oppref click id is kept in the __oppref cookie for 30 days and sent with every event.

The image tag cannot carry the __obref browser id (OpenAI rejects the parameter). Search text is never sent.

If it fails

Related

• Send a conversion event: server-side events to this pixel.
• Pixels and tracking tags: the pixel API across platforms.
• Create tracking tag: pixels and Conversions API keys.
• Shopify tracking pixels: what the Shopify pixel sends.
• Create a campaign: optimize for an event.