Billing

What you owe the platform and have paid (read-only; cards and top-ups are in the dashboard, which opens the payment provider's own pages). Your account is opened by the operator: prepaid (a balance — top-ups in, usage out) or postpaid (usage accrues; a monthly invoice settles it, under a credit limit). Your priced usage (charges in Usage) is charged to it a minute or two after each call.

Method	Path	Response
GET	/v1/billing	{ account, tax: { collected } } — account null until the operator opens one; collected: the platform adds tax on top
GET	/v1/billing/transactions	?page&limit → { page, limit, total, transactions: [{ id, kind, amount, balanceAfter, description, referenceType, referenceId, createdBy, at }] }
GET	/v1/billing/invoices	?page&limit → { …, invoices: [{ id, number, status, currency, total, tax, amountDue, taxStatus, periodStart, periodEnd, dueAt, paidAt, paidBy, hostedUrl, pdfUrl, createdAt }] }
GET	/v1/billing/invoices/{id}	{ invoice } with its lines: [{ kind, description, quantity, unit, amount, records }]
GET	/v1/billing/payments	?page&limit → { …, payments: [{ id, kind, status, amount, tax, charged, taxStatus, currency, invoiceId, failureReason, actionUrl, createdBy, at, updatedAt }] }

• account: id, mode (PREPAID / POSTPAID), currency, balance (prepaid: what's left; postpaid: negative = owed), creditLimit, available (what can still be spent), status — ACTIVE, OUTBOUND_BLOCKED (no balance left, over the credit limit, or an invoice overdue), SUSPENDED (long overdue, or by the operator) — and statusReason, pastDueSince, suspendedByOperator, autoTopup { enabled, threshold, amount }, card { brand, last4, expMonth, expYear } (nothing more of a card is ever stored), billingEmail, billingName, billingAddress { line1, line2, city, state, postalCode, country }, taxId{ type, value }, taxExempt (NONE, EXEMPT, REVERSE: set by the operator), invoiceDueDays, chargesFrom (usage before it isn't charged), createdAt.
• Tax. When tax.collected, the payment provider works out tax from your billing address and tax id and adds it on top: an invoice's total is before tax, tax is added, amountDue is what it asks for; a payment's amount is what your balance gets, tax was charged on top, charged is what the card paid. Your balance is never taxed. taxStatus is CALCULATED when tax was worked out; with no tax, it says why: OFF (not collected), NO_ADDRESS (you have no billing address — an invoice goes without tax, an auto top-up isn't charged until you add one), NOT_CALCULATED (an invoice settled by bank transfer). Set the address and tax id in the dashboard (Billing → Billed to).
• The ledger (transactions) is every credit and debit, newest first: kindTOPUP, AUTO_TOPUP, INVOICE_PAYMENT, ADJUSTMENT (by the operator, with its reason), REFUND (negative), USAGE (negative: priced usage, each record's rating names the debit). They add up to balance.
• An invoice bills the usage charged while the account was postpaid; usage paid from a prepaid balance is never invoiced.
• Payments: kind TOPUP, AUTO_TOPUP, INVOICE, REFUND; statusPENDING, REQUIRES_ACTION (the bank asks the card holder to confirm: actionUrl), SUCCEEDED, FAILED (failureReason), CANCELED, REFUNDED.
• In the dashboard these need the owner role; a session launched for one tenant never sees them.
• What the account allows. An outbound call is refused (402) when the account is OUTBOUND_BLOCKED or SUSPENDED, or can't pay the call's first billing block at the destination's price; it is checked again when Calloop dials (the agent gets call:error BILLING_REFUSED and the call ends FAILED / BILLING_REFUSED). A call your plan doesn't price is never refused for money. While a call is up it holds a few minutes' worth at a time; when the balance (or credit) runs out the call ends CREDIT_EXHAUSTED. A SUSPENDED account's inbound calls are declined (BILLING_REFUSED); one only blocked from calling out still takes them. A postpaid account without a credit limit is never stopped for money.
• Call rules, for every consumer, billing account or not: numbers in a range the operator blocks (destination_blocked), emergency short codes as a sip: address (emergency_not_supported); and your price plan's limits — the countries you may call (destination_not_allowed), calls at once, inbound and outbound across your tenants (too_many_calls; an inbound call over it is declined BILLING_REFUSED), the highest price a minute (rate_too_high).