> ## 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, plan, the offer it can accept, its
renewal, its recent invoices and the next thing to do. It takes no ID, filter or
include. 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, and an account whose organization manages billing for it gets the
`billing_managed` answer described in
[Response variants](/v3/response-variants).

## 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. |
| `terms`, `paymentAuthority` | Current Terms and payment status, as described in [Check and complete Terms setup in text-only chat](/v2/setup/v3/tool-reference#check-and-complete-terms-setup-in-text-only-chat). |
| `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` and `canCompleteInChat`. |

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

### `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.helpAvailable` | Whether a plan help request can be filed now. |

`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 and `accountLimit`, or `null` when the plan grants none. |
| `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 private rate card behind the offer (`version`, `visibility`, `displayName`), or `null`. |
| `governedBy.proposal` | The private proposal behind the offer (`documentTitle`, the scope it includes and excludes, `initialTermMonths`, `defaultPaymentOptionKey`), or `null` for a public offer. |
| `initialTermMonths` | The length of the first term. |
| `plans` | The plans on offer, in catalog order. Each has `planId`, `planName`, `currency`, `commitmentMinor`, `includedIus`, `iuPriceMinor`, `entitlements`, `displayOrder`, `paymentOptions` and `acceptanceConvertsStandaloneAccount`. |

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

## What the read leaves out

The read never carries card data, processor secrets, setup tokens, hosted
invoice or payment links, or browser hand-off links. 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.


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