Number Lifecycle
Once you own a number, Orbit gives you full lifecycle control: keep it billing automatically, schedule a future teardown, hand it to a sibling subaccount, recover from a failed carrier release, or reclaim a parked number during its grace window.
All lifecycle mutations are gated by org ownership — a sibling subaccount sharing your tenant schema cannot touch a number it doesn’t own.
Auto-Renew
Toggle automatic recurring renewal so a held number is re-billed each cycle instead of lapsing at next_billing_at.
Renewal Reminders & Low-Balance Warnings
A held number’s monthly rental is charged from your wallet each cycle. When your balance can’t cover an upcoming charge, Orbit warns you before the renewal is attempted — and again if it fails — so a number never lapses without notice.
- Before the renewal. When a number is approaching its renewal date and your wallet balance is already below the monthly charge, every owner and admin gets an email (“Action needed: add funds before your number renews”) and an in-app alert in the Notification Center (“Number renewal at risk — add funds”). Both link to the wallet top-up screen. The email is throttled and the in-app alert fires at most once per billing cycle, so a low balance won’t produce a daily pile-up of reminders.
- When the renewal fails. If the charge is attempted with too little balance, you get a follow-up notice (“Number renewal failed — add funds”). The number stays active and Orbit re-attempts the charge once a day. Once you top up, the next attempt renews the number automatically — no manual step needed.
- After the grace window. A renewal that stays unpaid for 7 days past its due date suspends the number. A suspended number stops sending and receiving until you add funds and reactivate it from the Numbers page. It is not released, so reactivating restores it unchanged.
To clear a warning, add funds from Billing, then confirm the number reads active on the Numbers page. Owner and admin users receive these notices; other team members are not emailed.
Scheduled Release
Pre-plan a teardown (seasonal campaign DIDs, trial overflow, contract end-of-term) without remembering to release on the day. A separate sweeper drives the existing release path when the date arrives.
release_at is an ISO-8601 future timestamp.
The PUT / GET / DELETE /:id/scheduled-release trio above is the canonical scheduled-release surface — all three verbs read and write the same schedule.A separate PATCH /:id/scheduled-release endpoint (body { "release_at": "<iso>" | null }) also exists, but it keeps its own independent schedule and does not interoperate with the trio: a schedule set with PUT is not returned by GET, is not removed by the PATCH endpoint, and vice versa. PATCH with release_at: null clears only the PATCH schedule, never the one set via PUT. Pick one surface and use it consistently — for read/write/clear, prefer the PUT / GET / DELETE trio.
Reassign to a Subaccount
Move a purchased number from your subaccount to a sibling subaccount under the same reseller parent — the DID parity to wallet transfer-to-subaccount.
The target must be a same-tenant, same-family sibling, and your subaccount must currently own the number. Eligibility is decided by ownership, not by a status value: a number your subaccount doesn’t own (including a trial-pool number you’ve only claimed) can’t be reassigned. Cross-tenant or unowned moves are rejected.
Retry a Failed Release
When a carrier DELETE fails (release_status = "failed" or stuck pending), re-issue it without re-purchasing.
Reclaim a Parked Number
Re-claim a parked number during its grace window without re-purchasing from upstream. Returns 409 when the number isn’t reclaimable (not parked, wrong org, or window expired) — fall back to a fresh purchase in those cases.
Repair Provisioning
Re-attach the messaging profile and voice connection on a number whose original purchase left them partial.
Attach a Compliance Profile
For a number that landed at pending_compliance, attach an approved compliance profile. Orbit re-submits the profile to the carrier and patches the pending order; a carrier webhook later flips the row to active.
Trial & Shared-Pool Numbers
New organizations can claim a trial number from a shared pool, then purchase it to keep it permanently or release it back.
Claim and purchase are rate-limited to 5 requests per minute per tenant.
