Skip to main content

Bulk order history

Every POST /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.
Open an order row to expand the per-line breakdown: each line shows the E.164 number, country, capabilities, monthly cost, and either 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. Inspect failed_count and the per-line errors.
  • failed — no line succeeded; nothing was charged.
Failed lines are never 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 the numbers: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 holding numbers:read:
Orders are org-scoped: an unknown or not-owned id returns 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. Match delivered_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