> ## 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.

# Billing: plan and invoices

> Read an organization's plan, the offer it can accept, its renewal and its recent invoices with get kind billing.

`get` with `{ "kind": "billing" }` returns one organization's billing in a
single read: its Terms, payment status, payment terms, standing, balance, IU usage, payout
setup, plan, the offer it can accept, its renewal, its recent invoices and the
next thing to do. It takes no ID or filter. It takes an `include` for the
detail a bare read leaves out: `mediaBilling`, `usageDetail`, `pricing`,
`contracts`, `accounts`, `paymentMethods`, `invoiceHistory` and `payouts`. It
always reads the organization of the selected account, so check
`object.organization.customerId` before you act on it.

The read changes nothing. It is available to Buyer, Seller and Organization
accounts. When an account's organization manages billing for it, a member who
is not an administrator of that organization gets the `billing_managed` answer
described in [Response variants](https://docs.apostra.com/v3/response-variants.md), and so does the
account's own service token, organization API key or machine-to-machine
application when it is not scoped to an advertiser. Only the organization's
administrators read its billing.

## Open Plan & Billing in Claude, ChatGPT or Murph

To see or change billing in a person's own host, ask the agent to open Plan &
Billing. The agent calls `open_plan_and_billing`, which shows the
[Plan & Billing Page](https://docs.apostra.com/v3/plan-and-billing.md): the plan, Terms, payment terms,
payment method, payer and payout details, invoices, and the requests waiting for
an administrator. The call takes no input and changes nothing.

It is available to Seller, Buyer and Organization accounts. A Developer account
has no plan of its own, so it reviews plans in its organization account. Claude
and Murph show the Page straight away. ChatGPT shows it once OpenAI's scan
approves the tool. To answer one question without the Page, read `get` with
`kind: "billing"`.

## What the read returns

Both response channels carry the same facts. The structured result is the
complete object. The text result starts with a short summary of the next action,
the plan, the offer version, the renewal and the invoices, followed by the
rest of the object, so a host that shows only text can still choose its next
call.

| Field | Meaning |
| - | - |
| `organization.customerId`, `organization.name` | The organization this read describes. |
| `organization.displayName` | The organization's company name, else its account name, else `null`. Use it to say whose plan a result describes. |
| `organization.roles` | The roles the organization's billing covers, `BUYER`, `SELLER` or both, or an empty list when none is set. They are the organization's own role together with the roles of its child accounts, so a parent whose sellers all sit in child accounts lists `SELLER`. Choose which sections to show from the roles. |
| `organization.currency` | The currency of the organization's ledger, which `balance` and every amount that names no currency of its own are in. |
| `terms`, `paymentAuthority` | Current Terms and payment status, as described in [Check and complete Terms setup in text-only chat](https://docs.apostra.com/v3/tool-reference.md#check-and-complete-terms-setup-in-text-only-chat). |
| `paymentTerms`, `paymentTermsChosen` | The payment terms sellers are asked for on the organization's behalf: `net_15`, `net_30`, `net_45`, `net_60` or `net_90`. It is the choice an administrator approved for `save_billing` with `paymentTerms`, or `net_60` when none has been chosen, and `paymentTermsChosen` is `false` in that case. A choice that still waits for approval is not shown here. Read it after an approval to check what was recorded. An account whose organization manages billing for it gets the `billing_managed` answer, which carries neither field. |
| `payer` | The payer details printed on the organization's invoices, and whether they are complete. See [`payer`](https://docs.apostra.com/v3/billing-plan-and-invoices#payer) below. An account whose organization manages billing for it gets the `billing_managed` answer, which carries no `payer`. |
| `setupProgress` | Where the organization is in the four setup steps while `nextAction` is a setup action, or `null` when it is not mid-setup. See [`setupProgress`](https://docs.apostra.com/v3/billing-plan-and-invoices#setupprogress) below. |
| `usageDetail` | Only when you ask for `include: ["usageDetail"]`: the IU cycle, buckets, allowance, overage, forecast and usage by activity and day. See [Usage detail](https://docs.apostra.com/v3/billing-plan-and-invoices.md#usage-detail) below. |
| `contracts` | Only when you ask for `include: ["contracts"]`: the agreements, their documents by id and title, and the plan history. See [Contracts](https://docs.apostra.com/v3/billing-plan-and-invoices.md#contracts) below. |
| `accounts`, `accountsTotal` | Only when you ask for `include: ["accounts"]`: the child accounts with their billing delegation and IU usage. A direct administrator only. See [Accounts](https://docs.apostra.com/v3/billing-plan-and-invoices.md#accounts) below. |
| `paymentMethods` | Only when you ask for `include: ["paymentMethods"]`: the saved cards, as a summary. A direct administrator only. See [Saved cards](https://docs.apostra.com/v3/billing-plan-and-invoices.md#saved-cards) below. |
| `invoiceHistory` | Only when you ask for `include: ["invoiceHistory"]`: every fee invoice with its credit notes. See [Invoice history](https://docs.apostra.com/v3/billing-plan-and-invoices.md#invoice-history) below. |
| `pricing` | Only when you ask for `include: ["pricing"]`: the platform fee rates in force and where they come from. See [Platform fee rates](https://docs.apostra.com/v3/billing-plan-and-invoices.md#platform-fee-rates) below. |
| `mediaBilling` | Only when you ask for `include: ["mediaBilling"]`: who is invoiced for the organization's media. See [Media billing entities](https://docs.apostra.com/v3/billing-plan-and-invoices.md#media-billing-entities) below. |
| `payouts` | Only when you ask for `include: ["payouts"]`: how a Seller is paid out, with the bank account numbers and identifiers cut to their last four characters. See [Payouts](https://docs.apostra.com/v3/billing-plan-and-invoices.md#payouts) below. |
| `pendingApprovals` | Your own payment terms, renewal, card setup and payout details requests that still wait for an administrator to approve them on Apostra, newest first, or an empty list. See [`pendingApprovals`](https://docs.apostra.com/v3/billing-plan-and-invoices#pendingapprovals) below. It is not part of the `billing_managed` answer. |
| `standing`, `balance`, `usage` | Whether the organization prepays or pays on terms, any holds, what it can spend, and its IU use this period. See below. |
| `payout`, `permissions` | Whether payout setup is owed, and what the signed-in person may do. See below. |
| `plan` | The plan section. See below. |
| `invoices`, `invoicesTruncated` | The most recent invoices and whether older ones exist. See below. |
| `nextAction` | The one action to take next: `type`, `severity`, `message`, `docsUrl` (the [Plan & Billing](https://docs.apostra.com/v3/plan-and-billing.md) page) and `canCompleteInChat`. |

### Payment terms a seller refused

When a seller's agent refuses an account request because it does not accept
your payment terms (`PAYMENT_TERMS_NOT_SUPPORTED`), nothing is sent to it
again until something changes. Once an administrator approves different
`paymentTerms` for `save_billing`, every request a seller refused over the terms
you replaced is sent once more, with the new terms. Choosing the terms you already have sends
nothing, and a request refused under the new terms waits for your next change
or for the seller to accept them. We never send terms other than the ones you
chose. A refusal over anything other than your payment terms, such as a seller
that has not enabled agent billing, is for the seller to fix, and changing your
terms does not resend it.

### `nextAction`

`nextAction.type` names the next step in a fixed order: accept Terms, accept the
governing agreement, choose a plan, add billing details, then set up payment.
`SELECT_IU_PLAN` means the organization has no plan and an offer is waiting.
`ADD_BILLING_INFO` means the payer name and address are missing; see
[Add billing details](https://docs.apostra.com/v3/plan-and-billing.md#add-billing-details) for where to enter them.
`ACCEPT_GOVERNING_AGREEMENT` means the agreement behind the offer must be
accepted first. `ADD_PAYMENT_METHOD`, `FUND_PREPAY` and `CONTACT_SCOPE3` name
how the chosen plan gets paid for. `NONE` means nothing is owed.

`nextAction.severity` is `success` when the type is `NONE` and `warning` for
every other type. Read it instead of deciding urgency yourself.

`nextAction.canCompleteInChat` is `true` only when the next action is accepting
Terms and the signed-in person can do it from this session.

### `standing`, `balance` and `usage`

| Field | Meaning |
| - | - |
| `standing.posture` | `PREPAY` when the organization must fund a balance to spend, `CREDIT` when it pays on terms. |
| `standing.mediaSpend` | How the organization pays for the media it buys: the same value as `standing.posture` when it buys media, and `null` when it does not (a seller that only sells has no media spend). Show it as Media spend, and show nothing when it is `null`. |
| `standing.holds` | Open holds, each with its `reason` and `createdAt`. It carries no credit limit, because Apostra grants no buyer credit. |
| `balance` | `currency`, `fundedMinor`, `owedMinor` and `availableMinor`, in minor units. |
| `balance.showsAvailable` | `true` only for an organization that prepays and holds funded money. Show `availableMinor` as an available balance only when it is `true`. |
| `usage.usedIus` | IUs used this period on the organization's IU account, or `null` when it has none. |
| `usage.activityIus` | IUs rated for the organization's activity, or `null`. |

### `setupProgress`

`setupProgress` says how far the organization has got through the four setup
steps, decided on the server from the same facts as `nextAction`, so the two
never disagree. It is `null` once `nextAction` is not a setup action.

| Field | Meaning |
| - | - |
| `steps` | Exactly four steps, always in this order: `ACCEPT_TOS`, `SELECT_PLAN`, `ADD_BILLING_INFO`, `ADD_PAYMENT_METHOD`. Each has an `id` and a `state` of `done`, `active` or `todo`. |
| `activeStep` | The one-based position in `steps` of the step the organization is on now. |

### `payout` and `permissions`

| Field | Meaning |
| - | - |
| `payout.setupRequired` | `true` when this Seller is paid out through Apostra and must provide payout details. |
| `payout.onboardingStatus` | `pending` or `complete`, or `null` when there is no storefront billing. |
| `payout.manageUrl` | Only when you ask for `include: ["payouts"]` and `permissions.canSetPayout` is `true`: the link to the web Payouts page, where an administrator adds or changes a payee. Absent otherwise. See [Payouts](https://docs.apostra.com/v3/billing-plan-and-invoices.md#payouts). |
| `permissions.canEditBillingInfo` | Whether the signed-in person may edit billing details. |
| `permissions.canSetPayout` | Whether the signed-in person may set payout details. |
| `permissions.supportSessionLimit` | Present when an Apostra staff support session reads this, which sees everything an administrator sees: `read_only` when it changes nothing, `no_plan_changes` when it keeps the write access it has but never changes a plan. See [Plan & Billing](https://docs.apostra.com/v3/plan-and-billing.md#support-sessions). |

`payout` says whether setup is owed, and carries the link to the web Payouts
page when you ask for `payouts` and may change them. Ask for
[`payouts`](https://docs.apostra.com/v3/billing-plan-and-invoices#payouts) to read the payees and their
masked bank details. Payout details are typed on that web page, never in chat or
in the Plan & Billing Page; see
[Change where a Seller is paid](https://docs.apostra.com/v3/billing-plan-and-invoices.md#change-where-a-seller-is-paid).
Whether the signed-in person may accept Terms stays in `terms.canAccept`.

### `payer`

`payer` holds the name, invoice emails, address and tax ID we print on the
organization's invoices. It uses the names and meaning of the billing profile in
the v2 API. Nothing here is a card or bank detail.

| Field | Meaning |
| - | - |
| `contactName` | The payer name, or `null`. |
| `email`, `ccEmails` | The addresses invoices are sent to, and the addresses copied on them. An empty list means none. |
| `phone` | The billing phone number, or `null`. |
| `address`, `address2`, `city`, `region`, `postalCode` | The billing address, or `null` for any part that is not set. |
| `countryAlpha2` | The billing country as an ISO 3166-1 alpha-2 code such as `GB`, or `null`. |
| `taxId` | The tax or VAT identifier shown on invoices, or `null`. |
| `complete` | `true` when we have what an invoice needs: a payer name, a street address and a country. It is the same rule buyer readiness uses for its `BILLING_DETAILS` gap, so the two never disagree. |
| `missing` | The fields an invoice still needs, from `contactName`, `address` and `countryAlpha2`, in that order. It is empty when `complete` is `true`. It comes from the same rule as `complete`, so the two never disagree. Use it to tell the person exactly what to add, for example "an invoice still needs a street address and country". |
| `visibility`, `redactedFields` | `visible` with an empty list for a signed-in person. For an organization-scoped service token, `visibility` is `redacted` and `redactedFields` names the fields we hold back: those fields are `null` and the email lists are empty, so you can tell "not allowed to read" from "empty". `complete` and `missing` are still worked out from the stored details, so a held-back address does not read as missing. |

A failure to read the payer details fails the whole read. The text result
starts its summary with whether the details are complete and, when they are not,
how to add them.

### `pendingApprovals`

A payment terms choice, a renewal change, a card setup, a card removal, a pay
now or a payout details change is recorded for an administrator to approve on Apostra,
and nothing changes until they do. If you lose track of one
(a Page was rebuilt, a conversation moved on), the billing read lists it. Each
entry is a request you made yourself and that can still be decided: waiting
before its deadline, or approved and being completed. Another person's request is
never listed, a request that was approved, declined or expired is not listed,
and a service token, which has no person behind it, sees an empty list.

| Field | Meaning |
| - | - |
| `kind` | `billing.payment_terms`, `billing.renewal`, `billing.payment_method_setup`, `billing.payment_method_remove`, `billing.pay_now` or `billing.payout_details`. |
| `paymentTerms` | For `billing.payment_terms`: the terms that were asked for. |
| `action`, `renewalVersion`, `reason` | For `billing.renewal`: the change that was asked for, the renewal version it was made against, and the reason given. Send the `reason` unchanged to read the approval by its key. |
| `paymentMethodId` | For `billing.payment_method_remove`: the id of the saved card that was asked to be removed. |
| `url` | The Apostra page where a signed-in direct administrator approves or declines it. Show it to the person. |
| `idempotencyKey` | The key the request is recorded under. Call `save_billing` again with the same input and this key to read the approval in any state (waiting, approved, declined, expired or failed); the call never records a new request. For a card setup, call `request_payment_authority` with this key instead. |
| `expiresAt` | When the request expires if nobody decides it. |

A `billing.payment_method_setup` entry carries only `kind`, `url`, `idempotencyKey` and `expiresAt`. A card setup asks for no choice, so there is nothing to repeat with the key. A `billing.pay_now` entry carries the same four fields: it names no choice beyond the organization. Call `save_billing` with `paymentMethod` or `payNow` and the entry's `idempotencyKey` to read a card removal or a pay now.

A `billing.payout_details` entry carries only `kind`, `url`, `idempotencyKey` and `expiresAt` too, for a different reason: payout details are bank data, so the read never repeats a name, an account number or an identifier. A caller that still holds the details it sent can repeat that same write with this key to read the approval.

### `plan`

| Field | Meaning |
| - | - |
| `plan.current` | The plan in force, or `null`. |
| `plan.upcoming` | An accepted plan that starts when the current term ends, or `null`. |
| `plan.offer` | The offer the organization can accept, at its exact version, or `null` when none applies. |
| `plan.renewal` | The renewal at its exact version, or `null`. |
| `plan.charges` | How the plan in force charges the organization, or `null` when the plan has no published description of it. `card_monthly_usage` is the Standard plan: the card on file is charged once a month for the IUs used. Show it as Plan charges, and show no row when it is `null`. |
| `plan.helpAvailable` | Whether a plan help request can be filed now. |
| `plan.showsChoices` | `true` while the organization is being asked to choose a plan, with no accepted successor and no ended plan awaiting renewal review. Show the plan choices only when it is `true`. |
| `plan.setupGrant` | The Storefront setup credit the organization holds (`grantedIus`, `grantedAt`, `expiresAt`, `status`, `attributionKind`), or `null`. Always `null` for an organization with no Storefront. The current plans carry no setup credit, so accepting one grants none; an organization that already holds a credit keeps it until it expires. |
| `plan.passThroughAvailable` | `true` when the organization may continue on Listing with a third-party sales agent and no plan. |
| `plan.eligible`, `plan.eligibleWorkloads` | Whether the organization may choose a plan now, and for which workloads: any of `BUYER`, `STOREFRONT`, `PARTNER` and `DEVELOPER`. The list is empty when `eligible` is `false`. |
| `plan.suggestedPlan` | The plan the chooser suggests to an organization with no plan in force, or `null`. It is only a suggestion: the organization is not on it and nothing is billed under it until it accepts a plan. It carries the plan terms as `plan.current` does (`planId`, `planName`, `currency`, `commitmentMinor`, `includedIus`, `iuPriceMinor`, `entitlements`) and `scopeIncluded`, what the plan covers. |
| `plan.calibratingActivities` | The activities whose IU price is still being set or measured, or an empty list when every activity is priced. Each has `activityCode`, `status` (`CALIBRATING` or `MEASURING`), `iuAmountMilli` (the standard price in thousandths of an IU while `CALIBRATING`, `null` while `MEASURING`), `unitCount` and `unit`. |

`plan.current` and `plan.upcoming` carry the same fields:

| Field | Meaning |
| - | - |
| `planId`, `planName` | The plan's stable plan code and its name. `planId` is the code. The read carries no internal plan row IDs. |
| `currency`, `commitmentMinor`, `includedIus`, `iuPriceMinor` | Net monthly commitment, included IUs and the net price of an IU beyond them. Money is in minor units of `currency`. |
| `entitlements` | `bundleName`, the `features` the plan grants, `accountLimit` and the `capacities` it grants (each a `target`, a `unit` and a `limitCount`), or `null` when the plan grants none. |
| `listCommitmentMinor`, `listIuPriceMinor`, `discountBasisPoints` | The commitment and the IU price before any discount, and the discount already applied to the net figures, in basis points. |
| `governedBy` | What the plan sits under, the same block as `plan.offer.governedBy`: the agreement, the rate card and the proposal. |
| `scopeIncluded` | What the plan covers, as short statements, when the offer in the read is of the rate card revision the plan was accepted on. Empty otherwise, so an accepted plan never shows newer text than it was accepted with. |
| `supportPackage` | The named support the plan includes (`kind`, `displayName`, `includedHoursPerMonth`, which is `null` for unlimited named support, and `additionalHourIus`, the IU price of a further hour for a package accepted before support became part of the plan), or `null`. |
| `lifecycle` | Where the plan stands: `PENDING_FUNDING` until payment authority exists, `SCHEDULED` before the term starts, `ACTIVE` in force, `BILLING_HOLD` while a payment hold limits spend, `SUSPENDED` while the contract is not in force, `EXPIRED`, `SUPERSEDED`, or `PAID` for a paid plan with no contract package. `null` when none applies. |
| `offerVersion` | The version of the offer the plan was accepted from. |
| `termStart`, `termEnd`, `acceptedAt` | The term and when it was accepted. |
| `paymentOption` | The payment option chosen at acceptance, or `null`. |
| `custom` | `true` for a private contract rather than a public catalog plan. |

`plan.offer` carries:

| Field | Meaning |
| - | - |
| `offerVersion` | The exact version of the offer. Anything that accepts or answers the offer names this version, and a stale version is refused. |
| `governedBy.agreementKind` | `STANDARD_TOS`, `CUSTOM_CONTRACT` or `AAA`: the agreement the offer sits under. |
| `governedBy.effectiveRateCard` | The rate card behind the offer: `version`, `visibility`, `displayName`, `adjustmentSource` (`default`, `discount`, `direct`, `promo` or `referral`: where its prices come from) and `priceAdjustment` (`PERCENT`, `PACKAGE` or `null`), or `null`. |
| `governedBy.termsUrl` | The address of the Terms of Service that govern it, for the standard Terms, or `null` for a custom contract. |
| `governedBy.proposal` | The private proposal behind the offer: `documentTitle`, `executiveSummary`, the scope it includes and excludes, `initialTermMonths`, `renewal` (`NO_AUTOMATIC_RENEWAL`, or `AUTOMATIC` with `renewalTermMonths` and `nonRenewalNoticeDays`), `customization` (`EXACT`, or `CUSTOMIZED` with its `reason`; `null` for a proposal issued before it was recorded) and `defaultPaymentOptionKey`. `null` for a public offer. |
| `serviceStart` | When service under the offer starts: `ON_ACCEPTANCE`, or an object with `kind: "FIXED_DATE"` and a `date`. |
| `initialTermMonths` | The length of the first term. |
| `lastResponse` | How the organization last answered this exact version of the offer (`outcome` of `ACCEPTED`, `DECLINED` or `DEFERRED`, and `at`), or `null`. `DEFERRED` is "decide later": the sign-in prompt stays quiet for this version. A new version of the offer starts again with `null`. |
| `discount` | The corporate discount that applies (`basisPoints`, `effectiveDate`, `endDate`), or `null`. |
| `activitySchedule` | What each priced activity costs under the offer, keyed by `activityCode`. The order is for presentation only. |
| `plans` | The plans on offer, in catalog order. Each has `planId`, `planName`, `currency`, `commitmentMinor`, `includedIus`, `iuPriceMinor`, `listCommitmentMinor`, `listIuPriceMinor`, `discountBasisPoints`, `rolloverPolicy` (`capBasisPoints` and `expiresAfterBillingPeriods`, or `null` when the plan does not roll over), `scopeIncluded` (what the plan covers, as short statements; empty when its rate card revision lists none), `activitySchedule`, `entitlements`, `displayOrder`, `paymentOptions` and `acceptanceConvertsStandaloneAccount`. The list figures are before any discount and `commitmentMinor` and `iuPriceMinor` are net of it. A plan's own `activitySchedule` is `null` when the offer's applies. |

`paymentOptions` lists the options a private proposal lets the organization
choose from: `optionKey`, `kind` (`MONTHLY` or `TERM_PREPAY`), `displayName`,
`currency`, `amountMinor`, `termMonths`, `paymentTermsDays` and
`collectionMethods`. For `MONTHLY`, `amountMinor` is the monthly amount; for
`TERM_PREPAY`, it is the whole prepaid amount. A public plan has no options to
choose from, so the list is empty. `acceptanceConvertsStandaloneAccount` is
`true` when accepting that plan first turns a standalone account into an
organization.

`plan.renewal` carries:

| Field | Meaning |
| - | - |
| `version` | The exact version of the renewal. |
| `status` | `RENEWS`, `NON_RENEWAL_SCHEDULED`, `RENEWAL_BLOCKED`, `ENDED` or `PINNED`. |
| `effectiveFreeAt` | When the organization is free of the plan if it does not renew. |
| `changeAllowedUntil` | The deadline for changing the renewal. |
| `allowedActions` | What the server permits now: `CANCEL_AT_TERM`, `REINSTATE_AUTO_RENEWAL`, both or neither. Change the renewal as described in [Change the renewal](https://docs.apostra.com/v3/billing-plan-and-invoices.md#change-the-renewal). |
| `latestInstruction` | The latest renewal change (`instructionType`, `effectiveAt`, `recordedAt`), or `null`. |

### `invoices`

`invoices` lists at most 10 invoices, newest first. `invoicesTruncated` is
`true` when the organization has older ones.

| Field | Meaning |
| - | - |
| `number`, `reference` | The invoice number and its display reference, such as `FEE-000042`. |
| `periodStart`, `periodEnd` | The billing period the invoice covers. A billing period is a UTC calendar month. Until 1 November 2026, an organization that was billed on cycles starting on its acceptance day keeps those cycles, and the last one ends on 1 November 2026; an invoice for such a cycle keeps the dates it was issued with. |
| `amountMinor`, `currency` | The amount invoiced, in minor units. |
| `balanceMinor` | What is still owed, in minor units. `0` once settled. |
| `status` | `paid`, `overdue` (unpaid and past its due date) or `open`. |
| `dueAt` | When payment is due. |

## Usage detail

Add `include: ["usageDetail"]` to read the IU cycle in detail. A bare read
carries only `usage.usedIus` and `usage.activityIus`.

```json theme={null}
{ "kind": "billing", "include": ["usageDetail"] }
```

The result carries `usageDetail` beside `object`. It comes from the same IU
account that Plan & Billing shows, so the two agree. The plan key, the monthly
commitment and the IU price are not repeated here: they stay on `plan.current`.

| Field | Meaning |
| - | - |
| `usageDetail.iu` | The IU account for the current cycle, or `null` when it cannot be read or the organization has none. |
| `usageDetail.iu.currency` | The currency of the `overage` amounts, in minor units. |
| `usageDetail.iu.cycle` | The cycle's `start` and `end`. |
| `usageDetail.iu.buckets` | The `free`, `rollover` and `included` buckets, each with `granted`, `used` and `remaining` IUs. A bucket the plan and grants do not carry has `granted` of `0`. |
| `usageDetail.iu.allowance` | The cycle's allowance across every bucket, so you never have to add them up: `granted` is what the plan and grants carry, `used` is what has been drawn from them (never more than `granted`), and `remaining` is what is left. Usage beyond the allowance is `overage`, so `allowance.used` plus `overage.ius` is the `usedIus` on the bare read. |
| `usageDetail.iu.overage` | `ius` consumed beyond every bucket, the `amountMinor` so far this cycle, the `capMinor` on overage that has not been charged yet, `warnAtMinor`, and whether the organization is over either: `overWarnThreshold` and `overCap`. |
| `usageDetail.iu.rolloverPolicy` | `capBasisPoints` and `expiresAfterBillingPeriods`, or `null` when the plan does not roll over. |
| `usageDetail.iu.forecast` | `projectedIus`, a straight-line projection of the cycle's total, and `projectedOverageMinor`. |
| `usageDetail.activity` | IUs used this period, or `null` when the IU experience is unavailable: `periodStart`, `periodEnd`, `totalIus`, `byActivity` (each `activityCode`, `displayName` and `ius`) and `byDay` (each UTC `date` and `ius`). |

## Platform fee rates

Add `include: ["pricing"]` to read the platform fee rates in force for the
organization.

```json theme={null}
{ "kind": "billing", "include": ["pricing"] }
```

| Field | Meaning |
| - | - |
| `pricing.source` | `standard` for the published rates, `custom` for rates agreed in a contract, `inherited` for the organization's rates shown on one of its accounts, or `null` when no rate card is in force. |
| `pricing.rates[]` | One rate for each combination in force. `customerRole` is `BUYER` or `SELLER`, `billingType` is `DECISIONED` or `ROUTED`, and `pricingType` is `MARGIN` or `UNIT`. A `MARGIN` rate carries `feeRatePercent`; a `UNIT` rate carries `unitPrice`, `unit` (`CPM`, `RECORD` or `FLAT_RATE`) and `currency`. The fields that do not apply are `null`. |

## Contracts

Add `include: ["contracts"]` to read the agreements the organization has
accepted, their documents and its plan history.

```json theme={null}
{ "kind": "billing", "include": ["contracts"] }
```

| Field | Meaning |
| - | - |
| `contracts.agreements[]` | Each agreement: `kind` (`STANDARD_TOS`, `CUSTOM_CONTRACT` or `AAA`), `status`, `effectiveDate`, `endDate`, `acceptedAt` and `acceptedByEmail`. |
| `contracts.documents[]` | The agreement documents, each with an `id` (`agreement-<id>` for an agreement, `supporting-<id>` for a supporting document) and a `title`. The read carries no link to a document: a signed-in person opens it on Apostra, and an agent can say that it exists. |
| `contracts.planHistory[]` | Every plan the organization has accepted, the plan in force and the upcoming plan included. Each has `status` (`CURRENT` for the plan in force, `UPCOMING` for the accepted plan waiting for the current term to end, `PAST` for a plan whose term has ended), `planId`, `planName`, `currency`, `commitmentMinor`, `includedIus`, `iuPriceMinor`, `listCommitmentMinor`, `listIuPriceMinor`, `discountBasisPoints`, `supportPackage`, `lifecycle` (as on `plan.current`; it is `lifecycle`, not `status`, because `status` says which entry this is), `termStart`, `termEnd`, `rateCardVersion`, `acceptedAt`, `acceptanceSource` (`SIGNUP`, `PLAN_BILLING`, `MCP_APP`, `ADMIN_ORDER_FORM` or `AUTO_RENEWAL`) and `activityTerms`, what each priced activity cost under the plan, keyed by `activityCode`. The plan in force keeps the rate card version and activity terms it was accepted under, so they stay right after the Rate Card is revised; `plan.current` carries neither. |
| `contracts.renewalHistory[]` | Every renewal change recorded for the plan in force: `instructionType`, `effectiveAt` and `recordedAt`. It carries no reason and no actor. |
| `contracts.visibility`, `contracts.redactedFields` | `visible` with an empty list for a signed-in person. An organization-scoped service token gets `redacted`: `acceptedByEmail` is `null` in every agreement and named here, because it is personal data. |

## Accounts

Add `include: ["accounts"]` to read the organization's child accounts. Only a
direct administrator of the organization can read it; any other caller gets it
in `unavailableIncludes` with the reason.

| Field | Meaning |
| - | - |
| `accounts[]` | At most 50 child accounts, each with `id`, `name`, `company`, `delegation` and `iuUsage`. `delegation` is `NONE`, `VIEW` or `OWN`, and is always `NONE` today. `iuUsage` has `quantity`, `periodStart` and `periodEnd` for the organization's billing cycle. `0` means the account had no rated activity, and `null` means the IU experience or accepted rating terms are unavailable. |
| `accountsTotal` | How many child accounts the organization has, whatever `accounts` lists. |

## Saved cards

Add `include: ["paymentMethods"]` to read the organization's saved cards. Only
a direct administrator of the organization can read it; any other caller gets it
in `unavailableIncludes` with the reason.

| Field | Meaning |
| - | - |
| `paymentMethods.cards[]` | Each saved card: `id`, `brand`, `last4`, `expiresMonth`, `expiresYear` and `status` (`pending_verification` or `verified`). A removed card is not listed. |
| `paymentMethods.cardCollectionEnabled` | Whether the organization can add a card now. It is `true` wherever the card rail is set up, whether or not the organization already holds a card. |

This is a summary, the kind a payment provider shows anyone who can see the
account. It never carries a card number, a security code, a processor ID or a
setup token.

## Invoice history

Add `include: ["invoiceHistory"]` to read every fee invoice. The bare `invoices`
list is unchanged: it holds the 10 newest.

| Field | Meaning |
| - | - |
| `invoiceHistory.invoices[]` | At most 120 invoices, newest first. Each has the fields of [`invoices`](https://docs.apostra.com/v3/billing-plan-and-invoices#invoices), `creditNotes` (at most 20 for one invoice, each with `reference`, `amountMinor`, `currency`, `reason` and `issuedAt`) and `creditNotesTruncated`, which is `true` when the invoice has more credit notes than the 20 listed. |
| `invoiceHistory.truncated` | `true` when the organization has older invoices than the 120 listed. |

Naming an include more than once reads it once. If the saved cards or the
invoice history cannot be read right now, the read still answers. It leaves the include out and lists it in `unavailableIncludes`.

## Payouts

Payouts say how a Seller is paid: the bank account for each legal entity and
currency, and whether the account's payout details are its own or its
organization's. Read them by adding `include: ["payouts"]` to the billing read.
A bare billing read does not carry them and is unchanged.

```json theme={null}
{ "kind": "billing", "include": ["payouts"] }
```

The result carries `payouts` beside `object`:

| Field | Meaning |
| - | - |
| `payouts.payees[]` | Every payee of the account, one for each legal entity and currency: `entityName`, `currency` (ISO 4217), `isPrimary`, `beneficiaryName`, the address (`addressLine1`, `addressLine2`, `city`, `region`, `postalCode` and `countryCode`), `accountNumberLast4`, `bankIdentifierType` (`FEDWIRE_ABA`, `CHIPS_ABA`, `SWIFT_BIC` or `BANK_CODE`), `bankIdentifierLast4`, `completedAt`, `createdAt` and `updatedAt`. |
| `payouts.payoutDetails` | The default payout details: the primary payee, or for an account with no payee, its older single payout-details row. It has the payee's bank and address fields, without `entityName`, `currency`, `isPrimary`, `createdAt` or `updatedAt`. `null` when no details are on file. |
| `payouts.inherited` | `true` when the account has no payout details of its own and shows its organization's. |
| `payout.manageUrl` | Inside `object`, beside `payout.setupRequired`. The link to the web Payouts page, where an administrator adds or changes a payee: a plain absolute address on Apostra's own site. It is there only when you ask for `payouts` and `permissions.canSetPayout` is `true`, and absent (not `null`) otherwise, so a person who cannot change payouts is not sent to a page that would turn them away. It carries no token, secret or bank detail, and opening it changes nothing: the page checks the signed-in person before it saves. |
| `payouts.accounts[]` | An organization only: one row for each active Seller account under it. A row has `accountId`, `name`, `company`, `inherited`, `onboardingStatus` (`pending`, `complete` or `restricted`, or `null` when the account has no payout record) and, when `inherited` is `false`, the account's own `payees`, in the same shape and with the same masking. A row for an account that inherits has no `payees`: it has none of its own, and the organization's are in `payouts.payees`. |

Two values are cut to their last four characters: the account number or IBAN,
and the bank identifier (a routing number, a CHIPS number, a SWIFT-BIC or a local
bank code). The full values are never returned, by this read or by any other.
`bankIdentifierLast4` is an empty string when the identifier has four
characters or fewer, because its last four would be the whole value. Nothing
else is masked: the beneficiary name, the address and the bank identifier type
come back as stored.

The billing read still answers when payouts cannot be read. It leaves
`payouts` out and lists it in `unavailableIncludes` with the reason when:

* the organization has not accepted the Terms. Payouts are read only after
  Terms; `terms` in the same read says what is owed.
* the account is a Buyer account, or an organization with no Seller account.
  Payouts exist only for Sellers.
* the payouts could not be read right now.

A Seller account reads its own payouts, and an account whose organization
manages billing reads the organization's, with `inherited` set to `true`. An
agent cannot change a payee or payout details. Bank details are typed on the web
Payouts page, because a bank account number is a secret that does not pass
through chat. Give the person `payout.manageUrl` to open it; see
[Change where a Seller is paid](https://docs.apostra.com/v3/billing-plan-and-invoices.md#change-where-a-seller-is-paid).
`permissions.canSetPayout` says whether the signed-in person may do it.

### The Payouts tab on the web

The **Payouts** tab of Plan & Billing on the web shows these same facts: the
payees, whether the account's details are its own or its organization's, and, for
an organization, each Seller account's payout status. It reads them with this
read, so it shows a bank account number and a bank identifier cut to their last
four characters, the same as an agent sees.

Adding or editing a payee is a step on that tab, in your own browser session. It
is not an API operation: an API key, a service token or an MCP bearer cannot do
it, and no tool does. A signed-in administrator of the billing organization
saves the payee on the call, for the organization itself or for a Seller account
under it. An account that its organization manages cannot change its own
payouts; the organization does.

Because a read returns only the last four characters of the bank identifier,
editing a payee asks for the full bank identifier again. The account number is
asked again only if you replace it; otherwise the stored number stays.

## Media billing entities

Media billing says who is invoiced for the organization's media. A media
billing entity is a legal name, a country, the currency it is invoiced in,
invoice emails, an address and a tax ID. An entity attaches to one advertiser or
one account. The organization's primary entity catches every advertiser and
account with no entity of its own. Today the entities record that choice: the
invoice we issue does not use them yet.

Read them by adding `include: ["mediaBilling"]` to the billing read. A bare
billing read does not carry them.

```json theme={null}
{ "kind": "billing", "include": ["mediaBilling"] }
```

The result carries `mediaBilling` beside `object`:

| Field | Meaning |
| - | - |
| `mediaBilling.entities[]` | The organization's entities, each an AdCP `BusinessEntity` with three fields of ours. `legal_name` is the legal name and `tax_id` the tax ID as entered. `address` holds `street` (the two address lines joined with a comma), `city`, `postal_code`, `region` and `country`, the ISO 3166-1 alpha-2 code. `contacts` holds one `billing` contact for each invoice email. A contact carries only `role` and `email`. We add `id`, `currency` (an ISO 4217 code) and `isPrimary`, which is `true` for the one primary entity. Bank details are never returned. |
| `mediaBilling.attachments[]` | Which advertiser or account an entity is attached to: `id`, `entityId`, and either `advertiserId` or `accountId`. |
| `mediaBilling.visibility`, `mediaBilling.redactedFields` | `visible` with an empty list for a signed-in person. An organization-scoped service token gets `redacted`: `tax_id`, `address` and `contacts` are left out of every entity and named here, so you can tell "not allowed" from "empty". |

The read returns what is stored. It does not check an entity against AdCP's
field limits, which are tighter than ours for some fields (for example, a legal
name of at most 200 characters). The read follows who can read media billing in
Plan & Billing: from the organization's own account, its members; from one of its
accounts, only a direct administrator of the organization. When the caller may
not read it, the billing read still answers. It leaves `mediaBilling` out and
lists it in `unavailableIncludes` with the reason.

Create, change and attach entities with `save_billing`, as
[Change media billing entities](https://docs.apostra.com/v3/billing-plan-and-invoices.md#change-media-billing-entities)
describes, or in the Media billing tab of Plan & Billing on the web.

### Who is invoiced for an advertiser

`get` with `kind: "advertiser"` carries `mediaBilling`, the entity that
resolves for that advertiser, so you do not have to match attachments yourself.

| Field | Meaning |
| - | - |
| `mediaBilling.entityId` | The entity's `id`, as `mediaBilling.entities[]` lists it. |
| `mediaBilling.legal_name`, `mediaBilling.currency` | The entity's legal name and invoice currency. |
| `mediaBilling.source` | Where the entity came from, most specific first. `advertiser`: the advertiser has its own attachment. `account`: its account does, or the account keeps its own primary entity. `organization`: the organization's primary entity catches it. |

`mediaBilling` is `null` when no entity resolves for the advertiser. When the
caller may not read media billing, the field is left out, so absent means "not
allowed" and `null` means "no entity". If the read itself fails, the field is
also left out and `unavailableIncludes` says so; the advertiser is still
returned.

### Who is invoiced for an account

`get` with `kind: "account"` carries `mediaBilling` for the child account in
the same shape, so you do not have to match attachments yourself. `source` is
`account` when the account has an entity attached to it, and `organization`
when the organization's primary entity catches it. It is never `advertiser`.

`mediaBilling` is `null` when no entity resolves for the account. When the
caller may not read media billing, the field is left out, so absent means "not
allowed" and `null` means "no entity". If the read itself fails, the field is
also left out and `unavailableIncludes` says so; the account is still returned.

## Change media billing entities

Media billing entities are the names and addresses we print on a media invoice.
Like the payer details, they move no money and commit the organization to
nothing, so a change saves on the call, with no approval step. Call
`save_billing` with `mediaBilling`, sent alone (not beside `terms`,
`paymentTerms`, `plan`, `offerResponse`, `renewal` or `payer`). Each call makes
one change: send exactly one of `entity`, `removeEntityId`, `attach` or
`detach`.

| Field | Meaning |
| - | - |
| `mediaBilling.entity` | Create an entity, or update one. Without `id` it creates. With `id` it updates that entity, and you send the whole entity: an optional field you leave out (`tax_id`, `address.region`) is cleared, and `isPrimary` left out keeps the entity's primary flag. The fields are the ones the read returns: `legal_name`, `tax_id` (optional), `address` (`street`, `city`, `postal_code`, `country` and an optional `region`), `contacts` (one `{ "role": "billing", "email": "..." }` for each invoice email, at least one) and `currency`, plus an optional `isPrimary`. |
| `mediaBilling.removeEntityId` | Remove the entity with this `id`. It must have no attachments. |
| `mediaBilling.attach` | Attach an entity to one advertiser or one account: `entityId`, and exactly one of `advertiserId` or `accountId` (a child account of the organization). |
| `mediaBilling.detach` | Remove an attachment: `attachmentId`, as `mediaBilling.attachments[]` lists it. |

```json theme={null}
{
  "mediaBilling": {
    "entity": {
      "legal_name": "Acme Media Limited",
      "tax_id": "GB123456789",
      "address": {
        "street": "1 High Street",
        "city": "London",
        "postal_code": "N1 1AA",
        "country": "GB"
      },
      "contacts": [{ "role": "billing", "email": "ap@acme.example" }],
      "currency": "GBP"
    }
  }
}
```

The call returns `action: "media_billing_saved"` with `saved` (the `entityId`
or `attachmentId` the change was made to) and `mediaBilling`, the updated
entities and attachments in the shape the read returns. If the change is saved
but the read after it fails, the answer is still a success: it leaves out
`mediaBilling` and names it in `unavailableIncludes` with the reason, so you do
not repeat a change that already happened. Read it with `get`. `idempotencyKey`
is accepted only with `paymentTerms`, so `mediaBilling` takes none. A repeated
create is refused when an entity with the same name and currency already exists.

AdCP's limits apply to every write, and they are tighter than the web app's form
and the v2 routes: `legal_name` is at most 200 characters, `tax_id` 30,
`address.street` 200, `address.city` 100, `address.postal_code` 20 and
`address.region` 100, with at most 10 contacts. `address.country` is an ISO
3166-1 alpha-2 code, never a country name. `legal_name`, `street`, `city` and
`postal_code` must not be empty, and each `email` must be a valid address. A call
that breaks a limit is refused with the field named, and nothing changes. An
entity saved earlier through the web app over one of these limits still reads as
stored. To change it through `save_billing`, it has to fit. The
address is saved as one street line: `street` is stored as line 1, and line 2 is
cleared. An entity carries no `bank`, `vat_id`, `registration_number` or `ext`,
and a contact carries only `role` and `email`.

These rules hold on every call:

* There is exactly one primary entity while any entity exists. The first entity
  you create is primary. Send `isPrimary: true` to make another one primary, and
  the old primary stops being primary. You cannot demote the primary by sending
  `isPrimary: false`. Make another entity primary instead. Removing the primary
  makes the oldest remaining entity primary.
* An entity with attachments cannot be removed. Detach them first.
* An advertiser or account takes one attachment. Detach it before you attach it
  to another entity.

Who may write follows who may change media billing in Plan & Billing. From the
organization's own account, the caller's role must be administrator. From one of
its child accounts, the caller must be a direct administrator member of the
organization. Service tokens and advertiser-scoped principals are refused from a
child account. Apostra staff acting as a SuperAdmin may write. A caller who may
not write gets `ACCESS_DENIED`, and nothing changes. Each change is recorded in
the audit log with the entity as it was and as it is now.

The Media billing tab in the Apostra web app changes the same entities.

## Change the payer details

Payer details are what we print on the organization's invoices. They move no
money and commit the organization to nothing, so a direct administrator of the
billing organization saves them on the call, from an agent or from the
[Plan & Billing Page](https://docs.apostra.com/v3/plan-and-billing.md), with no approval step. Call
`save_billing` with `payer`, sent alone (not beside `terms`, `paymentTerms`,
`plan`, `offerResponse`, `renewal` or `mediaBilling`):

| Field | Meaning |
| - | - |
| `payer.contactName`, `payer.email`, `payer.ccEmails`, `payer.phone`, `payer.address`, `payer.address2`, `payer.city`, `payer.region`, `payer.postalCode`, `payer.countryAlpha2`, `payer.taxId` | The fields to change, with the validation of the v2 billing profile: `email` and `ccEmails` hold at most 10 valid addresses each and `countryAlpha2` is two upper-case letters. Send only the fields to change. A field you leave out stays as it is, and `null` clears it. Send at least one. |
| `payer.idempotencyKey` | Optional. Accepted so a caller built on the earlier shape keeps working, and ignored: the call sets values, so repeating it changes nothing further. |

```json theme={null}
{
  "payer": {
    "contactName": "Acme Media Limited",
    "address": "1 High Street",
    "city": "London",
    "postalCode": "N1 1AA",
    "countryAlpha2": "GB",
    "phone": null
  }
}
```

The call checks the fields, writes the ones you named to the billing
organization and returns `action: "payer_saved"` with `payer`, the details as
they stand now, in the shape the read returns. `payer.complete` says whether we
now have what an invoice needs, and `payer.missing` names what is still needed. Confirm the details with the person before you
send them.

Only a direct administrator of the billing organization signed in as
themselves may save payer details. An administrator of a parent organization who
is not a direct member, Apostra staff without a direct administrator
membership, service tokens and impersonated or support sessions are
refused with `ACCESS_DENIED`, and nothing changes. A direct administrator of the
organization may work from the organization account or any child account they
administer. Each change is recorded in the audit log with the values before and
after.

The Plan & Billing Page and the Payment & invoices form in the Apostra web app
save payer details the same way.

## Choose the payment terms

The payment terms are what every seller connection of the organization is asked
for. Choosing them binds the organization, so a call from an agent or a Page
does not change them. A direct administrator of the billing organization
approves the choice on Apostra first. Call `save_billing` with `paymentTerms`
and an `idempotencyKey`, sent alone (not beside `terms`, `plan`,
`offerResponse`, `renewal` or `payer`):

| Field | Meaning |
| - | - |
| `paymentTerms` | `net_15`, `net_30`, `net_45`, `net_60` or `net_90`. `net_60` is the default. `null` and `prepay` are refused. |
| `idempotencyKey` | Optional, and accepted only with `paymentTerms`: a stable key you make up for this choice. Repeat it with the same terms to read the outcome. A rejected, expired or failed approval needs a new key. Reusing a key for other terms is refused. Without one, Apostra matches the call to the approval you already have open for the same terms, so a repeated call reads the same approval, and when none is open (it was rejected, expired or failed) the call asks again, as often as you need. The answer names the key it recorded the approval under (`idempotencyKey`), so you can repeat the call with it to read that approval, in any state, without ever asking again. |

```json theme={null}
{
  "paymentTerms": "net_45",
  "idempotencyKey": "payment-terms-net-45-2026-11-09"
}
```

The call writes nothing. It returns `action: "approval_required"` with an
approval `url`, its `state` and when it expires. Show the person the link and
say that nothing changes until an administrator approves. The approval page
shows the terms in force now beside the ones you asked for, and says when none
were ever chosen and the `net_60` default applies. Asking for the terms the
organization has already chosen records nothing and answers
`payment_terms_saved`. Approving sets the terms once
and records the change in the audit log under the administrator who approved it.

Call again with the same `idempotencyKey` to check. If you sent none, use the `idempotencyKey` in the answer: a call with that key reads the approval and never records a new one, while a call with no key can start a new request once the earlier one has ended. While the approval waits, or
when it ended without approval (`rejected`, `expired` or `failed`), the answer is
`approval_required` and its `state` says which. Once it is approved, the answer
is `action: "payment_terms_saved"` with `paymentTerms` and
`paymentTermsChosen: true`. `get` with `kind: "billing"` returns the same terms.

Only a direct administrator of the billing organization signed in as themselves
may ask for the terms, and only a direct administrator signed in to Apostra in
their own browser may approve them. An administrator of a parent organization who
is not a direct member, Apostra staff without a direct administrator membership,
service tokens and impersonated or support sessions are refused with
`ACCESS_DENIED`, and nothing is recorded.

Apostra's own screens ask for the choice the same way: the Buyer Setup Page and
the Media Partners prompt call `save_billing`, open the approval page, and show
the terms once they are in force.

## Remove a saved card

Removing a card changes how the organization pays, so a call from an agent or a
Page does not remove it. A direct administrator of the billing organization
approves the removal on Apostra first. Call `save_billing` with `paymentMethod`
and an `idempotencyKey`, sent alone (not beside `terms`, `paymentTerms`, `plan`,
`offerResponse`, `renewal`, `payer`, `mediaBilling` or `payNow`):

| Field | Meaning |
| - | - |
| `paymentMethod.remove` | The id of the saved card to remove, as digits. Only a card that is on file for the organization is accepted. |
| `idempotencyKey` | Required, and accepted only with `paymentTerms`, `paymentMethod` or `payNow`: a stable key you make up for this request. Repeat it with the same card to read the outcome. A rejected, expired or failed approval needs a new key. Reusing a key for another card is refused with `CONFLICT`. |

```json theme={null}
{
  "paymentMethod": { "remove": "17" },
  "idempotencyKey": "remove-card-17-2026-11-12"
}
```

The call removes nothing. It returns `action: "approval_required"` with an
approval `url`, its `state` and when it expires. Show the person the link and
say that nothing changes until an administrator approves. The approval page
shows the card, its brand, last four digits and expiry, as it is on file now.
A request is refused, and nothing is recorded, when the card is not on file for
the organization (`NOT_FOUND`), or when it is the organization's only way to
pay: with no credit line and no balance to spend, removing it would leave no way
to pay, so add a replacement card first. Approving removes the card once. It can
no longer be charged, and adding a card again goes through a new card setup. If
the card became the only way to pay between the request and the decision, the
approval fails and the card stays.

Call again with the same `idempotencyKey` to check. While the approval waits,
or when it ended without approval (`rejected`, `expired` or `failed`), the
answer is `approval_required` and its `state` says which. Once it is approved,
the answer is `action: "payment_method_removed"` with
`paymentMethod: { id, removed: true }`. Read billing again with `get` and
`kind: "billing"` to see the organization's payment status without the card.

Only a direct administrator of the billing organization may ask, and only a
direct administrator signed in to Apostra in their own browser may approve. A
user's own API key, which acts for that user, can ask. An administrator of a
parent organization who is not a direct member, Apostra staff without a direct
administrator membership, credentials that act for no user (service tokens and
organization API keys) and impersonated or support sessions are refused with
`ACCESS_DENIED`, and nothing is recorded.

## Change where a Seller is paid

Payout details are the bank account and beneficiary Apostra wires a Seller's
revenue to, so changing them binds the organization. A bank account number is a
secret, so it is typed only on Apostra's own web Payouts page, never in chat and
never in the Plan & Billing Page. An administrator signed in on Apostra saves
them there directly.

The Plan & Billing Page shows where payouts stand and, for a person who may
change them, a button that opens the Payouts page. It opens the link
`payout.manageUrl` that the billing read carries when you ask for
[`payouts`](https://docs.apostra.com/v3/billing-plan-and-invoices#payouts). A person who may not change
payouts gets no link and no button, and the Page says that only an account
administrator can. An agent does the same: it reads `payout.manageUrl`, shows
the person the link and asks them to open it. The Page no longer takes bank
details or calls `set_plan_billing_payout_payee`, the action earlier versions of
the Page used.

A request that does not come from that page, such as one sent with an API key,
does not change the details. It records a request, returns
`action: "approval_required"` with an approval `url`, its `state` and when it
expires, and takes effect only after a direct administrator of the billing
organization approves it on Apostra.

| What | Behaviour |
| - | - |
| Who may ask | A direct administrator of the billing organization, signed in as themselves. An administrator of a parent organization who is not a direct member, Apostra staff without a direct administrator membership, service tokens and impersonated or support sessions are refused with `ACCESS_DENIED`, and nothing is recorded. |
| Who may approve | A direct administrator of the billing organization signed in to Apostra in their own browser. It may be another administrator than the one who asked. The approval is checked again when the change is made. |
| What the approver sees | The beneficiary, the address, the payout currency and the bank identifier type, beside what is on file now. The account number and the bank identifier appear only as their last four characters, here, in the approval page and in the `approval_required` answer. |
| Details already on file | Asking for exactly what is already stored records nothing and answers that it is saved. |
| Repeating the call | Sending the same details again returns the same waiting approval. A different request under the same `idempotencyKey`, or the same key from another person, is refused with `CONFLICT`, and nothing is recorded or shown. A rejected, expired or failed approval needs a new request. |
| What is recorded | The change is written once, as the approving administrator, with the audit log naming the approval. The audit log, the approval record and every read hold no account number: the stored number is encrypted, and the request holds it only as a seal until the approval ends, then deletes it. |

`payout.onboardingStatus` becomes `complete` once the first payee is saved. Your own waiting request appears in
[`pendingApprovals`](https://docs.apostra.com/v3/billing-plan-and-invoices#pendingapprovals) as
`billing.payout_details`, with no bank data.

## Pay a failed payment now

When a card payment fails, Apostra retries it on a schedule. Paying now charges
the saved card straight away for the organization's open failed payment. It
moves money, so a call from an agent or a Page does not charge. A direct
administrator of the billing organization approves it on Apostra first. Call
`save_billing` with `payNow: true` and an `idempotencyKey`, sent alone (not
beside any other declaration):

| Field | Meaning |
| - | - |
| `payNow` | `true`. It names no card and no amount: the approval charges the organization's open failed payment. |
| `idempotencyKey` | Required, and accepted only with `paymentTerms`, `paymentMethod` or `payNow`: a stable key you make up for this request. Repeat it to read the outcome. A rejected, expired or failed approval needs a new key. |

```json theme={null}
{
  "payNow": true,
  "idempotencyKey": "pay-now-2026-11-14"
}
```

The call charges nothing. It returns `action: "approval_required"` with an
approval `url`, its `state` and when it expires. Show the person the link and
say that nothing is charged until an administrator approves. The approval page
shows the failed payment's amount and date and the card that would be charged,
as they are now. A request is refused, and nothing is recorded, when there is no
failed payment to pay (`NOT_FOUND`), when a payment attempt is already
processing (`VALIDATION_ERROR`), or when there is no card to charge
(`VALIDATION_ERROR`).

Approving starts one charge on the saved card. The payment provider reports how
it ends afterwards, so a started charge is not a paid one. Call again with the
same `idempotencyKey` to check. While the approval waits, or when it ended
without approval (`rejected`, `expired` or `failed`), the answer is
`approval_required` and its `state` says which. Once it is approved, the answer
is `action: "pay_now_started"` with `payNow: { status: "processing" }`. It never
says the payment was made. Read billing again with `get` and `kind: "billing"`
to see the result in `standing` and `balance` once the provider confirms it. If
the charge is declined, the failed payment stays open and its retry schedule
continues. An approval fails, and nothing is charged, when the failed payment is
gone by the time it runs (for example because it was paid in the meantime) or
the card was removed.

Repeating an approved request never charges twice: the charge carries a key that
Apostra stores on the failed payment before it is sent, so a charge whose answer
was lost is found again instead of repeated.

The same people may ask and approve as for a card removal.

## Change the renewal

Ending the plan at the end of its term, or keeping it renewing, changes the
contract the organization has accepted, so a call from an agent or a Page does
not change the renewal. A direct administrator of the billing organization
approves the change on Apostra first. Call `save_billing` with `renewal`, sent
alone (not beside `terms`, `paymentTerms`, `plan`, `offerResponse` or `payer`):

| Field | Meaning |
| - | - |
| `renewal.renewalVersion` | The `plan.renewal.version` the person was shown. |
| `renewal.action` | `CANCEL_AT_TERM` or `REINSTATE_AUTO_RENEWAL`, and only one of the `plan.renewal.allowedActions`. |
| `renewal.reason` | Why, in 3 to 500 characters. It is shown to the approving administrator and kept in the audit history. |
| `renewal.idempotencyKey` | Optional: a stable key you make up for this change, 8 to 128 characters. Repeat it with the same input to read the outcome. A rejected, expired or failed approval needs a new key. Reusing a key for a different change is refused. Without one, Apostra matches the call to the approval you already have open for the same action on the same renewal version, so a repeated call reads the same approval, and when none is open (it was rejected, expired or failed) the call is checked and asks again. The answer names the key it recorded the approval under (`idempotencyKey`, beside `approval`), so you can repeat the call with it to read that approval, in any state, without ever asking again. |

```json theme={null}
{
  "renewal": {
    "renewalVersion": "v1:7f3a…",
    "action": "CANCEL_AT_TERM",
    "reason": "Moving to another provider at the end of the term",
    "idempotencyKey": "renewal-cancel-2026-11-09"
  }
}
```

The call checks the version and the action first. A `renewalVersion` that is no
longer current is refused with `CONFLICT`, `field: "renewalVersion"` and
`details.currentVersion`, and an action outside `allowedActions` is refused with
`CONFLICT`. Nothing is recorded in either case: read the renewal again and ask
the person to confirm again.

Otherwise the call changes nothing. It returns `action: "approval_required"`
with an approval `url`, its `state` and when it expires. Show the person the link
and say that nothing changes until an administrator approves. The approval page
shows the action, the plan term it applies to and the date it takes effect (the
end of the current term), the reason, and the renewal as it stands now.

When an administrator approves, Apostra applies the change once, as that
administrator, and records it in the audit log under their name. It checks the
renewal version again at that moment. If the renewal has changed since you asked
(another change landed, the window for changing it closed, or the plan is no
longer eligible), the approval ends as `failed` and nothing changes: read the
renewal again and ask again, under a new key if you send one.

Call again with the same `renewal`, including its `idempotencyKey` if you sent
one, to check. A repeat with a key does not compare the version again, because
approving the first call moves the renewal on. While the approval waits, or when
it ended without approval (`rejected`, `expired` or `failed`), a keyed call
answers `approval_required` and its `state` says which. Once it is approved, it
answers `action: "renewal_changed"` with `renewal.instructionId`, `instruction`,
`effectiveAt` and `changeCutoffAt`. A call with no key reads the approval you
have open, and so answers `approval_required` while it waits; to check without
any chance of asking again, repeat the call with the `idempotencyKey` the answer
named. Once the approval
has succeeded the renewal has a new version, so a call with no key for the old
version is refused as stale: read `get` with `kind: "billing"`, which returns the
new `plan.renewal`, to see the change.

Only a direct administrator of the billing organization signed in as themselves
may ask for the change, and only a direct administrator signed in to Apostra in
their own browser may approve it. An administrator of a parent organization who
is not a direct member, Apostra staff without a direct administrator membership,
service tokens and impersonated or support sessions are refused with
`ACCESS_DENIED`, and nothing is recorded.

The [Plan & Billing Page](https://docs.apostra.com/v3/plan-and-billing.md) asks for the change the same
way: it calls `save_billing`, opens the approval page, says that nothing changes
until an administrator approves, and asks again while it waits. It shows the
result once the change is approved, and says plainly that nothing was changed if
the approval was declined, expired or failed. The Page and its controls send no
key on a click, so a Page that is rebuilt while an approval waits returns the
same approval on the next ask instead of recording a second. While it waits, the
Page checks with the key the answer named, which reads the approval and never
records a new one, so a declined change stays declined until the person asks
again.

## When an account becomes an organization

A standalone account is its own billing boundary. When it is converted into an
organization (see
[Turn a standalone account into an organization](https://docs.apostra.com/v2/setup/account-access.md#turn-a-standalone-account-into-an-organization)),
the billing read above starts reading the new organization, so the billing
records move with the conversion, in the same step as the contract. Nothing is
charged again and Stripe is not called.

What moves to the organization:

* the card, its Stripe customer, its payment methods (a detached one too), and
  any card setup or capture link that has not finished. The Stripe customer id
  and payment method id do not change, so a card entered before the
  conversion keeps being charged after it;
* a metered plan record (a plan with no monthly commitment), and the free,
  rollover and referral credit;
* credit standing, buyer payment terms and the billing currency override;
* the billing contact fields. They are copied: the organization gets them and
  the account keeps its own values as history.

What stays with the account: media billing entities and their advertiser
attachments. They keep resolving for the account's advertisers.

Where the organization already holds a plan record, standing, payment terms,
currency override, free credit or the same rollover cycle, the organization's
own record stays as it is and the account's stays on the account as history;
nothing is merged. An organization that already has its own Stripe customer
stops the conversion, because two cards cannot be reconciled by a rule.

An account with a charge, a closed cycle or an invoice in progress, a payment
collection in progress, an open standing hold, a plan with a monthly
commitment, a credit application, a referral or funds on its Apostra balance is
refused, and the refusal names which one.

Afterwards only organization administrators see and manage the card, invoices
and standing, because they belong to the organization. A member of the account
who is not an organization administrator no longer sees them, and a billing
read from that account returns the organization that manages billing or a
refusal, as in
[A caller without billing access](https://docs.apostra.com/v3/billing-plan-and-invoices.md#a-caller-without-billing-access).

## Billing documents

The rate card of a plan and the organization's contract documents are files, and
they download from Plan & Billing on the web, not from the API. A direct
administrator of the billing organization opens them from the page. The file is
served only to a signed-in browser session, so an API key, a service token or an
agent credential cannot fetch one, and the read carries no download link for
them. The proposal document of a plan, in force or upcoming, or of a pending
offer is the one of its `offerVersion`. If you need a copy of a document, open
Plan & Billing in the web app and download it there.

## What the read leaves out

The read never carries card numbers, security codes, processor IDs, processor secrets, setup tokens, hosted
invoice or payment links, browser hand-off links, or a full bank account number
or bank identifier. A card summary (brand, last four digits, expiry and status) is available with `include: ["paymentMethods"]`. It also leaves out
internal row IDs, the actor behind a renewal change and any free-text reason
given for one. `terms.url` and `nextAction.docsUrl` are public documentation
links.

## A caller without billing access

The read follows the same access rules as Plan & Billing. A member who cannot
read the organization's billing gets the organization that manages it, or a
refusal, never part of the plan section.

The `billing_managed` answer carries nothing from the organization's billing, so
`usageDetail`, `pricing`, `contracts`, `accounts`, `paymentMethods` and
`invoiceHistory` are left out of it when you ask for them. Each is listed in
`unavailableIncludes` with the reason.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.