> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk number-order history: the delivered/partial/failed ledger

> Audit every bulk purchase after the fact — the order ledger lists GET /numbers/orders and GET /numbers/orders/:id with aggregate per-order status plus a per-line breakdown, so finance reconciles what a bulk buy actually delivered.

# 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`:

```bash theme={null}
# List recent bulk orders (summaries)
curl "https://api.orbit.devotel.io/api/v1/numbers/orders?limit=20" \
  -H "X-API-Key: dv_live_sk_..."

# Fetch one order with per-line outcomes
curl "https://api.orbit.devotel.io/api/v1/numbers/orders/numOrder_01J9Z8ABCDEF" \
  -H "X-API-Key: dv_live_sk_..."
```

```json theme={null}
{
  "data": {
    "order_id": "numOrder_01J9Z8ABCDEF",
    "status": "partial",
    "requested_count": 2,
    "delivered_count": 1,
    "failed_count": 1,
    "total_cost_cents": 300,
    "debited_cents": 150,
    "created_at": "2026-08-24T12:00:00.000Z",
    "lines": [
      {
        "phone_number": "+14155550100",
        "line_status": "delivered",
        "country_code": "US",
        "capabilities": ["sms", "voice"],
        "monthly_cost_cents": 150
      },
      {
        "phone_number": "+14155550101",
        "line_status": "failed",
        "error": { "code": "NUMBER_UNAVAILABLE", "message": "Number no longer available" }
      }
    ]
  }
}
```

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](/billing/cdr-export-billing-reconciliation) explains both feeds. Match `delivered_count` on each order against active inventory in [Inventory & Export](/numbers/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](/guides/buy-numbers) — the full search → buy → audit → wire loop, single and bulk.
* [Bulk Reserve](/guides/bulk-reserve) — hold up to 1000 matching DIDs, then finalize or cancel.
* [Phone Numbers](/numbers/overview) — the full numbers endpoint surface.
* [Inventory & Export](/numbers/inventory-export) — page and export what you own.