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 full mechanism 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.

​
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).
  • 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.
  • Pause states. When the balance is exhausted (or a billing alert’s pause action fires), outbound sending pauses and sends return SENDING_PAUSED until you top up or re-enable.

​
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.