Credits and billing
Understand available credit, review purchases and distinguish payments from reported usage cost.
Billing belongs to an organization. Personal and shared organizations use the same wallet machinery. When billing is enforced, Tokamak reserves credit before a paid request and settles the actual charge afterward. A deployment can also run with billing disabled or observing; read the status shown for your organization.
Payment methods, fees, receipts and auto top-up depend on operator configuration. The presence of the billing page does not establish that every payment feature is enabled.
Your balance
Open Organization › Billing & credits in the sidebar and check the payer name. Available credit is the primary figure. Expand balance details for:
| Figure | Meaning |
|---|---|
| Available credit | Ledger balance minus credit reserved for work in progress. |
| Ledger balance | The wallet balance before subtracting reservations. |
| Reserved | Credit held while requests complete and settle. |
| Outstanding debt | Money owed after a reversal; new deposits repay debt first. |
| Purchased credit | Lifetime purchased principal, not the amount still available. |
| Settled wallet charges | Lifetime settled charges, not the selected analytics period's usage cost. |
Budgets do not fund this wallet. Usage & spending reports request cost separately; it is not a wallet statement.
Add credit
- Choose Add credit beside your balance. Enter an amount and choose an available saved-card or new-card option in the payment dialog.
- Review the named payer, credit amount, processing fee, tax and total payment calculated by the server.
- Confirm and finish the configured payment flow. Changing the amount, card choice or organization requires a new review.
- Wait for the purchase status. Confirmation comes from the payment provider and can arrive asynchronously.
The fee is added to the credited amount. A payment total and purchased credit therefore need not be equal. Keep the existing purchase when recovering a pending result; retrying the same operation is idempotent, while starting another purchase is a new payment.
The return page checks pending status for a limited period and provides Refresh payment status. A purchase needing support stops automatic polling and shows its recovery state.
Saved cards and auto top-up
Choose Manage cards (or Set up card when none are saved) to open card management. Card details are handled by the payment provider. Tokamak shows the card summary, including brand, last four digits and expiry. You can manage the default and remove cards subject to the displayed safeguards.
Choose Set up beside Auto top-up. If there is no default card, choose a card, add one or make a saved card the default, then select Continue auto top-up. Enter the threshold and credit amount, review the per-top-up total, and choose Enable auto top-up. No automatic payment is enabled merely by adding a card.
Auto top-up uses the default card when available credit is below the configured threshold. The purchase amount is separate from the threshold, and fees apply. Review the configuration before enabling it. The UI explains disabled or failed states; turn it off when you no longer want automatic purchases. A required default card cannot be removed while the setting depends on it.
Purchase history and receipts
Recent payments shows the latest five records. Choose View all payments to open payment history and load earlier purchases. Payment totals include fees and tax; Credit added is shown separately. Pending or failed payments show a Quoted total, which is not confirmation of a charge.
Use the receipt action on a completed purchase when configured. Tokamak receipts download through an authenticated, organization-checked request; provider receipts may open at the provider. Expand purchase details for the original credit, fee, tax, payment total and support reference. Refunds, reversals and debt repayment remain separate adjustments.
Older Spend links redirect to Analytics. There is no separate customer Spend tab to reconcile with another usage workspace.
Refusals and recovery
| Status | Meaning | Action |
|---|---|---|
402 insufficient_credit | Credit admission refused the payer, including applicable debt conditions. | Review funds/debt with the billing administrator. |
403 billing_frozen | The wallet is frozen under the stated condition. | Contact the operator; do not assume repeated requests will fix it. |
503 billing_unavailable | Billing could not be consulted. | Retry or contact the operator; it says nothing about your balance. |
422 not_safely_billable | The request cannot be given a safe bounded price. | Correct the parameter named in the response. |
429 usage-limit breach | A blocking budget refused the request. | Review the budget window; adding credit does not remove the cap. |
Credit admission refuses before upstream execution. Keep refusal codes separate from upstream errors or requests that have already run.
Who can manage billing?
Reads require org.billing.view; purchases, cards and auto top-up require org.billing.manage. Owners and admins have these permissions. The fixed Billing Admin role also carries org.usage_limits.manage for budgets and organization usage, without general member/settings administration. A personal organization's owner uses the same permissions.
Inference keys do not authorize billing mutations. Customer refund requests have no general self-service page; contact your operator. See Access control and Error codes.