get_account_financials

get_account_financials returns spend summaries, credit balances, payment status, and invoice history for operator-billed AdCP accounts. Requires account_financials capability.

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/v3/account/get-account-financials-request.json Response Schema: /schemas/v3/account/get-account-financials-response.json

Quick start

Check remaining credit before launching a campaign:

JavaScript

import { testAgent } from "@adcp/sdk/testing";

const result = await testAgent.getAccountFinancials({
  account: { account_id: "acc_acme_001" },
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

if ("errors" in result.data && result.data.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(result.data.errors)}`);
}

const { spend, credit, payment_status } = result.data;
console.log(`Spent: $${spend?.total_spend} this period`);

if (credit) {
  console.log(`Available credit: $${credit.available_credit} of $${credit.credit_limit}`);
}

if (payment_status === "past_due") {
  console.log("Warning: payment is past due — campaigns may be paused");
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.get_account_financials(
        account={"account_id": "acc_acme_001"},
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    print(f"Spent: ${result.spend.total_spend} this period")

    if hasattr(result, 'credit') and result.credit:
        print(f"Available credit: ${result.credit.available_credit} of ${result.credit.credit_limit}")

    if getattr(result, 'payment_status', None) == 'past_due':
        print("Warning: payment is past due — campaigns may be paused")

asyncio.run(main())

Request parameters

Parameter	Type	Required	Description
account	object	Yes	Account reference — by account_id or natural key (brand + operator + optional sandbox). Must be an operator-billed account.
period	object	No	Date range for spend summary: start and end as ISO 8601 dates. Defaults to the current billing cycle if omitted.

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.

Field	Description
account	Account reference, echoed from the request.
currency	ISO 4217 currency code for all monetary amounts.
period	Actual period covered (start, end). May differ from requested period if adjusted to billing cycle boundaries.
timezone	IANA timezone of the seller’s billing day boundaries (e.g., America/New_York). All dates in the response are calendar dates in this timezone.
spend	Spend summary: total_spend (amount in currency) and optional media_buy_count.
credit	Present for credit-based accounts. Contains credit_limit, available_credit, and optional utilization_percent (0-100).
balance	Present for prepay accounts. Contains available balance and optional last_top_up (amount, date).
payment_status	current, past_due, or suspended.
payment_terms	Payment terms in effect: net_15, net_30, net_45, net_60, net_90, or prepay.
invoices	Array of recent invoices: invoice_id, amount, status (draft, issued, paid, past_due, void), optional period, due_date, paid_date.

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.

Common scenarios

Budget check before campaign launch

JavaScript

import { testAgent } from "@adcp/sdk/testing";

const financials = await testAgent.getAccountFinancials({
  account: { account_id: "acc_acme_001" },
});

if (!financials.success || "errors" in financials.data) {
  throw new Error("Could not check financials");
}

const campaignBudget = 15000;
const { credit } = financials.data;

if (credit && credit.available_credit < campaignBudget) {
  console.log(
    `Insufficient credit: $${credit.available_credit} available, ` +
    `$${campaignBudget} needed. ` +
    `Credit utilization: ${credit.utilization_percent}%`
  );
} else {
  console.log("Budget check passed — proceeding with campaign");
}

import asyncio
from adcp.testing import test_agent

async def main():
    financials = await test_agent.simple.get_account_financials(
        account={"account_id": "acc_acme_001"},
    )

    if hasattr(financials, 'errors') and financials.errors:
        raise Exception("Could not check financials")

    campaign_budget = 15000
    credit = getattr(financials, 'credit', None)

    if credit and credit.available_credit < campaign_budget:
        print(
            f"Insufficient credit: ${credit.available_credit} available, "
            f"${campaign_budget} needed. "
            f"Credit utilization: {credit.utilization_percent}%"
        )
    else:
        print("Budget check passed — proceeding with campaign")

asyncio.run(main())

Prepay balance monitoring

JavaScript

import { testAgent } from "@adcp/sdk/testing";

const financials = await testAgent.getAccountFinancials({
  account: {
    brand: { domain: "acme-corp.com" },
    operator: "acme-corp.com",
  },
});

if (!financials.success || "errors" in financials.data) {
  throw new Error("Could not check financials");
}

const { balance } = financials.data;
if (balance && balance.available < 2000) {
  console.log(
    `Low balance warning: $${balance.available} remaining. ` +
    `Consider topping up before launching new campaigns.`
  );
}

import asyncio
from adcp.testing import test_agent

async def main():
    financials = await test_agent.simple.get_account_financials(
        account={
            "brand": {"domain": "acme-corp.com"},
            "operator": "acme-corp.com",
        },
    )

    if hasattr(financials, 'errors') and financials.errors:
        raise Exception("Could not check financials")

    balance = getattr(financials, 'balance', None)
    if balance and balance.available < 2000:
        print(
            f"Low balance warning: ${balance.available} remaining. "
            f"Consider topping up before launching new campaigns."
        )

asyncio.run(main())

Error handling

Error Code	Description	Resolution
UNSUPPORTED_FEATURE	Account uses agent billing — financials not available from seller	Query your own billing system for agent-billed accounts
UNSUPPORTED_FEATURE	Seller doesn’t have financial data for this account or period	Verify account_financials capability is true
ACCOUNT_NOT_FOUND	Account does not exist or is not accessible	Check account reference or re-sync

Next steps

• list_accounts — Discover accounts and check their status
• get_adcp_capabilities — Check account_financials before calling this task
• Accounts and agents — Billing models and account references