Skip to main content

​
CPA Conversion Event Schema

​
Overview

Event fired when a user completes a CPA-eligible action (signup, purchase, trial start, etc.). This records the final billing event for the serve_token.

​
Required Fields

FieldTypeDescription
event_typestringAlways cpa_conversion
serve_tokenstringToken linking exposure → click → conversion
conversion_idstringUnique identifier for this conversion
conversion_typestringEnum: signup, purchase, trial_start, demo_request, download, custom
wallet_idstringWallet to apply the final CPA charge
brand_agent_idstringBrand agent associated with the conversion
pricing.unitstringMust be CPA
pricing.amount_centsintegerFinal CPA charge (in cents)
timestampstringISO 8601 timestamp for the conversion

​
Optional Fields

FieldTypeDescription
order_value_centsintegerOptional purchase value in cents
currencystringCurrency for order value (ISO 4217)
conversion_metadataobjectAdvertiser-side metadata (user/order/product IDs)
extobjectVendor extensions

​
Pricing Object

FieldTypeDescription
unitstringAlways CPA
amount_centsintegerFinal charge in cents

​
Conversion Metadata Object

FieldTypeDescription
user_idstringAdvertiser user identifier
order_idstringOrder or transaction ID
product_idsstring[]List of product IDs linked to this conversion

​
Example

{
  "event_type": "cpa_conversion",
  "serve_token": "stk_abcxyz123",
  "conversion_id": "cnv_001",
  "conversion_type": "purchase",
  "wallet_id": "wal_ba451",
  "brand_agent_id": "ba_451",
  "pricing": {
    "unit": "CPA",
    "amount_cents": 4900
  },
  "order_value_cents": 25000,
  "currency": "USD",
  "conversion_metadata": {
    "user_id": "usr_12345",
    "order_id": "ord_67890",
    "product_ids": ["prod_crm_pro", "prod_addon_analytics"]
  },
  "timestamp": "2025-11-14T18:30:00Z"
}

​
Validation Rules

  • pricing.amount_cents must be an integer ≥ 0
  • conversion_type must match the defined enum
  • order_value_cents, when present, must be ≥ 0
  • timestamp must be ISO 8601 formatted