Skip to main content
Query financial status for an operator-billed account — spend summary, credit or prepay balance, payment status, and invoice history. This gives budget-aware agents the context they need to make spend decisions without leaving the protocol. get_account_financials is only available when the seller declares account_financials: true in get_adcp_capabilities. It applies to operator-billed accounts only. For agent-billed accounts, the agent’s own billing system is the source of truth. Response Time: ~1s. Request Schema: /schemas/3.3.0-beta.1/account/get-account-financials-request.json Response Schema: /schemas/3.3.0-beta.1/account/get-account-financials-response.json

Quick start

Check remaining credit before launching a campaign:

Request parameters

Response

Success response: Returns financial data for the account. Only account, currency, period, and timezone are guaranteed — everything else depends on what the seller exposes. Error response:
  • errors — Array of operation-level errors. No financial data is present.
Note: Responses use discriminated unions — you get either financial data OR errors, never both.

Being notified of new invoices

Sellers that list invoice in account.change_feed.resource_types record a change when an invoice is created, changes status, or has its amount or period corrected. Subscribe to account.change_recorded and drain list_account_changes instead of polling; each record carries the invoice_id as resource.resource_id, and the buyer rereads this task to get the invoice. The feed is experimental. Buyers of sellers without it must keep polling.

Common scenarios

Budget check before campaign launch

Prepay balance monitoring

Invoice lines (experimental)

Experimental in AdCP 3.3 under the account.invoice_lines feature id. A seller that returns lines, invoice_kind, or adjusts_invoice_id MUST list account.invoice_lines in experimental_features on get_adcp_capabilities. See Experimental status.
An official reporting revision is the invoice-addressable close for its reporting slice, but an invoice that carries only invoice_id and amount cannot say which of that reporting it billed. Sellers that itemise add optional fields to each invoices[] item: Amounts are never negative. A credit note is invoice_kind: "credit_note" with a non-negative amount; the kind carries the sign, and a buyer subtracts it from what is owed. A credit note has no due_date; its paid_date, when present, is the date the credit was applied or refunded. A document is one direction: a net-negative correction goes on a credit_note, never on an invoice, and line billed_quantity values are non-negative. Sellers MUST NOT send credit_note records to callers pinned below AdCP 3.3, because a legacy buyer summing invoices[].amount would count the credit as a charge. A rebill is a new invoice that carries adjusts_invoice_id; the replaced invoice is reported void or offset by a credit note, so buyers do not count both. reporting_revision_ids and reporting_adjustment_ids are the opaque ids from the media_buy.reporting_delivery surface. Lines are reference only and never settle. They identify which reporting an invoice amount covers; they do not create, approve, or settle invoices, calculate tax or FX, or determine payment obligations, which stays inside the boundary set by core/reporting-adjustment.json and enums/billing-party.json. The sum of line amounts SHOULD NOT exceed the invoice amount; taxes, fees, and unitemised charges may sit outside the lines. Sellers that do not itemise keep returning invoices without lines. Buyers read lines through get_account_financials, including as the repair read for an invoice change on the account change feed. The line shape is the standalone core/invoice-line.json, so a later invoice notification can carry the same lines without changing shape.

Error handling

Next steps