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.
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.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
plan.current and plan.upcoming carry the same fields:
plan.offer carries:
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:
invoices
invoices lists at most 10 invoices, newest first. invoicesTruncated is
true when the organization has older ones.
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.