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 order ids come from

The ledger starts upstream: POST /api/v1/numbers/buy-bulk creates the order and returns it synchronously with a stable order_id in the response body. Store that id at call time — it is the only handle you have for polling or re-audit after the response returns, and the order detail endpoint below keys on it. The two GET endpoints on this page are the follow-up to that one POST: GET /numbers/orders lists the ledger so you can find orders you did not capture at create time, and GET /numbers/orders/:id re-reads one order with its per-line outcomes. The create call itself — search inventory, forward each inventory row’s id into the buy-bulk items, attach one compliance profile — is covered in Buy and provision numbers; this page is what you do with the id that call hands back. One asymmetry matters when you plan a reconciliation loop: POST /numbers/buy-bulk is rate-limited to 2 requests per minute per tenant (one call fans out to up to 50 carrier calls), but the order-read endpoints carry no such ceiling — poll them on whatever cadence reconciliation needs; the create-path limit never gates your polling.

​
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_NO_LONGER_AVAILABLE) 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; the per-line error-code table and retry guidance live in Buy and provision numbers.

​
See Also

  • Create a bulk order — the upstream POST /numbers/buy-bulk that produces the ids this ledger audits.
  • 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.
  • Inbound health — after a bulk buy lands, check the Numbers → Inbound health tab and repair any missing routing entries before traffic starts.
  • Phone Numbers — the full numbers endpoint surface.
  • Inventory & Export — page and export what you own.