​

Billing overview

• The dashboard exposes the same surface under Billing (alerts, invoices, statements, usage, cost-centers, pay-by-link, pricing, calculator, and the what-if simulator).
• The full request/response reference for every endpoint named here is in the Billing API reference.

​

1. Wallet & prepaid model

{
  "data": {
    "balance_usd": 150.00,
    "balance_cents": 15000,
    "balance_micro_cents": 15000000000,
    "credits": 15000,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  }
}

• outbound_paused — true when sending is paused (balance exhausted, a billing alert’s pause action, or repeated payment-method failures). Outbound sends return SENDING_PAUSED (HTTP 402) while paused.
• outbound_block_reason — why the pause is in effect, when set.
• payment_failure_count — consecutive Stripe payment failures (0–3) driving dunning; at 3 the account is frozen until the card is updated.

​

2. Top-up flows

​

3. Auto-top-up

• GET /api/v1/billing/auto-topup — read the current config.
• PUT /api/v1/billing/auto-topup — create or update the rule.
• DELETE /api/v1/billing/auto-topup — disable it and clear its state.

{
  "enabled": true,
  "threshold_minor": 5000,
  "recharge_amount_minor": 10000,
  "max_monthly_minor": 50000,
  "max_topups_per_day": 5,
  "currency": "USD"
}

• threshold_minor — the balance level (minor units, e.g. cents) that triggers a top-up. Minimum $1.00.
• recharge_amount_minor — the amount charged when triggered. Must exceed the threshold so each top-up lifts the balance back above the trigger (otherwise you would get charged repeatedly).
• max_monthly_minor — optional monthly cap. Persisting it is explicit: omitting the field (or sending null) keeps any saved cap; removing a cap requires "clear_cap": true.
• max_topups_per_day — optional per-day cap (default 5) bounding runaway-loop exposure.

​

4. Plans & subscriptions

• POST /api/v1/billing/subscription — cancel, reactivate, or change_plan with an audit-logged reason (owner/admin/billing role).
• POST /api/v1/billing/checkout — mint a hosted checkout session for a one-off enterprise contract price.
• POST /api/v1/billing/portal — open the payment-method portal for the org’s Stripe customer.
• GET /api/v1/billing/payment-method — read the saved payment method.

​

5. Invoices & statements

​

6. Usage, burn rate, and spend alerts

• GET /api/v1/billing/alerts / GET /api/v1/billing/alerts/:id — list and read.
• POST /api/v1/billing/alerts — create (thresholds: spend_percent, spend_amount, balance_remaining, daily_spend; recipients by email and/or SMS; action_on_hit: notify, pause_outbound, or block_outbound; cooldown up to 30 days).
• POST /api/v1/billing/alerts/:id/test — dry-run test-fire.
• GET /api/v1/billing/spend-anomaly and GET /api/v1/billing/spend-anomaly/ledger — velocity-anomaly detection that flags channels projecting a spend surge above your trailing baseline.

​

7. Committed-use contracts

{
  "data": {
    "commitment": {
      "monthly_commit_cents": 100000,
      "discount_percent": 15,
      "currency": "USD",
      "term_start": "2026-01-01",
      "term_end": "2026-12-31"
    },
    "drawdown": {
      "committed_cents": 100000,
      "consumed_cents": 62000,
      "remaining_cents": 38000,
      "drawdown_percent": 62,
      "projected_spend_cents": 80000,
      "projected_shortfall_cents": 20000,
      "days_elapsed": 15,
      "days_in_period": 31,
      "status": "on_track"
    }
  }
}

​

8. Refunds

• POST /api/v1/billing/refunds — create a refund request (owner only).
• GET /api/v1/billing/refunds / GET /api/v1/billing/refunds/:id — list and poll request status.

​

Where next

• Billing API reference — endpoint-by-endpoint request/response detail.
• Cryptocurrency payments — crypto top-ups.
• Cryptocurrency refunds — the operator-managed refund process.
• Wallet top-up currency conversion — FX behavior on non-wallet-currency credits.