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 /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 /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.

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.

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	Account funds available before creating an Order.
DID Groups	DID inventory groups that provide Stock Keeping Units for ordering.
Available DIDs	Specific DID phone numbers that can be selected before ordering.
DID Reservations	Temporary reservations used to hold selected DID phone numbers before ordering.
DIDs	Purchased DID phone numbers created through completed DID Orders.
Capacity Pools	Capacity pools to which purchased channels are assigned.
Common Definitions	Shared embedded objects such as the Stock Keeping Unit Object.