Create Order#
Creates a new DID order to purchase phone numbers (DIDs) based on availability, reservations, or predefined stock-keeping units (SKUs). This request allows you to order specific available DIDs, reserve numbers from a particular region, or request multiple DIDs in bulk.
Request#
HTTP Method: POST
URI Path: /v3/orders
Note
For all returned data attributes, see Order Object.
Body#
Name |
Type |
Is Required? |
Description |
|---|---|---|---|
allow_back_ordering |
|
No |
Specifies whether back-ordering is allowed. The default value is |
items |
|
Yes |
Array of items to be ordered. Each item must contain one of the valid order item attributes. |
callback_url |
|
No |
The HTTP or HTTPS endpoint to which order related events will be delivered. |
callback_method |
|
No |
The HTTP method used for order events. Supported methods: |
external_reference_id |
|
No |
Optional identifier for the order in the customer’s external system. Maximum length is 100 characters. |
Note
If
allow_back_orderingis omitted, the request behaves as ifallow_back_ordering = true.allow_back_ordering = true: Proceeds with the order when items are not in stock.allow_back_ordering = false: Does not proceed with the order when items are not in stock.Insufficient balance validation for
POST /v3/ordersis based on the current order amount only. Existing pending orders are not included in this validation. If the customer’s available balance covers the current order amount, the order can be created successfully even when other pending orders already exist.
See Order callback details for information about
callback_url, callback_method, and the Order callback payload.
Order Item#
Name |
Type |
Is Required? |
Description |
|---|---|---|---|
type |
|
Yes |
Item object type: |
attributes |
One of DID Order Item Attributes, Capacity Order Item Attributes |
Yes |
Order Item Attributes object. |
Order Item Attributes#
Name |
Type |
Is Required? |
Description |
|---|---|---|---|
sku_id |
|
Yes |
The Stock Keeping Unit (SKU) ID representing the DID product being ordered. Send at most one of |
qty |
|
No |
The quantity of DIDs to be ordered. Defaults to |
did_reservation_id |
|
No |
The ID of a previously reserved DID. Use this to complete the purchase of a reserved DID. |
nanpa_prefix_id |
|
No |
The ID representing a North American Numbering Plan (NANPA) prefix (NPA-NXX group). Used for ordering numbers from a specific region. |
billing_cycles_count |
|
No |
The number of billing cycles for which the DID will automatically renew before expiration. Each billing cycle follows the DID service billing period. For monthly billing, |
available_did_id |
|
No |
The ID of a specific available DID to be ordered. Used when ordering a known available number. |
Name |
Type |
Is Required? |
Description |
|---|---|---|---|
qty |
|
No |
Number of channels to buy. Defaults to |
capacity_pool_id |
|
Yes |
Capacity Pool ID. |
Examples#
http
1POST /v3/orders HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
6
7{
8 "data": {
9 "type": "orders",
10 "attributes": {
11 "items": [
12 {
13 "type": "did_order_items",
14 "attributes": {
15 "qty": 1,
16 "sku_id": "a78bb6d8-b05e-4e12-afe6-ad84ac979088"
17 }
18 }
19 ]
20 }
21 }
22}
curl
1curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"items": [{"type": "did_order_items", "attributes": {"qty": 1, "sku_id": "a78bb6d8-b05e-4e12-afe6-ad84ac979088"}}]}, "type": "orders"}}'
response
1HTTP/1.1 201 Created
2Content-Type: application/vnd.api+json
3
4{
5 "data": {
6 "id": "9eeaab6c-b758-41b8-af86-8978a86603a2",
7 "type": "orders",
8 "attributes": {
9 "reference": "FZH-374899",
10 "external_reference_id": null,
11 "amount": "10.0",
12 "status": "pending",
13 "created_at": "2017-06-25T14:56:31.513Z",
14 "description": "DID",
15 "items": [
16 {
17 "type": "did_order_items",
18 "attributes": {
19 "qty": 1,
20 "nrc": "5.0",
21 "mrc": "5.0",
22 "prorated_mrc": true,
23 "billed_from": "2018-08-15",
24 "billed_to": "2018-09-15",
25 "setup_price": "5.0",
26 "monthly_price": "5.0",
27 "did_group_id": "d01704b0-6522-47d5-8865-3398c417ed1d"
28 }
29 }
30 ],
31 "callback_method": null,
32 "callback_url": null
33 }
34 },
35 "meta": {
36 "api_version": "2026-11-19"
37 }
38}
http
1POST /v3/orders HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
6
7{
8 "data": {
9 "type": "orders",
10 "attributes": {
11 "allow_back_ordering": false,
12 "items": [
13 {
14 "type": "did_order_items",
15 "attributes": {
16 "qty": 15,
17 "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
18 }
19 }
20 ]
21 }
22 }
23}
curl
1curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"allow_back_ordering": false, "items": [{"type": "did_order_items", "attributes": {"qty": 15, "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"}}]}, "type": "orders"}}'
response
1HTTP/1.1 201 Created
2Content-Type: application/vnd.api+json
3
4{
5 "data": {
6 "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
7 "type": "orders",
8 "attributes": {
9 "amount": "79.2",
10 "status": "pending",
11 "created_at": "2017-06-25T14:56:31.513Z",
12 "description": "DID",
13 "reference": "NXH-560588",
14 "external_reference_id": null,
15 "items": [
16 {
17 "type": "did_order_items",
18 "attributes": {
19 "qty": 15,
20 "nrc": "5.0",
21 "mrc": "5.0",
22 "prorated_mrc": true,
23 "billed_from": "2018-08-15",
24 "billed_to": "2018-09-15",
25 "setup_price": "5.0",
26 "monthly_price": "5.0",
27 "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
28 }
29 }
30 ],
31 "callback_method": null,
32 "callback_url": null
33 }
34 },
35 "meta": {
36 "api_version": "2026-11-19"
37 }
38}
http
1POST /v3/orders HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
6
7{
8 "data": {
9 "type": "orders",
10 "attributes": {
11 "allow_back_ordering": false,
12 "items": [
13 {
14 "type": "did_order_items",
15 "attributes": {
16 "available_did_id": "7f44285d-20ef-4773-953f-ba012adafed3",
17 "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
18 }
19 }
20 ]
21 }
22 }
23}
curl
1curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"allow_back_ordering": false, "items": [{"type": "did_order_items", "attributes": {"available_did_id": "7f44285d-20ef-4773-953f-ba012adafed3", "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"}}]}, "type": "orders"}}'
response
1HTTP/1.1 201 Created
2Content-Type: application/vnd.api+json
3
4{
5 "data": {
6 "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
7 "type": "orders",
8 "attributes": {
9 "amount": "10.0",
10 "status": "pending",
11 "created_at": "2017-06-25T14:56:31.513Z",
12 "description": "DID",
13 "reference": "NXH-560588",
14 "external_reference_id": null,
15 "items": [
16 {
17 "type": "did_order_items",
18 "attributes": {
19 "qty": 1,
20 "nrc": "5.0",
21 "mrc": "5.0",
22 "prorated_mrc": true,
23 "billed_from": "2018-08-15",
24 "billed_to": "2018-09-15",
25 "setup_price": "5.0",
26 "monthly_price": "5.0",
27 "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
28 }
29 }
30 ],
31 "callback_method": null,
32 "callback_url": null
33 }
34 },
35 "meta": {
36 "api_version": "2026-11-19"
37 }
38}
http
1POST /v3/orders HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
6
7{
8 "data": {
9 "type": "orders",
10 "attributes": {
11 "allow_back_ordering": false,
12 "items": [
13 {
14 "type": "did_order_items",
15 "attributes": {
16 "did_reservation_id": "2a1d98d2-eafd-4332-80d5-5ecd36411eb3",
17 "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
18 }
19 }
20 ]
21 }
22 }
23}
curl
1curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"allow_back_ordering": false, "items": [{"type": "did_order_items", "attributes": {"did_reservation_id": "2a1d98d2-eafd-4332-80d5-5ecd36411eb3", "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"}}]}, "type": "orders"}}'
response
1HTTP/1.1 201 Created
2Content-Type: application/vnd.api+json
3
4{
5 "data": {
6 "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
7 "type": "orders",
8 "attributes": {
9 "amount": "10.0",
10 "status": "pending",
11 "created_at": "2017-06-25T14:56:31.513Z",
12 "description": "DID",
13 "reference": "NXH-560588",
14 "external_reference_id": null,
15 "items": [
16 {
17 "type": "did_order_items",
18 "attributes": {
19 "qty": 1,
20 "nrc": "5.0",
21 "mrc": "5.0",
22 "prorated_mrc": true,
23 "billed_from": "2018-08-15",
24 "billed_to": "2018-09-15",
25 "setup_price": "5.0",
26 "monthly_price": "5.0",
27 "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
28 }
29 }
30 ],
31 "callback_method": null,
32 "callback_url": null
33 }
34 },
35 "meta": {
36 "api_version": "2026-11-19"
37 }
38}
http
1POST /v3/orders HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
6
7{
8 "data": {
9 "type": "orders",
10 "attributes": {
11 "allow_back_ordering": true,
12 "callback_url": "http://example.com",
13 "callback_method": "get",
14 "items": [
15 {
16 "type": "did_order_items",
17 "attributes": {
18 "qty": 1,
19 "sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7"
20 }
21 }
22 ]
23 }
24 }
25}
curl
1curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"allow_back_ordering": true, "callback_method": "get", "callback_url": "http://example.com", "items": [{"type": "did_order_items", "attributes": {"qty": 1, "sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7"}}]}, "type": "orders"}}'
response
1HTTP/1.1 201 Created
2Content-Type: application/vnd.api+json
3
4{
5 "data": {
6 "id": "76b20d6b-f9a8-47bf-8715-bc5fbfd59f55",
7 "type": "orders",
8 "attributes": {
9 "amount": "0.5",
10 "status": "pending",
11 "created_at": "2021-09-06T16:54:28.659Z",
12 "description": "DID",
13 "reference": "TQR-660582",
14 "external_reference_id": null,
15 "items": [
16 {
17 "type": "did_order_items",
18 "attributes": {
19 "qty": 1,
20 "nrc": "0.0",
21 "mrc": "0.5",
22 "prorated_mrc": false,
23 "billed_from": null,
24 "billed_to": null,
25 "setup_price": "0.0",
26 "monthly_price": "0.5",
27 "did_group_id": "fce19421-b6b4-4f31-99f4-699bc0300bbc"
28 }
29 }
30 ],
31 "callback_method": "get",
32 "callback_url": "http://example.com"
33 }
34 },
35 "meta": {
36 "api_version": "2026-11-19"
37 }
38}
http
1POST /v3/orders HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
6
7{
8 "data": {
9 "type": "orders",
10 "attributes": {
11 "items": [
12 {
13 "type": "capacity_order_items",
14 "attributes": {
15 "capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228",
16 "qty": 1
17 }
18 }
19 ]
20 }
21 }
22}
curl
1curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"items": [{"type": "capacity_order_items", "attributes": {"capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228", "qty": 1}}]}, "type": "orders"}}'
response
1HTTP/1.1 201 Created
2Content-Type: application/vnd.api+json
3
4{
5 "data": {
6 "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
7 "type": "orders",
8 "attributes": {
9 "amount": "21.33",
10 "status": "completed",
11 "created_at": "2017-06-25T14:56:31.513Z",
12 "description": "Capacity",
13 "reference": "NXH-560588",
14 "external_reference_id": null,
15 "items": [
16 {
17 "type": "capacity_order_items",
18 "attributes": {
19 "qty": 1,
20 "nrc": "20.0",
21 "mrc": "1.33",
22 "prorated_mrc": true,
23 "billed_from": "2018-08-15",
24 "billed_to": "2018-09-15",
25 "capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228"
26 }
27 }
28 ],
29 "callback_method": null,
30 "callback_url": null
31 }
32 },
33 "meta": {
34 "api_version": "2026-11-19"
35 }
36}
http
1POST /v3/orders HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
6
7{
8 "data": {
9 "type": "orders",
10 "attributes": {
11 "allow_back_ordering": false,
12 "items": [
13 {
14 "type": "did_order_items",
15 "attributes": {
16 "nanpa_prefix_id": "2a1d98d2-eafd-4332-80d5-5ecd36411eb3",
17 "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
18 }
19 }
20 ]
21 }
22 }
23}
curl
1curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"allow_back_ordering": false, "items": [{"type": "did_order_items", "attributes": {"nanpa_prefix_id": "2a1d98d2-eafd-4332-80d5-5ecd36411eb3", "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"}}]}, "type": "orders"}}'
response
1HTTP/1.1 201 Created
2Content-Type: application/vnd.api+json
3
4{
5 "data": {
6 "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
7 "type": "orders",
8 "attributes": {
9 "amount": "10.0",
10 "status": "pending",
11 "created_at": "2017-06-25T14:56:31.513Z",
12 "description": "DID",
13 "reference": "NXH-560588",
14 "external_reference_id": null,
15 "items": [
16 {
17 "type": "did_order_items",
18 "attributes": {
19 "qty": 1,
20 "nrc": "5.0",
21 "mrc": "5.0",
22 "prorated_mrc": true,
23 "billed_from": "2018-08-15",
24 "billed_to": "2018-09-15",
25 "setup_price": "5.0",
26 "monthly_price": "5.0",
27 "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
28 }
29 }
30 ],
31 "callback_method": null,
32 "callback_url": null
33 }
34 },
35 "meta": {
36 "api_version": "2026-11-19"
37 }
38}
When POST /v3/orders fails because the current order amount is greater than the customer’s available balance, the API returns an insufficient balance error.
The error includes meta.total_cost and meta.available_balance. Both values are returned as strings.
http
1POST /v3/orders HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
6
7{
8 "data": {
9 "type": "orders",
10 "attributes": {
11 "allow_back_ordering": false,
12 "items": [
13 {
14 "type": "did_order_items",
15 "attributes": {
16 "sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7",
17 "qty": 1
18 }
19 }
20 ]
21 }
22 }
23}
curl
1curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"allow_back_ordering": false, "items": [{"type": "did_order_items", "attributes": {"sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7", "qty": 1}}]}, "type": "orders"}}'
response
1HTTP/1.1 400 Bad Request
2Content-Type: application/vnd.api+json
3
4{
5 "errors": [
6 {
7 "title": "Insufficient balance",
8 "detail": "Insufficient balance",
9 "code": "400",
10 "status": "400",
11 "meta": {
12 "available_balance": "1.5",
13 "total_cost": "5.67"
14 }
15 }
16 ]
17}
Other Responses#
Code |
Success |
Description |
|---|---|---|
400 |
No |
The body is malformed, or Insufficient Balance Error Object |
422 |
No |
Validation Error Object. The order was rejected. |
401 |
No |
|
403 |
No |
The customer is in read-only mode. Also returned when the access token carries the |
429 |
No |
The request budget of the account for the current window is spent ( |