{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/account/get-account-financials-response.json",
  "title": "Get Account Financials Response",
  "description": "Financial status for an operator-billed account. Returns spend summary, credit/balance status, payment status, and invoice history. The level of detail varies by seller — only account, currency, and period are guaranteed on success.",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/version-envelope.json"
    },
    {
      "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/protocol-envelope.json"
    }
  ],
  "oneOf": [
    {
      "title": "GetAccountFinancialsSuccess",
      "description": "Financial data retrieved successfully",
      "type": "object",
      "properties": {
        "account": {
          "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/account-ref.json",
          "description": "Account reference, echoed from the request"
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "ISO 4217 currency code for all monetary amounts in this response"
        },
        "period": {
          "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/date-range.json",
          "description": "The actual period covered by spend data. May differ from the requested period if the seller adjusts to billing cycle boundaries."
        },
        "timezone": {
          "type": "string",
          "description": "IANA timezone of the seller's billing day boundaries (e.g., 'America/New_York'). All dates in this response — period, invoice periods, due dates — are calendar dates in this timezone. This may differ from Account.timezone or a feature-specific cap/reporting timezone when the upstream platform uses distinct clocks; buyers MUST use this value for financial periods rather than infer equality."
        },
        "spend": {
          "type": "object",
          "description": "Spend summary for the period",
          "properties": {
            "total_spend": {
              "type": "number",
              "minimum": 0,
              "description": "Total spend in the period, in currency"
            },
            "media_buy_count": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of active media buys in the period"
            }
          },
          "required": [
            "total_spend"
          ]
        },
        "credit": {
          "type": "object",
          "description": "Credit status. Present for credit-based accounts (payment_terms like net_30).",
          "properties": {
            "credit_limit": {
              "type": "number",
              "minimum": 0,
              "description": "Maximum outstanding balance allowed"
            },
            "available_credit": {
              "type": "number",
              "description": "Remaining credit available (credit_limit minus outstanding balance)"
            },
            "utilization_percent": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "description": "Credit utilization as a percentage (0-100)"
            }
          },
          "required": [
            "credit_limit",
            "available_credit"
          ]
        },
        "balance": {
          "type": "object",
          "description": "Prepay balance. Present for prepay accounts.",
          "properties": {
            "available": {
              "type": "number",
              "minimum": 0,
              "description": "Remaining prepaid balance"
            },
            "last_top_up": {
              "type": "object",
              "description": "Most recent balance top-up",
              "properties": {
                "amount": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Top-up amount"
                },
                "date": {
                  "type": "string",
                  "format": "date",
                  "description": "Date of top-up"
                }
              },
              "required": [
                "amount",
                "date"
              ]
            }
          },
          "required": [
            "available"
          ]
        },
        "payment_status": {
          "type": "string",
          "enum": [
            "current",
            "past_due",
            "suspended"
          ],
          "description": "Overall payment status. current: all obligations met. past_due: one or more invoices overdue. suspended: account suspended due to payment issues."
        },
        "payment_terms": {
          "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/enums/payment-terms.json",
          "description": "Payment terms in effect for this account"
        },
        "invoices": {
          "type": "array",
          "description": "Recent invoices. Sellers may limit the number returned.",
          "items": {
            "type": "object",
            "properties": {
              "invoice_id": {
                "type": "string",
                "description": "Seller-assigned invoice identifier"
              },
              "period": {
                "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/date-range.json",
                "description": "Billing period covered by this invoice"
              },
              "amount": {
                "type": "number",
                "minimum": 0,
                "description": "Invoice total in currency"
              },
              "status": {
                "type": "string",
                "enum": [
                  "draft",
                  "issued",
                  "paid",
                  "past_due",
                  "void"
                ],
                "description": "Invoice status"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "description": "Payment due date"
              },
              "paid_date": {
                "type": "string",
                "format": "date",
                "description": "Date payment was received. Present when status is 'paid'."
              },
              "invoice_kind": {
                "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/enums/invoice-kind.json",
                "x-status": "experimental",
                "x-added-in": "3.3.0",
                "description": "Whether this record is an invoice or a credit note. Absent means invoice. Amounts are never negative, so a credit_note carries a non-negative amount that reduces what the buyer owes. Sellers MUST NOT send credit_note records to callers pinned below AdCP 3.3. Experimental in AdCP 3.3 (account.invoice_lines)."
              },
              "adjusts_invoice_id": {
                "type": "string",
                "minLength": 1,
                "x-status": "experimental",
                "x-added-in": "3.3.0",
                "description": "For a credit note or a rebill, the invoice_id of the invoice this record changes. Reference only: the field does not itself alter, void, or settle the referenced invoice; that invoice's status is reported on its own record. Experimental in AdCP 3.3 (account.invoice_lines)."
              },
              "lines": {
                "type": "array",
                "x-status": "experimental",
                "x-added-in": "3.3.0",
                "description": "Itemised lines tying this invoice's amount to the media buys, packages, official reporting revisions, and reporting adjustments it bills. Reference only, never settles: lines let a buyer reconcile an invoice against delivery and do not create, approve, or settle invoices. Optional; sellers that do not itemise return invoices without lines. Buyers MUST NOT assume lines are exhaustive: the sum of line amounts SHOULD NOT exceed amount, and the remainder is unitemised. Experimental in AdCP 3.3 (account.invoice_lines): a seller that returns lines MUST list account.invoice_lines in experimental_features on get_adcp_capabilities.",
                "items": {
                  "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/invoice-line.json"
                }
              }
            },
            "required": [
              "invoice_id",
              "amount",
              "status"
            ]
          }
        },
        "context": {
          "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/context.json"
        },
        "ext": {
          "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/ext.json"
        }
      },
      "required": [
        "account",
        "currency",
        "period",
        "timezone"
      ],
      "additionalProperties": true,
      "not": {
        "required": [
          "errors"
        ]
      }
    },
    {
      "title": "GetAccountFinancialsError",
      "description": "Operation failed — financials not available",
      "type": "object",
      "properties": {
        "errors": {
          "type": "array",
          "description": "Operation-level errors",
          "items": {
            "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/error.json"
          },
          "minItems": 1
        },
        "context": {
          "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/context.json"
        },
        "ext": {
          "$ref": "https://adcontextprotocol.org/schemas/3.3.0-beta.1/core/ext.json"
        }
      },
      "required": [
        "errors"
      ],
      "additionalProperties": true,
      "not": {
        "anyOf": [
          {
            "required": [
              "account"
            ]
          },
          {
            "required": [
              "currency"
            ]
          },
          {
            "required": [
              "period"
            ]
          },
          {
            "required": [
              "timezone"
            ]
          }
        ]
      }
    }
  ],
  "examples": [
    {
      "description": "Credit account — current, with invoice history",
      "data": {
        "status": "completed",
        "account": {
          "account_id": "acc_acme_001"
        },
        "currency": "USD",
        "period": {
          "start": "2026-02-01",
          "end": "2026-02-28"
        },
        "timezone": "America/New_York",
        "spend": {
          "total_spend": 45230,
          "media_buy_count": 3
        },
        "credit": {
          "credit_limit": 100000,
          "available_credit": 54770,
          "utilization_percent": 45.23
        },
        "payment_status": "current",
        "payment_terms": "net_30",
        "invoices": [
          {
            "invoice_id": "inv_2026_01",
            "period": {
              "start": "2026-01-01",
              "end": "2026-01-31"
            },
            "amount": 38500,
            "status": "paid",
            "due_date": "2026-02-28",
            "paid_date": "2026-02-15"
          }
        ]
      }
    },
    {
      "description": "Itemised invoice and credit note (experimental, account.invoice_lines)",
      "data": {
        "status": "completed",
        "account": {
          "account_id": "acc_acme_001"
        },
        "currency": "USD",
        "period": {
          "start": "2026-03-01",
          "end": "2026-03-31"
        },
        "timezone": "America/New_York",
        "invoices": [
          {
            "invoice_id": "inv_2026_02",
            "period": {
              "start": "2026-02-01",
              "end": "2026-02-28"
            },
            "amount": 45230,
            "status": "issued",
            "due_date": "2026-03-30",
            "lines": [
              {
                "media_buy_id": "mb_spring_launch",
                "package_id": "pkg_ctv_prime",
                "reporting_revision_ids": [
                  "rev_mb_spring_launch_2026_02_official"
                ],
                "billed_quantity": {
                  "name": "impressions",
                  "value": "1808000",
                  "value_type": "integer",
                  "unit": "impressions"
                },
                "amount": 45230
              }
            ]
          },
          {
            "invoice_id": "cn_2026_03_001",
            "invoice_kind": "credit_note",
            "adjusts_invoice_id": "inv_2026_02",
            "period": {
              "start": "2026-03-01",
              "end": "2026-03-31"
            },
            "amount": 1200,
            "status": "issued",
            "lines": [
              {
                "media_buy_id": "mb_spring_launch",
                "package_id": "pkg_ctv_prime",
                "reporting_adjustment_ids": [
                  "adj_mb_spring_launch_2026_02_ivt"
                ],
                "billed_quantity": {
                  "name": "impressions",
                  "value": "48000",
                  "value_type": "integer",
                  "unit": "impressions"
                },
                "amount": 1200
              }
            ]
          }
        ]
      }
    },
    {
      "description": "Prepay account with low balance",
      "data": {
        "status": "completed",
        "account": {
          "brand": {
            "domain": "acme-corp.com"
          },
          "operator": "acme-corp.com"
        },
        "currency": "USD",
        "period": {
          "start": "2026-02-01",
          "end": "2026-02-28"
        },
        "timezone": "America/Los_Angeles",
        "spend": {
          "total_spend": 8200,
          "media_buy_count": 2
        },
        "balance": {
          "available": 1800,
          "last_top_up": {
            "amount": 10000,
            "date": "2026-02-01"
          }
        },
        "payment_status": "current",
        "payment_terms": "prepay"
      }
    },
    {
      "description": "Agent-billed account — not supported",
      "data": {
        "status": "completed",
        "errors": [
          {
            "code": "UNSUPPORTED_FEATURE",
            "message": "Financial data is not available for agent-billed accounts. The agent's own billing system is the source of truth."
          }
        ]
      }
    }
  ],
  "properties": {}
}