Skip to main content

​
How billing meters your usage

Orbit bills from a prepaid wallet. You top the wallet up, usage debits it in real time, and every credit and debit lands in an append-only ledger you can read and reconcile. This page is the map of that pipeline — the other billing pages zoom in on one step of it.

​
Units of money — one wallet, one currency

Every organization holds a single wallet denominated in one currency (typically USD). All usage — messages, voice minutes, AI tokens — is priced and debited in that currency, and the balance endpoint reports it in dollars, whole cents, and exact integer micro-cents so sub-cent rates (per-email, per-token) stay precise. When you top up in a currency other than your wallet currency, Orbit converts at credit time and records the applied rate on the resulting transaction. The rate comes from a fixed priority pipeline, and the first source that returns a usable rate wins:
  1. A pinned rate for the pair (an administrator-set explicit rate).
  2. A commercial provider feed (hourly-refreshed, when configured).
  3. A public live feed (when enabled).
  4. A maintained reference table built on published central-bank rates. In a default deployment the live sources above are off, so this table is the source used — with a 60-day staleness ceiling past which Orbit refuses to use it.
If no active source returns a usable rate, Orbit does not guess — the conversion fails with FX_RATE_UNAVAILABLE. Hosted card checkouts retry automatically; API-initiated top-ups return the error so your integration can retry. Same-currency top-ups are never affected. The pipeline’s mechanism is modeled end to end on FX-rate resolution; the person-level walkthrough is on Wallet top-up currency conversion.

​
Rating — how usage events become debits

Orbit’s own usage debits follow the same shape the rating pipeline exposes: each event is counted in a unit (messages, minutes, tokens), a quantity is bundled at no charge when a plan includes one, and the overflow is priced against graduated tiers — per-tier unit prices where each tier covers a bounded range and the last tier is open-ended. You can exercise that rating pipeline directly through the Usage Metering API, built for platforms reselling Orbit to their own customers. You POST a batch of usage events (tagged per subaccount) plus a meter definition — unit, currency, includedQuantity, and graduated overageTiers — and get back a rated per-subaccount rollup: total quantity, included quantity, billable quantity, and the priced amount per tier. On top of the rated amount you can apply a reseller margin (a percentage markup on each subaccount, 0–100) and a tax line (VAT/GST/sales tax with an optional exemption certificate; only an approved certificate matching the tax jurisdiction suppresses the tax line). The response then carries the wallet-ledger debit descriptors and, when you supply invoice metadata, a branded HTML invoice — the document you hand your end customer. The margin concept — percentage per subaccount, applied before tax, and how it differs from a rate markup — has its own page: Reseller margin and the tax pipeline.

​
Credits and refunds in the ledger

The ledger is append-only; every movement is either a credit or a debit with a recorded reference.
  • Card top-ups credit the wallet when the payment settles, and produce a receipt under Dashboard → Billing → Invoices.
  • Crypto top-ups settle to USD-equivalent credits — once confirmed, the funds are indistinguishable from any other top-up (Cryptocurrency payments).
  • Card refunds reverse the original charge within a 30-day window and only against unused balance.
  • Crypto refunds are operator-processed payouts on the same chain as the original payment; when the payout confirms, the original credited amount is reclaimed from the wallet (Cryptocurrency refunds).

​
Reconciliation edge cases

  • Number renewals against a low balance. A held number’s monthly rental charges from the wallet each cycle. When the balance cannot cover an upcoming renewal, every owner and admin gets a throttled warning (email plus a Notification Center alert). If the charge fails, the number stays active and Orbit re-attempts the charge once a day until you top up (Number lifecycle). The full warning → suspend → reactivate arc is laid out on Number rental and your wallet.
  • What counts as billable usage. SMS bills per segment — a long message splits into multiple billable segments, so message length drives cost, not sends. Voice bills per minute. AI usage bills per token. Segments and per-channel units are spelled out in the pricing-throughput guide.
  • Which refusal fires when. A send that can’t be paid for is refused before it starts (see the next section). At $0 balance the pre-flight rejects with INSUFFICIENT_BALANCE (402). If the org’s outbound flags are set, the flags gate rejects with SENDING_PAUSED (soft pause — auto-pause-on-zero or a billing alert you configured) or SENDING_BLOCKED (hard hold — suspended subscription, payment dispute, admin suspension), also 402. The balance response’s outbound_block_reason names the cause (wallet_empty, billing_alert:<id>:<name>, dunning_failed_3x). The recovery loop is the same for all of them: treat 402 as terminal, top up or resolve the flagged cause, poll GET /api/v1/billing/balance until outbound_paused flips false, then resume. The auto-top-up evaluator runs every 15 minutes to stop wallet_empty pauses before they form (auto-top-up).

​
Authorize before you use — the prepaid model

Two properties of the ledger complete the picture: authorization is before-use, not post-hoc, and every debit collapses retries. The companion ledger page documents both in full — Wallets, credits, and charges — this section is the conceptual summary. Debits are authorized before usage runs, not debited afterwards. Every send pre-flights the wallet (a sub-cent channel with $0 fails with INSUFFICIENT_BALANCE, 402), and the check-and-decrement is one atomic operation — concurrent debits can’t race each other into an overdraft. A voice call additionally holds up to two minutes’ worth at dial before the provider leg is ever dialed, then settles the delta when the call ends (minimum 2¢ at dial, 1¢ per call at settle; unanswered calls refund the hold in full). That voice hold is the only hold/reservation in the model — other channels pre-flight but never escrow funds. Retries can’t double-charge. Each balance mutation carries an idempotency key naming the real-world event it pays for (the message id, call id, checkout session id). The key caches the mutation’s result for 24 hours and drives the ledger row’s deterministic identifier — a retry replays the cached result without moving money, and concurrent attempts with the same key either collapse to one debit or get a 409 DEDUCT_IN_FLIGHT to back off with. Insufficient-balance outcomes are never cached, so top-up + same key retries cleanly.

​
What you can’t do here

The rating endpoints under Usage Metering are stateless — nothing is persisted. The rollup returns wallet-ledger debit descriptors and invoice drafts as a preview; committing those writes against your downstream customers is a separate step in your own billing flow. Do not treat a rollup response as money moved.

​
End to end: top-up → usage → debit

  1. Top up. You pay by card or crypto. If the currency differs from your wallet currency, the rate pipeline resolves a rate and the converted amount is credited, with the rate recorded on the transaction.
  2. Usage. Every send, call, or AI request is counted in its unit and priced against the applicable meter — included quantity first, then graduated tiers — as it happens.
  3. Debit. The priced amount is debited from the wallet in real time and appended to the ledger. You can read the balance, the ledger, and monthly statements built from it at any time.
The person-level operation of each step — top-up endpoints, alerts, statements, refunds — is documented in the Billing overview and the Billing API reference. The ordered chain every send walks (pre-flight → flags → fund path → atomic decrement) is narrated on the billing gate chain.