​

Number rental and your wallet

​

What an idle number costs

1. Before the renewal is attempted. When a number approaches next_billing_at and the wallet is already below the monthly charge, every owner and admin gets an email (“Action needed: add funds before your number renews”) plus an in-app Notification Center alert, both linking to the top-up screen. The email is throttled and the in-app alert fires at most once per billing cycle — a low balance produces one clear prompt, not a pile-up.
2. When the charge fails. The renewal is attempted once at next_billing_at. Too little balance does not flip the number’s status — it stays active, you get the “Number renewal failed — add funds” notice, and Orbit re-attempts the charge once a day. A top-up that settles before the daily attempt renews the number automatically; there is no manual retry step.
3. Notifications land with owners and admins only. Other team members are not emailed, so the people who can actually add funds are the ones warned.

​

The suspension arc

next_billing_at reached        renewal fails → number stays active
daily retries, days 1–7        each attempt fails → still active, still warned
day 7 unpaid                   status: suspended — stops sending and receiving
top up + reactivate            status: active — configuration intact

​

Why suspension is not release

​

Scheduled release and reclaim — the separate arc a suspend never enters

1. Schedule a release (PUT /api/v1/numbers/:id/scheduled-release). The number moves to parked — the release-path grace state.
2. The grace window stays open. While parked, the number is still assigned to you, and POST /api/v1/numbers/:id/reclaim moves it back to active without a re-purchase.
3. The window closes. The parking-expiry scheduler issues the carrier release and the row flips to released. That is terminal — the only way back is a fresh purchase.

​

Two controls: auto-renew per number, auto-top-up for the fleet

• Auto-renew is the per-number prevent-default control. Toggle it via PATCH /api/v1/numbers/:id/auto-renew (auto_renew: true) and Orbit re-bills the rental at next_billing_at automatically; only a row explicitly opted in renews — an unset flag reads as off, and the number lapses at next_billing_at instead. Auto-renew decides whether a payment is due; it cannot guarantee the wallet can pay it.
• Auto-top-up is the whole-fleet prevent-default control. It keeps the wallet funded: when the balance crosses your threshold_minor, Orbit charges your saved payment method off-session and credits the wallet. The evaluator runs every 15 minutes, consecutive auto-charges are separated by a 5-minute cooldown and capped at one per hour with a per-day cap (default 5), and a settled auto-charge is indistinguishable from a manual top-up in the ledger. Configure it via GET/PUT/DELETE /api/v1/billing/auto-topup or Dashboard → Billing → auto-replenish; full semantics on the Billing overview.

​

Worked scenario: a 50-DID campaign tenant that hits $0

1. Renewals fail in staggered order, not as one event. Because next_billing_at differs per number, the ~2 renewals per day that arrive first are the first to fail. The failed renewals emit the retry-once-a-day warnings; numbers that haven’t reached their renewal date are untouched.
2. Warning volume stays bounded. The pre-renewal low-balance email is throttled and the in-app alert fires at most once per billing cycle per number — 50 struggling numbers produce staggered single reminders, not an inbox flood. The tenant sees the wallet problem plainly instead of a pile-up that looks like a platform malfunction.
3. First suspensions arrive 7 days after the first unpaid renewal. The number whose renewal failed on day 1 suspends on day 8; the rest follow their own 7-day clocks. Nothing suspends in bulk unless renewals were bulk-aligned all along.
4. Auto-top-up intercepts the cascade before it binds. If auto-top-up is configured, its 15-minute evaluator sees the balance below threshold_minor and charges the saved card — usually within one evaluator cycle. The settled credit lands before the next daily renewal retry, the retry succeeds, and the number never leaves active. The hourly and daily auto-charge caps pace recovery instead of stampeding the card.
5. The mass-suspend that never happens. With auto-top-up on, the arc stops at step 1 for every number whose renewal hasn’t retried yet. Without auto-top-up, every number still recovers on top-up: fund the wallet once, the next daily retry clears the overdue renewals, and the few suspended rows reactivate from the Numbers page with configuration intact. A $0 wallet suspended 50 numbers? All 50 come back. A$0 wallet released none of them.

​

Posture checklist

• Keep auto-renew on for numbers you intend to keep; turn it off on teardown candidates and let them lapse deliberately.
• Set auto-top-up with a threshold_minor above your largest daily rental+usage draw, so the evaluator fires before any renewal retry cycles.
• Poll GET /api/v1/billing/balance from your integration and alert on outbound_block_reason — the same 402 pause machinery that gates sends tells you the wallet ran dry long before the 7-day suspend window closes.
• Reactivate after top-up, once — the renewal retry and reactivate are idempotent, so racing them cannot double-charge you.

​

See also

• Number status map — the six-state vocabulary this money arc moves through (active ↔ suspended)
• Number lifecycle — the step-by-step operations: auto-renew toggle, renewal reminders, reactivate, scheduled release, reclaim
• Number reuse, aging, and post-release posture — the parking grace window and regional aging floor a suspended number never approaches
• How billing meters your usage — the wallet rating pipeline the rental debits land in
• Wallets, credits, and charges — the prepaid ledger and the auto-top-up mechanics
• Billing overview — every endpoint named here