Chapter 11 — Event Data Shapes

Every event payload’s data object must include a type field that matches the event. There are four data shapes.

Universal rules

• Monetary values: integers in the currency’s lowest denomination. 12999 = $129.99 when currency: "USD".
• If amount is present, currency is required.
• Quantities: integers, never strings.

These rules apply to every shape below.

contents

Used by all commerce-flow events: page_viewed, contents_viewed, items_added, checkout_started, order_created.

Field	Required	Type	Notes
type	Yes	string	Must be contents.
amount	No	integer	Event-level monetary value, lowest denomination.
currency	Conditional	string	Required when amount is present.
contents	No	array of Content	Items associated with the event.

customer_action

Used by lead-style events: lead_created, registration_completed, appointment_scheduled.

Field	Required	Type	Notes
type	Yes	string	Must be customer_action.
amount	No	integer	Event-level monetary value, lowest denomination.
currency	Conditional	string	Required when amount is present.

No contents array — customer_action events are about a user act, not an item set.

plan_enrollment

Used by subscription/trial events: subscription_created, trial_started.

Field	Required	Type	Notes
type	Yes	string	Must be plan_enrollment.
plan_id	No	string	Internal plan identifier.
amount	No	integer	Event-level monetary value, lowest denomination.
currency	Conditional	string	Required when amount is present.
contents	No	array of Content	Optional plan-related items.

custom

Field	Required	Type	Notes
type	Yes	string	Must be custom.
plan_id	No	string	Optional plan identifier.
amount	No	integer	Event-level monetary value, lowest denomination.
currency	Conditional	string	Required when amount is present.
contents	No	array of Content	Optional items.

Content (item shape inside contents[])

Use only these fields. No undocumented keys.

Field	Required	Type	Notes
id	No	string	Internal item identifier (your SKU).
name	No	string	Human-readable item name.
content_type	No	string	Non-empty category — product, plan, page, etc.
quantity	No	integer	Integer, not string.
amount	No	integer	Item-level value, lowest denomination.
currency	No	string	Include with item-level amount, or rely on event-level currency.

Worked example: order conversion (pixel)

oaiq("measure", "order_created", {
  type: "contents",
  amount: 2599,
  currency: "USD",
  contents: [
    {
      id: "sku_123",
      name: "Starter bundle",
      content_type: "product",
      quantity: 1
    }
  ]
}, {
  event_id: "order_12345"
});

Worked example: same order via CAPI

curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL-ID>" 
  -H "Authorization: Bearer <API-KEY>" 
  -H "Content-Type: application/json" 
  --data '{
    "validate_only": false,
    "events": [{
      "id": "order_12345",
      "type": "order_created",
      "timestamp_ms": 1773892800000,
      "oppref": "oppref_abc",
      "source_url": "https://shop.example.com/checkout/confirmation",
      "action_source": "web",
      "data": {
        "type": "contents",
        "amount": 2599,
        "currency": "USD",
        "contents": [{
          "id": "sku_123",
          "name": "Starter bundle",
          "content_type": "product",
          "quantity": 1
        }]
      }
    }]
  }'

Same event_id (pixel) and id (server) — that’s how dedup works (Chapter 12).