> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Get billing account > The consolidated commercial-account view — plan, usage, balance, and agreements in one document `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 Apostra 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 ```bash curl theme={null} curl "https://api.apostra.com/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 legacy v2 `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, commercial package 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 ```json theme={null} { "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.apostra.com/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` (Apostra-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. ## Commercial package 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. The field name is retained for API compatibility; a newly issued Offer selects one exact Rate Card revision and complete plan rather than a generic Enterprise template. `enterpriseContracts.packages` adds a lifecycle projection for every accepted commercial-package record, including its purchased product rights. Ordinary public IU plan records remain in `commercialState.history` and are not mislabelled as custom commercial packages: | `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 commercial package 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 commercial package 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` | Apostra 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 — Apostra 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 Offer needs its governing agreement reviewed before plan selection. Open the `open_iu_plan_task` Task. | | `SELECT_IU_PLAN` | An exact Rate Card revision and plan are ready for the organization to review and select. Open the `open_iu_plan_task` Task. | | `CONTACT_SCOPE3` | The accepted payment option needs an operator-assisted authority that the enabled self-serve rails cannot establish. Follow `docsUrl` to contact Apostra; no unreachable route is returned. | | `ADD_BILLING_INFO` | No billing contact/address is on file. Resolve with [Update billing info](/v2/buyer/billing/tasks/update-billing-info). | | `ADD_PAYMENT_METHOD` | The account still needs a verified card before eligible platform and IU charges can be collected. Resolve with the returned payment-setup route. | | `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 Apostra 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 Apostra. | | `RESOLVE_HOLD` | A card payment remains unresolved. The current alpha records the hold but does not enforce it as a spend or entitlement gate. | | `UPDATE_PAYMENT_METHOD` | The verified card is approaching expiry. Replace it through the returned payment-setup route. | | `NONE` | Nothing outstanding — the account is in good standing. | Only one `nextAction` is ever returned — the single most important thing to do. Setup priority is Terms of Service, governing-agreement acceptance or IU plan selection for eligible organizations, billing information, and payment method. Funding and standing recovery follow those prerequisites. An organization that is not eligible for an IU plan skips the plan prerequisite. `permissions` tells you whether the authenticated caller can act on the result directly, or should route it to an account admin. The compact Plan & Billing app renders this same server-owned value without reordering it. ## 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](/v2/reference/errors) for the full error contract. ## Related The payer identity on its own, without the rest of the account How invoicing and remittance work