Get billing account

GET /api/v2/billing/account Returns one document that answers, for whoever is responsible for an account’s money: which plan and terms the account is on, what has been used, what is funded and what is owed, which agreements are in force, and the one concrete step — if any — needed to become or remain paid. It reads the same facts the org-settings Billing tab and the Plan & Billing page show; anything shown on those surfaces that isn’t in this document is a bug. Money always describes the organization: a child account’s request resolves to its parent (billing lives at the org level), and the returned organization.customerId reflects that. A human caller needs org-admin standing (a child-account admin must also be an admin of the parent). An API key (service token) issued to the organization gets the document with payment-detail fields and contract-document download links redacted — marked with "visibility": "redacted" and redactedFields so an agent can tell “not allowed” from “empty”. Advertiser-scoped keys and keys issued to a child account are denied. Credit-application reviewer notes are internal to Scope3 and always read as null here; your own justification text stays visible. The document keeps two pricing systems separate. plan, pricing, and contracts.mediaRateCard describe the active media contract used to clear buys. enterpriseContracts describes the unpublished Organization IU plan pilot. An absent IU offer or accepted plan does not invalidate an active media rate card. IU offers remain absent unless the billing organization is enrolled in the pilot; accepted history remains visible as a contractual record.

Request

curl

curl "https://api.interchange.io/api/v2/billing/account" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

This endpoint takes no parameters.

From an agent (MCP)

Two read-only MCP tools cover the same document on both the buyer and storefront MCP servers — billing lives at the organization level regardless of role:

get_billing_account returns this document as the tool’s structured content. An optional section parameter (one of organization, scope, standing, plan, pricing, usage, payment, contracts, accounts, enterpriseContracts, nextAction, permissions) returns just that section to keep the response small; section: "accounts" also returns totalAccounts, since the accounts array is capped at 50 entries.
open_plan_and_billing opens the Plan & Billing view in chat — a read-only page showing standing, balance, Enterprise Contract rights and lifecycle, the next action, and an intelligence-usage summary, with links to the full web page.

Neither tool mutates anything: accepting terms, funding a balance, and applying for credit remain separate flows.

Response

{
  "organization": {
    "customerId": 246,
    "name": "Blue Peak Brands",
    "roles": ["BUYER"],
    "currency": "USD"
  },
  "scope": {
    "boundary": "ORG",
    "delegatedFrom": null
  },
  "standing": {
    "posture": "CREDIT",
    "creditLimitMinor": "5000000",
    "currency": "USD",
    "verificationLevel": "kyb_verified",
    "holds": []
  },
  "plan": {
    "tosVersion": "v3-0",
    "tosAcceptedAt": "2026-01-15T18:04:00.000Z",
    "tosAcceptedByEmail": "dana@bluepeakbrands.example",
    "contractStatus": "active",
    "rateCardType": "STANDARD",
    "effectiveDate": "2026-01-15T00:00:00.000Z",
    "endDate": null,
    "autoRenewal": null,
    "subscriptions": []
  },
  "pricing": {
    "effective": { "type": "STANDARD", "rates": [] },
    "publicList": null,
    "provenance": "STANDARD"
  },
  "usage": {
    "intelligence": {
      "periodStart": "2026-07-01T00:00:00.000Z",
      "byFeature": [],
      "byDay": [],
      "totalCostMicroUsd": 0
    },
    "creditBalance": {
      "effectiveCustomerId": 246,
      "currency": "USD",
      "creditLimitMinor": "5000000",
      "fundedBalanceMinor": "0",
      "owedBalanceMinor": "1200000",
      "netBalanceMinor": "1200000",
      "spendableMinor": "3800000",
      "accounts": []
    },
    "orgPosition": {
      "orgRootCustomerId": 246,
      "customerCount": 1,
      "currency": "USD",
      "fundedMinor": "0",
      "committedMinor": "300000",
      "creditLimitMinor": "5000000",
      "availableMinor": "4700000",
      "overLimit": false
    }
  },
  "payment": {
    "billingInfo": {
      "contactName": "Dana Whitfield",
      "email": ["ap@bluepeakbrands.example"],
      "ccEmails": [],
      "phone": null,
      "address": "225 Mission St",
      "address2": null,
      "city": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "countryAlpha2": "US",
      "taxId": "83-1234567",
      "visibility": "visible",
      "redactedFields": []
    },
    "storefrontBilling": null,
    "creditApplications": [],
    "deposits": [],
    "invoices": []
  },
  "contracts": {
    "agreements": [
      {
        "contractId": "9001",
        "status": "active",
        "agreementKind": "STANDARD_TOS",
        "effectiveDate": "2026-01-15T00:00:00.000Z",
        "endDate": null,
        "acceptedAt": "2026-01-15T18:04:00.000Z",
        "acceptedByEmail": "dana@bluepeakbrands.example"
      }
    ],
    "documents": [],
    "mediaRateCard": null
  },
  "enterpriseContracts": {
    "commercialState": {
      "billingCustomerId": 246,
      "eligible": false,
      "eligibleWorkloads": [],
      "commercialStatus": "FREE",
      "offer": null,
      "currentBinding": null,
      "upcomingBinding": null,
      "history": [],
      "renewal": null,
      "setupGrant": null,
      "calibratingActivities": [],
      "paymentSetupUrl": "https://app.interchange.io/246/billing?tab=payment",
      "nextAction": "NONE"
    },
    "packages": [],
    "visibility": "visible",
    "redactedFields": []
  },
  "accounts": [],
  "totalAccounts": 0,
  "nextAction": {
    "type": "NONE",
    "message": "Your account is in good standing.",
    "docsUrl": null,
    "route": null,
    "taskId": null
  },
  "permissions": {
    "canAcceptTos": true,
    "canEditBillingInfo": true,
    "canApplyForCredit": true
  }
}

Document sections

Section	What it is
`organization`	The org this document describes — always the PARENT/STANDALONE customer, never a child’s own id
`scope`	Whose money this is (`boundary`) and, for a delegated child, which parent it’s delegated from
`standing`	Credit posture: `PREPAY` (fund a balance to spend) or `CREDIT` (Scope3-granted line), the limit, and any payment holds
`plan`	Terms of Service version/acceptance, contract status, rate card type, contract dates
`pricing`	The rate card actually applied to this account, and (once published) the public price list for comparison
`usage`	Intelligence/AI usage by feature and by day, plus the credit/prepay balance and org-wide funded/committed/available position
`payment`	Billing (payer) info, shared organization IU commercial terms summary when published, credit application history, deposits, invoices
`contracts`	Agreement records and supporting documents
`enterpriseContracts`	The authoritative pending Offer and accepted package history: governing agreement kind/version, immutable Rate Card acceptance and lineage, product entitlements, support package, renewal state, lifecycle, and machine-readable reason codes
`accounts`	For a parent org: its child accounts in their billing dimension only — not a way to switch accounts. Every child uses the organization’s media pricing. The compatibility `delegation` field is a reserved placeholder and always reads `NONE`; it does not control media-pricing inheritance. Model-facing MCP output preserves that field and also returns the authoritative `mediaPricingSource: "ORGANIZATION"` with `inheritsMediaPricing: true`. Capped at 50 entries; `totalAccounts` carries the uncapped count
`nextAction`	The single most important thing to do next — see below
`permissions`	What the authenticated caller may do with this account (drives whether a UI shows write affordances)

payment.deposits lists the organization’s recent prepay deposits (newest first, at most 10): each row carries the deposited amount in minor units, its currency, when it took effect, whether it was later reversed, and the payment provider and reference recorded with it. Every row is projected read-only from the platform ledger — the same source of truth as the balances above. Some fields are typed but always empty today because the platform doesn’t yet have a source for them: plan.subscriptions, pricing.publicList, and payment.invoices. They will start populating as their owning features ship, with no change to this response shape.

Enterprise Contract lifecycle

enterpriseContracts.commercialState is the complete Offer and immutable Rate Card acceptance read model. Plan & Billing consumes the complete authenticated REST object. MCP consumes the model-safe projection described below; neither surface reconstructs commercial terms from flags or account metadata. enterpriseContracts.packages adds a lifecycle projection for every accepted Enterprise package record, including its purchased product rights. Ordinary public IU plan records remain in commercialState.history and are not mislabelled as Enterprise Contracts:

`lifecycleState`	Reason code	Meaning
`PENDING_FUNDING`	`payment_authority_missing`	An authorized administrator accepted the package, so the contract and rights are purchased, but the selected card, invoice-credit, ACH, or term-prepay authority is not ready. Rights have state `PENDING` and do not grant runtime access.
`SCHEDULED`	`term_not_started`	The package is accepted and begins on its contracted service-start date. Rights have state `PENDING`.
`ACTIVE`	`in_force`	The governing agreement, term, and payment authority are in force. Rights have state `ACTIVE`.
`BILLING_HOLD`	`billing_hold`	The package is still purchased; it is not reported as “not purchased.” Runtime rights have state `SUSPENDED` until the hold is resolved.
`SUSPENDED`	`contract_not_in_force`	The package remains in accepted history, but the governing contract is not currently in force. Runtime rights have state `SUSPENDED`.
`EXPIRED`	`term_ended`	The term ended without an accepted successor. Rights have state `EXPIRED`.
`SUPERSEDED`	`successor_accepted`	A successor acceptance replaced this package. The immutable predecessor remains visible and its rights have state `EXPIRED`.

For a full-term prepayment, funding is recorded against the exact accepted Enterprise Contract acceptance. Once the complete required amount is confirmed, ordinary use of that prepaid balance does not make the package pending again. If the funding deposit is reversed, the payment authority is no longer satisfied and runtime access closes until funding is restored. Every entry in rights carries purchased: true independently of its runtime state. This distinction is deliberate: acceptance records what the customer bought, while funding, holds, term dates, and suspension determine whether the right can be exercised now. For an organization-scoped service token, enterpriseContracts.visibility is redacted: immutable proposal prose and the selected payment option read as null, and redactedFields names both fields. Human organization admins see visibility: "visible". Internal actor and database identifiers are never part of this customer-facing projection. The get_billing_account agent tool also replaces stored proposal prose and the selected payment choice with null so customer-authored contract text and payment details cannot enter model context. Its model-visible history is partitioned and bounded: accepted Enterprise records appear once under enterpriseContracts.packages, while ordinary IU plan records remain under commercialState.history; each list contains at most the 20 newest entries. Accepted records and offers are explicit summaries rather than the deep REST snapshots, and each package returns at most 10 rights. Companion total/truncated fields disclose array, text, and 96 KiB UTF-8 byte bounds. Plan labels are code-owned; unrecognized plan codes become numbered options rather than echoing authored text. Exact authored names, activity schedules, Rate Card snapshots, proposal prose, and payment choices stay outside model context. The authenticated REST document used by Plan & Billing keeps the complete history and exact terms. The IU-plan launcher gives the model only a bounded launch receipt; the full authenticated Task state is delivered to the requesting MCP App outside model context. The Plan & Billing web page retains the human service schedule. When enterpriseContracts.commercialState.nextAction asks for acceptance, use open_iu_plan_task to review the exact version and accept_iu_rate_card_offer for the human-confirmed acceptance step. The write tool re-verifies that the caller is a current administrator of the governing organization; an administrator of only a child account cannot read or accept the parent package.

`plan.contractStatus` values

`contractStatus`	Meaning
`active`	The account holds its own accepted contract.
`awaiting_acceptance`	Scope3 has set the account up on standard terms, but nobody at the account has accepted them yet. The contract and its rate card are real and apply the moment they are accepted; until then the account cannot transact. An admin of the organization accepts via `POST /api/v2/accept-tos` or the `accept_tos` agent tool — Scope3 does not accept on your behalf. `nextAction` is `ACCEPT_TOS`.
`no_contract`	No contract exists for the account at all.
`inherited_active`	The account inherits its organization’s contract, and the organization shares its terms.
`inherited_hidden`	The account inherits, but the organization has not shared its terms; contract fields are omitted.
`organization_contract_missing`	The account inherits, but the organization has no active contract. An organization admin must accept on its behalf.

Only active and inherited_active mean the account can transact. In particular, awaiting_acceptance carries a real contractId — do not read the presence of a contract as proof the account is ready.

`nextAction` values

`type`	Meaning
`ACCEPT_TOS`	The current Terms of Service haven’t been accepted yet. Resolve with `POST /api/v2/accept-tos` or the `accept_tos` agent tool.
`ACCEPT_GOVERNING_AGREEMENT`	An issued Enterprise Offer needs its governing agreement reviewed before plan selection. Open the `open_iu_plan_task` Task.
`SELECT_IU_PLAN`	An Enterprise Rate Card is ready for the organization to review and select. Open the `open_iu_plan_task` Task.
`CONTACT_SCOPE3`	The accepted Enterprise payment option needs an operator-assisted authority that the enabled self-serve rails cannot establish. Follow `docsUrl` to contact Scope3; no unreachable route is returned.
`ADD_BILLING_INFO`	No billing contact/address is on file. Resolve with Update billing info.
`FUND_PREPAY`	The account has no credit line and its prepay balance is exhausted. This currently reflects buyer media standing; org-wide IU plan funding is not active before the Rate Card is published. Contact Scope3 to fund your account — self-serve funding is not yet available.
`APPLY_FOR_CREDIT`	The account holds a credit line that is exhausted (buyer orgs only). Apply for a higher limit. The resolving `route` is present only when the credit-applications API is enabled for your account; otherwise contact Scope3.
`RESOLVE_HOLD`	A payment hold is blocking spend.
`NONE`	Nothing outstanding — the account is in good standing.

Only one nextAction is ever returned — the single most important thing to do, not a checklist. permissions tells you whether the authenticated caller can act on it directly, or should route it to an account admin.

Errors

401 UNAUTHORIZED — missing or invalid bearer token.
403 ACCESS_DENIED — the caller is not an account admin (or, for a child account, an admin of the parent organization), or the API key is advertiser-scoped or issued to a child account.

See Errors for the full error contract.

Get billing info

The payer identity on its own, without the rest of the account

Billing overview

How invoicing and remittance work

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Request

Parameters

From an agent (MCP)

Response

Document sections

Enterprise Contract lifecycle

`plan.contractStatus` values

`nextAction` values

Errors

Get billing info

Billing overview

​Request

​Parameters

​From an agent (MCP)

​Response

​Document sections

​Enterprise Contract lifecycle

​plan.contractStatus values

​nextAction values

​Errors

​Related

Get billing info

Billing overview

Request

Parameters

From an agent (MCP)

Response

Document sections

Enterprise Contract lifecycle

`plan.contractStatus` values

`nextAction` values

Errors

Related