In OpenAI Ads conversion measurement, every event you send has to clarify two things: which standard event it is and which data shape (data type) it carries. The platform defines eleven standard events and four data shapes; correct measurement comes from binding each action to the right event and the right shape. This reference lists when each event fires and the fields of each shape.
The event name says what the action is, and the data shape says which fields that action carries. The two are linked: order_created always uses the contents shape, lead_created always uses the customer_action shape.
Standard Events
Eleven standard events bind to one of four data shapes. The table below gives each event’s name, the shape it uses, and when it fires1.
| Event | Data shape (type) | When |
|---|---|---|
page_viewed | contents | An important page is viewed |
contents_viewed | contents | A product, listing, content, or unit is viewed |
items_added | contents | An item is added to a cart, bundle, or selection |
checkout_started | contents | The checkout flow starts |
order_created | contents | A purchase is completed |
lead_created | customer_action | A lead form is submitted or contact is requested |
registration_completed | customer_action | An account or event registration completes |
appointment_scheduled | customer_action | A meeting, demo, or consultation is scheduled |
subscription_created | plan_enrollment | A paid subscription starts |
trial_started | plan_enrollment | A free trial starts |
custom | custom | A defined action not in the taxonomy |
Watch the distinction between checkout_started and order_created: one marks the start of the checkout flow, the other a completed purchase. Mixing them breaks the conversion count.
The Four Data Shapes
Each event’s data object carries the shape’s name in the type field and uses the fields specific to that shape. The table below gives the fields of the four shapes and their requirement state1.
Shape (type) | Fields | Notes |
|---|---|---|
contents | amount, currency, contents[] | Product and order events |
customer_action | amount, currency | Lead, registration, and appointment events |
plan_enrollment | plan_id, amount, currency, contents[] | Subscription and trial events |
custom | plan_id, amount, currency, contents[] | Actions outside the taxonomy |
In every shape the type field is required and carries the shape’s name. amount and plan_id are optional; currency is conditional, that is, it becomes required when amount is sent. customer_action is the narrowest shape: it carries no product list (contents[]) or plan_id, only an optional amount.
Items in the contents[] Array
Each item in the contents[] array describes a product or content unit. All fields are optional; send only what you have1.
| Field | Description |
|---|---|
id | Product or content identifier |
name | Product or content name |
content_type | Unit type (product, page, etc.) |
quantity | Quantity (integer) |
amount | Per-item amount (minor unit, integer) |
currency | Item currency |
Monetary Value and Currency
Monetary values follow the same rule everywhere: they are sent as integers in the ISO 4217 minor unit of the currency you provide. $129.99 becomes 12999; the cents are expressed with the minor unit, not with a decimal. The second rule completes it: if amount is sent, currency is required too1. So sending an amount requires sending the currency as well.
The details of minor unit and currency mistakes are the subject of a separate post; here it is enough to note that the rule is the same across every shape in the taxonomy.
Custom Events
If none of the ten standard events covers an action, custom is used and named with custom_event_name. The custom name is 1-64 characters long; it can contain lowercase letters, numbers, underscores, and dashes. A standard event name cannot be reused as a custom_event_name1. Because the custom shape can use the fields of the standard shapes (plan_id, amount, currency, contents[]), it lets actions outside the taxonomy be sent with structured data too.
Standard event first, custom second
If a standard event exists for an action, using it reports better than a custom event and fits naturally into the shape the platform expects. Reserve custom only for genuinely unique actions the taxonomy does not cover. Producing a custom event for every special need loses the consistency standard events provide.
Next Steps
Once the event and shape mapping is clear, the next step is how these events are sent via the pixel and the Conversions API, and the common mistakes in sending currency. When the taxonomy is set up correctly, both the browser and server sides speak the same language and conversions are counted consistently.
Footnotes
-
Supported events (OpenAI Developers) — the standard event taxonomy and each event’s data type (appointment_scheduled/lead_created/registration_completed = customer_action; checkout_started/contents_viewed/items_added/order_created/page_viewed = contents; subscription_created/trial_started = plan_enrollment; custom), the four data shapes and their fields (contents/customer_action/plan_enrollment/custom; the Content object id/name/content_type/quantity/amount/currency), the minor units rule (“Send monetary values as integers in the standard ISO 4217 minor unit for the currency code you provide.”), currency required when amount present (“If you include an
amount, also include acurrency.”), custom event naming (1-64 characters, lowercase/numbers/underscores/dashes, standard name cannot be reused). ↩ ↩2 ↩3 ↩4 ↩5
- 01 There are eleven standard events; each is bound to one of four data shapes: contents, customer_action, plan_enrollment, custom.
- 02 The contents shape is for product/order events (amount + currency + contents[]); customer_action is for lead/registration events (only amount + currency).
- 03 plan_enrollment is used for subscription and trial events and can carry plan_id; the custom shape is for actions outside the taxonomy.
- 04 Monetary value is an integer in ISO 4217 minor units: 2599 for $25.99. If amount is sent, currency is required.
- 05 A custom event name is 1-64 characters, lowercase, numbers, underscores, or dashes; a standard event name cannot be reused.
+ How many standard events does OpenAI Ads define?
There are eleven standard events: page_viewed, contents_viewed, items_added, checkout_started, order_created, lead_created, registration_completed, appointment_scheduled, subscription_created, trial_started, and custom. The first five use the contents shape, lead_created/registration_completed/appointment_scheduled use customer_action, subscription_created/trial_started use plan_enrollment; custom is for actions not in the taxonomy.
+ What are the data shapes (data type)?
There are four shapes: contents (amount, currency, contents[]), customer_action (amount, currency), plan_enrollment (plan_id, amount, currency, contents[]), and custom (plan_id, amount, currency, contents[]). Every shape's type field is required and carries the shape's name.
+ How is a monetary value sent?
Monetary values are sent as integers in the ISO 4217 minor unit of the currency you provide. For example, $129.99 is 12999. If the amount field is sent, the currency field becomes required as well.
+ What rules does a custom event name follow?
A custom event name is 1-64 characters long; it can contain lowercase letters, numbers, underscores, and dashes. A standard event name cannot be reused as a custom_event_name.