# Orders

Use the Orders resource to create, retrieve, and cancel orders associated with your DIDWW
account.

An Order records a purchase and provides its reference, amount, status, description,
creation time, and ordered items. Order items can describe DID phone numbers or channels
added to a Capacity Pool.

Orders are commonly used after checking the account balance and selecting DID inventory.
Use a Stock Keeping Unit `id` as `sku_id` to order DID phone numbers in bulk, purchase
a specific Available DID, or complete the purchase of a reserved DID. Orders can also be
used to add channels to a Capacity Pool.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Orders | `GET` | `/v3/orders` |
| Retrieve Order | `GET` | `/v3/orders/{id}` |
| Create Order | `POST` | `/v3/orders` |
| Cancel Order | `DELETE` | `/v3/orders/{id}` |

## Retrieve all Orders

Retrieves all Orders associated with the account.

Use this endpoint to review order history and filter Orders by ID, status, creation date,
reference, or external reference ID. Results can be sorted by status, amount, creation
time, or description.

See [Retrieve All Orders](get-orders.html).

```
GET /v3/orders
```

## Retrieve Order

Retrieves a specific Order by its unique ID.

Use this endpoint to check the Order status, amount, reference, ordered items, billing
details, and callback configuration.

See [Retrieve Order](get-order.html).

```
GET /v3/orders/{id}
```

## Create Order

Creates an Order for DID phone numbers or additional channels.

For DID orders, provide a Stock Keeping Unit `id` as `sku_id` together with a quantity,
an Available DID ID, or a DID Reservation ID. The request can also control back-ordering,
provide an external reference ID, and configure order event callbacks.

For channel orders, provide the Capacity Pool ID and the required quantity.

See [Create Order](create-order.html).

```
POST /v3/orders
```

## Cancel Order

Cancels an Order that is still in `pending` status.

Use this endpoint when a pending Order should not be completed. Canceling the Order also
removes the DID phone numbers included in that Order.

See [Cancel Order](cancel-order.html).

```
DELETE /v3/orders/{id}
```

## Common Order use cases

| Use case | Description |
| --- | --- |
| Review account orders | Retrieve the account's Order history and inspect amounts, references, and ordered items. |
| Track Order status | Determine whether an Order is `pending`, `completed`, or `canceled`. |
| Order DID numbers in bulk | Use a Stock Keeping Unit `id` as `sku_id` together with `qty` to order multiple DID phone numbers. |
| Order a specific DID number | Use `available_did_id` with `sku_id` to purchase a selected Available DID. |
| Complete a reserved DID purchase | Use `did_reservation_id` with `sku_id` to purchase a reserved DID phone number. |
| Increase channel capacity | Use a Capacity Pool ID and quantity to add channels to the pool. |
| Receive Order events | Configure a callback URL and method to receive events related to the Order. |
| Cancel a pending Order | Cancel an Order before it is completed and remove its included DID phone numbers. |

## Related resources

Use Orders together with balance, coverage, and inventory resources to purchase DIDs and
add channels to a Capacity Pool.

| Resource | Description |
| --- | --- |
| [Balance](../balance/index.html) | Account funds available before creating an Order. |
| [DID Groups](../../coverage-resources/did-group/index.html) | DID inventory groups that provide Stock Keeping Units for ordering. |
| [Available DIDs](../../coverage-resources/available-did/index.html) | Specific DID phone numbers that can be selected before ordering. |
| [DID Reservations](../../coverage-resources/did-reservation/index.html) | Temporary reservations used to hold selected DID phone numbers before ordering. |
| [DIDs](../did/index.html) | Purchased DID phone numbers created through completed DID Orders. |
| [Capacity Pools](../capacity-pool/index.html) | Capacity pools to which purchased channels are assigned. |
| [Common Definitions](../../common-definitions/index.html) | Shared embedded objects such as the Stock Keeping Unit Object. |

On this page