Skip to main content

​
Ledger Record Schema

​
Overview

Final reservation-based ledger entry that records the reserved amount, actual billing, and revenue share for a serve_token.

​
Required Fields

FieldTypeDescription
serve_tokenstringToken linking exposure → click → conversion
session_idstringConversation/session identifier
auction_idstringAuction that produced the serve
platform_idstringPlatform identifier
brand_agent_idstringWinning Brand Agent
statestringLedger state (PENDING, EXPOSED, CLICKED, CONVERTED, FINALIZED, REFUNDED)
reserved_unitstringUnit reserved at auction (CPX, CPC, CPA)
reserved_amount_centsintegerAmount held from the wallet (in cents)
final_unitstringUnit actually billed (CPX, CPC, CPA)
final_amount_centsintegerActual charge applied (in cents)
currencystringISO currency code
timestampsobjectISO timestamps for major lifecycle steps

​
Timestamps Object

FieldTypeDescription
auctionstringWhen the auction completed
exposurestringWhen exposure occurred
clickstringWhen click occurred
conversionstringWhen conversion occurred
finalizedstringWhen ledger entry was finalized

​
Optional Fields

FieldTypeDescription
revenue_shareobjectBreakdown of platform/operator cents
extobjectVendor extensions

​
Revenue Share Object

FieldTypeDescription
platform_centsintegerPortion allocated to the platform
operator_centsintegerPortion allocated to the operator

​
Example

{
  "serve_token": "stk_abcxyz123",
  "session_id": "sess_001",
  "auction_id": "auc_981",
  "platform_id": "pf_openai_chat",
  "brand_agent_id": "ba_451",
  "state": "FINALIZED",
  "reserved_unit": "CPA",
  "reserved_amount_cents": 500,
  "final_unit": "CPC",
  "final_amount_cents": 120,
  "currency": "USD",
  "timestamps": {
    "auction": "2025-11-14T18:00:00Z",
    "exposure": "2025-11-14T18:00:01Z",
    "click": "2025-11-14T18:00:05Z",
    "conversion": "2025-11-14T18:03:00Z",
    "finalized": "2025-11-14T19:00:00Z"
  },
  "revenue_share": {
    "platform_cents": 30,
    "operator_cents": 90
  }
}

​
Validation Rules

  • Amount fields must be integers ≥ 0
  • state must be one of the defined enum values
  • reserved_unit and final_unit must each be CPX, CPC, or CPA
  • All timestamps must be ISO 8601 date-time strings