​

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).
• 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.

​

Next steps

• 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).