​

Wallets, credits, and charges: how usage metering works

​

The prepaid ledger — one balance, append-only history

• The balance is the spendable remainder, read live from GET /api/v1/billing/balance.
• The ledger is the append-only history of every movement that produced that balance, read from GET /api/v1/billing/transactions with cursor pagination. Rows are never updated or deleted — a reversal is a new row of the opposite sign, so you can replay the ledger to reconcile the balance against your own records.

​

Credit paths vs. debits at usage time

• Top-up credit — a card checkout or crypto payment settles:
  {
    "type": "credit_purchase",
    "amount_minor": 10000,
    "reference": "checkout:cs_live_a1b2c3",
    "created_at": "2026-08-01T14:22:10.000Z"
  }
  
• Other credits — refunds and trial/admin grants land (type = refund, admin_grant, …) as positive rows the same way.
• Usage debit — every send, call, or AI request debits the wallet as it happens, with the reference naming what was charged:
  {
    "type": "debit",
    "amount_minor": -2,
    "reference": "charge:sms_mccmnc:msg_4f8c1d",
    "created_at": "2026-08-01T14:35:41.000Z"
  }
  

​

Pause semantics — when outbound sending stops

• outbound_paused: true — sends are currently refused.
• outbound_block_reason — the machine-readable cause when set (wallet_empty at a $0 balance, billing_alert:<id>:<name> when a billing alert’s pause action fired, dunning_failed_3x after repeated payment failures). Harder hold classes — a suspended subscription (yours or an ancestor reseller’s) or an active payment dispute — flip the outcome to SENDING_BLOCKED, same HTTP 402. The send-time checks fire in order: first the balance pre-flight (INSUFFICIENT_BALANCE on an empty wallet), then the flags gate (SENDING_PAUSED / SENDING_BLOCKED), then the fund-consuming charges (the voice hold, or the post-send ledger debit). An account-level block beats a balance check by construction: a blocked tenant is refused even with money in the wallet.
• payment_failure_count — consecutive card payment failures (0–3). At 1 or 2, dunning is in progress and the dashboard warns the owner to update the card; at 3 the account is frozen until it’s fixed.

{
  "error": {
    "code": "SENDING_PAUSED",
    "message": "Outbound sending is paused for this organization. Top up the wallet or reset the billing alert to resume.",
    "details": {
      "reason": "wallet_empty"
    }
  }
}

​

Units — dollars, cents, and micro-cents

{
  "data": {
    "balance_usd": 150.00,
    "balance_cents": 15000,
    "balance_micro_cents": 15000000000,
    "currency": "USD"
  }
}

​

Degraded balance — the last-known fallback

{ "data": { "balance_cents": 15000, "degraded": true, "source": "db-fallback" } }

​

Auto-top-up feeds the same ledger

• An evaluator runs on a 15-minute schedule and compares the balance to your threshold_minor.
• A 5-minute cooldown separates consecutive auto-charges.
• No more than one auto-charge per hour fires even after the cooldown clears, and a per-day cap (default 5) bounds runaway exposure.

​

Authorize-then-debit — and the one authorized hold

• Every send and call goes through a wallet pre-flight. A send on a sub-cent channel reads the balance up front and fails with INSUFFICIENT_BALANCE (HTTP 402) when it can’t pay. Voice goes further: it needs a funded hold before the provider leg is even dialed (below).
• Voice holds up to 2 minutes at dial time. This is the only hold/reservation in the billing model. When you place a call, Orbit resolves the destination’s per-minute rate and debits two minutes’ worth up front (minimum 2¢). An empty wallet means no hold, and no hold means the call never dials. When the call ends, Orbit computes the true charge from the call record — per-minute rate, one-minute billing increments, minimum 1¢ per call — debits only the difference above what the hold already took, and refunds the hold in full when the call never answered. The FX rate locked at hold time is reused at settlement, so the two computations can never disagree on currency. For rated channels other than voice there is no reservation — the send pre-flight checks the balance but never escrow funds against it.

​

How the idempotency key collapses retries

• Result cache. Before a debit runs, the key is claimed atomically; the completed result is then stored under it for 24 hours. A retry with the same key returns the stored result without moving money again, and two concurrent calls with the same key either collapse to one debit or the second is refused with DEDUCT_IN_FLIGHT (409) — safe to retry with the same key after a short backoff. An INSUFFICIENT_BALANCE outcome is never cached: it clears the key, so topping up and retrying the same key with funds works.
• Ledger reference. The same key is stamped onto the credit_transactions row and drives its deterministic identifier — the same (organization, idempotency key) pair always resolves to the same ledger row, so retries collapse to one row instead of double-billing. Replayed balance responses carry idempotentReplay: true so callers don’t re-fire side effects (webhooks, notifications, audit entries) on a deduplicated retry.

{
  "id": "txn_9f2c1a4b7e…",
  "type": "debit",
  "amount_minor": -2,
  "reference": "charge:sms_mccmnc:msg_4f8c1d",
  "idempotency_key": "charge:msg:msg_4f8c1d",
  "created_at": "2026-08-01T14:35:41.000Z"
}

​

Next steps

• The outbound billing gate chain — the ordered chain (pre-flight → flags → fund path → atomic decrement) every send walks, narrated once.
• Spend alerts, burn rate, and the velocity-anomaly model — the threshold-alert, burn-rate, and anomaly-detection instruments layered on top of this ledger and its pause gate.
• Billing overview — endpoint surface map (top-ups, alerts, invoices, statements, refunds).
• Billing API reference — request/response schemas for every endpoint named here.
• How billing meters your usage — the rating pipeline behind each debit (included quantity, graduated tiers, FX on converted top-ups), and the authorize-before-use model of this ledger.