AdCP — report

Reports how a vendor’s service was consumed after campaign delivery. Called by orchestrators to inform a vendor agent (signals, governance, creative) what was used so the vendor can track earned revenue and verify billing. It is also used against the sales agent itself when a media buy names the buyer or a measurement vendor as the billing authority. Each usage record is self-contained — it carries its own account and media_buy_id. A single request can span multiple accounts and campaigns. Response Time: ~1s. Response Schema: /schemas/3.2.0-beta.0/account/report-usage-response.json

Request Parameters

Parameter	Type	Required	Description
`idempotency_key`	string	Recommended	Client-generated unique key for this request (UUID recommended). If a request with the same key has already been accepted, the server returns the original response without re-processing. Prevents duplicate billing on retries.
`reporting_period`	object	Yes	`start` and `end` as ISO 8601 date-time in UTC. Applies to all records in the request.
`usage`	UsageRecord[]	Yes	One or more usage records.

Usage Record Fields

Each record requires account, vendor_cost, and currency. Additional fields depend on the vendor type:

Field	Type	Required	Description
`account`	AccountRef	Yes	Account for this record — by `account_id` or `{ brand, operator }`.
`vendor_cost`	number	Yes	Amount owed to the vendor for this record, in `currency`
`currency`	string	Yes	ISO 4217 currency code
`pricing_option_id`	string	Vendor: Yes	Pricing option from the vendor’s discovery response (`get_signals`, `list_creatives`, `list_content_standards`, `list_property_lists`) or execution response (`build_creative`). The vendor uses this to verify the correct rate was applied.
`impressions`	number	Signals: Yes	Impressions delivered
`media_spend`	number	percent_of_media: Yes	Media spend for percent-of-media cost verification
`media_buy_id`	string	Revenue share: Yes	Media buy whose selected package pricing is being reconciled.
`conversions`	number	No	Number of attributed conversion events. Optional analytics context for revenue share.
`conversion_value`	number	No	Total attributed conversion value. Optional analytics context; not the revenue-share billing basis.
`commissionable_value`	number	Revenue share: Yes	Settled attributed value eligible for commission. The seller verifies `vendor_cost = round_currency(commissionable_value × commission_rate)`.
`signal_agent_segment_id`	string	Signals: Yes	Signal identifier from `get_signals`
`creative_id`	string	Creative: Yes	Creative identifier from `build_creative` or `list_creatives`. Links usage to a specific creative for billing verification. A `build_creative` variant leaf earns a `creative_id` only when trafficked/added to the library — discarded best-of-N or fan-out variants are never reported here; their charge is the inline per-leaf `vendor_cost` on the `build_creative` response (the authoritative record for untrafficked leaves).
`build_variant_id`	string	No	When the reported `creative_id` was promoted from a specific `build_creative` variant leaf but differs from that source id, carry the source `build_variant_id` for reconciliation. On the canonical path where `creative_id` is the kept `build_variant_id`, omit this field.
`property_list_id`	string	Property lists: Yes	Property list identifier from `list_property_lists`. Links usage to a specific property list for billing verification.

For revenue-share records, pricing_option_id identifies the agreed rate and commission basis. currency must match the selected option, and vendor_cost must not exceed the package’s commission budget.

Response

Field	Description
`accepted`	Number of usage records successfully stored
`errors`	Validation errors for individual records. Partial acceptance is valid — accepted records are stored even when some fail.

Examples

Signal usage — single campaign

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "reporting_period": {
    "start": "2025-03-01T00:00:00Z",
    "end": "2025-03-31T23:59:59Z"
  },
  "usage": [
    {
      "account": { "account_id": "acct_pinnacle_signals" },
      "signal_agent_segment_id": "luxury_auto_intenders",
      "pricing_option_id": "po_lux_auto_cpm",
      "impressions": 4200000,
      "media_spend": 21000.00,
      "vendor_cost": 2100.00,
      "currency": "USD"
    }
  ]
}

{
  "accepted": 1
}

Creative usage — ad server with CPM pricing

{
  "idempotency_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reporting_period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "usage": [
    {
      "account": { "account_id": "acct_acme_creative" },
      "creative_id": "cr_88201",
      "pricing_option_id": "po_video_cpm",
      "impressions": 2400000,
      "vendor_cost": 1200.00,
      "currency": "USD"
    }
  ]
}

{
  "accepted": 1
}

Multi-account batch

A single request spanning two campaigns across two accounts:

{
  "idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "reporting_period": {
    "start": "2025-03-01T00:00:00Z",
    "end": "2025-03-31T23:59:59Z"
  },
  "usage": [
    {
      "account": { "account_id": "acct_pinnacle_signals" },
      "signal_agent_segment_id": "luxury_auto_intenders",
      "pricing_option_id": "po_lux_auto_cpm",
      "impressions": 2100000,
      "vendor_cost": 1050.00,
      "currency": "USD"
    },
    {
      "account": { "account_id": "acct_nova" },
      "signal_agent_segment_id": "eco_conscious_shoppers",
      "pricing_option_id": "po_eco_cpm",
      "impressions": 800000,
      "vendor_cost": 400.00,
      "currency": "USD"
    }
  ]
}

Partial acceptance

If some records fail validation, the response identifies how many were accepted:

{
  "accepted": 1,
  "errors": [
    {
      "code": "INVALID_PRICING_OPTION",
      "message": "pricing_option_id 'po_unknown' does not exist on this account",
      "field": "usage[1].pricing_option_id"
    }
  ]
}

Retry Safety

Always include idempotency_key in production usage. If a request times out or returns a network error, retry with the same key — the server will return the original result without double-counting. An idempotent replay is transparent: the server returns the original response unchanged and does not emit a DUPLICATE_REQUEST error or advisory. Generate a fresh UUID per request, not per usage record. If you need to report additional records for the same period, submit a new request with a new key.

Reporting cadence

Report at regular intervals — monthly at minimum. For campaigns with significant spend, weekly reporting gives vendor agents timely visibility into earned revenue. Report upon campaign completion to close out the final period.

Error Handling

Error Code	Description	Resolution
`ACCOUNT_NOT_FOUND`	Account reference in a usage record not found or not accessible	Verify via `list_accounts`; re-run `sync_accounts` if needed
`INVALID_USAGE_DATA`	A usage record has missing or invalid fields	Check required fields for your vendor type
`INVALID_PRICING_OPTION`	`pricing_option_id` not found on this account	Verify `pricing_option_id` from the vendor’s discovery response

Next Steps

sync_accounts — Sync advertiser accounts with a seller before reporting
Accounts Protocol — How account establishment and settlement fit together
Accounts and agents — Billing hierarchy and operator model

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

report_usage

Request Parameters

Usage Record Fields

Response

Examples

Signal usage — single campaign

Creative usage — ad server with CPM pricing

Multi-account batch

Partial acceptance

Retry Safety

Reporting cadence

Error Handling

Next Steps

​Request Parameters

​Usage Record Fields

​Response

​Examples

​Signal usage — single campaign

​Creative usage — ad server with CPM pricing

​Multi-account batch

​Partial acceptance

​Retry Safety

​Reporting cadence

​Error Handling

​Next Steps

Request Parameters

Usage Record Fields

Response

Examples

Signal usage — single campaign

Creative usage — ad server with CPM pricing

Multi-account batch

Partial acceptance

Retry Safety

Reporting cadence

Error Handling

Next Steps