Bulk order history
EveryPOST /numbers/buy-bulk call persists an order record — a stable, pollable ledger of the batch — so you can reconcile what a bulk buy actually delivered days or weeks after the request returned. This page covers the ledger console in the dashboard and the two read endpoints behind it: GET /numbers/orders (list) and GET /numbers/orders/:id (per-line detail).
Each record carries the aggregate status (delivered, partial, or failed) plus a per-line breakdown with carrier error codes — the same order-status surface Twilio and Bandwidth ship as OrderStatus. All reads are inbound DID provisioning history only; the ledger never touches outbound routing.
Where it lives
In the dashboard, go to Numbers → Buy → Orders. The Orders tab sits next to Buy (single purchase) and Bulk (bulk reserve):- Buy — search inventory and purchase one DID at a time.
- Bulk — reserve a block of up to 1000 matching DIDs for 15 minutes, then finalize or cancel.
- Orders — the history of every submitted bulk purchase, newest first.
delivered or the carrier error for the failure — enough to tell inventory turnover (NUMBER_UNAVAILABLE) from a regulatory hold without replaying the batch.
Poll-style order records
Bulk purchases resolve in one request, but the record is built for polling: the response and every later read carry the same aggregate tallies and per-line results.delivered— every requested line succeeded.partial— some lines succeeded, some failed. Inspectfailed_countand the per-line errors.failed— no line succeeded; nothing was charged.
total_cost_cents sums the full batch; debited_cents is what the wallet actually paid — the succeeded lines only. The dashboard marks this surface inbound DID provisioning history only; it is a provisioning ledger, not an outbound-routing surface.
Access and limits
The ledger is read-only for every role that can see the Numbers page — owner, admin, and members with numbers access. API reads need thenumbers:read scope. Nothing on the page or endpoint mutates data: orders are append-only records of past purchases.
API parity
Authenticate with an API key holdingnumbers:read:
404 — a missing id never leaks that the order exists elsewhere.
Reconcile against usage exports
To tie the provisioning ledger to usage billing, pull the per-call detail records and reconcile them against the delivered lines: CDR export & billing reconciliation explains both feeds. Matchdelivered_count on each order against active inventory in Inventory & Export; retry failed lines from a fresh inventory search — failed rows are never charged, so retrying is safe.
See Also
- Buy and provision numbers — the full search → buy → audit → wire loop, single and bulk.
- Bulk Reserve — hold up to 1000 matching DIDs, then finalize or cancel.
- Phone Numbers — the full numbers endpoint surface.
- Inventory & Export — page and export what you own.