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. Every lifecycle verb returns the standard{ data, meta } envelope — no per-verb surprise. The shapes below hold for every mutation on this page:
Auto-Renew
Toggle automatic recurring renewal so a held number is re-billed each cycle instead of lapsing atnext_billing_at.
200 with the number record after the update — the persisted auto_renew flag lives in data.metadata.auto_renew:
"auto_renew": false to opt back out — the response echoes metadata.auto_renew: false. The request fails 409 CONFLICT on a released number (there is nothing left to renew).
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.
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.PUT returns 200:
GET returns 200 with the same shape; when no schedule exists, data.scheduled_release is null.
Clear — DELETE returns 200:
release_at is an ISO-8601 future timestamp (UTC, ending in Z). data.scheduled_release.status goes from scheduled to released once the release fires, or cancelled / failed if the run aborted.
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.200 with the new ownership chain:
assigned_to_org_id field always holds the new owner; previous_assigned_to_org_id holds the org that moved it. 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 carrierDELETE fails (release_status = "failed" or stuck pending), re-issue it without re-purchasing.
202:
202 means the re-attempt job is queued, not that the carrier already acked it — poll GET /numbers/:id and watch release_status move back to pending.
Reclaim a Parked Number
Re-claim a parked number during its grace window without re-purchasing from upstream. Returns409 when the number isn’t reclaimable (not parked, wrong org, or window expired) — fall back to a fresh purchase in those cases.
200 with the restored number record — status is back to active and release_status settles at completed (no upstream release is owed anymore):
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 atpending_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.POST /numbers/claim-trial returns 201 with the assignment:
GET /numbers/trial returns the same assignment shape inside data (null when none); the meta.ever_claimed flag tells you whether the org has used its one free claim:
POST /numbers/purchase-trial returns 200 with the purchase result inside data.
Release — DELETE /numbers/release-trial returns 200:
See also
- Number dormancy and rental spend — understand how to review numbers with no recent calls or messages before scheduling a release.
- Low DID inventory alerts and the auto-replenishment loop — see how the daily low-stock sweep flags a depleted (country, area code) pool and how the replenishment policy, plan, and run endpoints top it back up.