How to Use This Encyclopedia

Three reading paths, depending on where you are.

Path 1 — You’ve never run ChatGPT Ads (read end-to-end)

Read chapters 1–6 first. They explain what the product is from the user’s side: where ads appear, who sees them, how OpenAI matches an ad to a conversation, what data flows where. Without that mental model, the API and measurement chapters read as plumbing without purpose.

Then read chapters 7–12. The Ads Manager, the pixel, the Conversions API, the event taxonomy, the data shapes, and dedup. By the end of Section 2 you know what gets measured and how.

Finally read chapters 13–19. The Advertiser API. Skim Section 3 the first time — return to specific chapters when you actually build the integration.

Path 2 — You’re integrating right now (jump to the spec)

If you are wiring up a Shopify store with a pixel and CAPI:

Chapter 8 — pixel install snippet, exact <head> placement, automatic oppref capture.
Chapter 10 — pick the events you need. For Shopify the minimum stack is page_viewed, contents_viewed, items_added, checkout_started, order_created.
Chapter 11 — the data shapes. Get amount denomination right (integers in lowest currency unit). Get event_id right.
Chapter 9 — the server-side endpoint, batch limits, and the per-request structure.
Chapter 12 — match event_id between pixel and CAPI.

If you are building campaign management on top of the Advertiser API:

Chapter 13 — base URL, auth, rate limits, the lifecycle states.
Chapter 14 — confirm your key works against GET /ad_account.
Chapter 15–17 — create a campaign, create an ad group, create an ad. Chapter 18 if you upload assets programmatically.
Chapter 19 — pull insights once delivery starts.

Path 3 — You’re debugging or auditing (use the index)

Each chapter is self-contained and source-cited. Open the chapter, find the field or endpoint you’re looking at, cross-check against the source URL in the frontmatter. If the live OpenAI doc has changed since last_verified, the OpenAI doc wins — this encyclopedia is a snapshot, not a fork.

A note on numbers

All monetary fields in the API and pixel use integers in the lowest currency denomination. 12999 means $129.99 in a USD account. The Advertiser API additionally uses micros (millionths of the main currency unit) for bid and budget fields — 60000 micros = $0.06 = $60 CPM. The two conventions look similar and are not the same. Chapter 11 covers the event-side convention; Chapter 16 covers micros.