# 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](order-object.html).

## Body

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| allow\_back\_ordering | `boolean` | No | Specifies whether back-ordering is allowed. The default value is `true`. If true, the system allows ordering DIDs that are not currently available. If false, only currently available DIDs can be ordered. |
| items | `Array<CreateOrderItem>` | Yes | Array of items to be ordered. Each item must contain one of the valid order item attributes. |
| callback\_url | `string` | No | The HTTP or HTTPS endpoint to which order related events will be delivered. |
| callback\_method | `string` | No | The HTTP method used for order events. Supported methods: `post`, `get`. |
| external\_reference\_id | `string` | No | Optional identifier for the order in the customer's external system. Maximum length is 100 characters. |

Note

- If `allow_back_ordering` is omitted, the request behaves as if `allow_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/orders` is 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](../../callbacks-details.html#callbacks-order-v35) for information about
`callback_url`, `callback_method`, and the Order callback payload.

### Order Item

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| type | `string` | Yes | Item object type: `did_order_items` for DIDs and `capacity_order_items` for Channels. |
| attributes | One of [DID Order Item Attributes](#did-order-item-attributes-v35), [Capacity Order Item Attributes](#capacity-order-item-attributes-v35) | Yes | Order Item Attributes object. |

### Order Item Attributes

DIDCapacity

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| sku\_id | `string` | Yes | The Stock Keeping Unit (SKU) ID representing the DID product being ordered. Send at most one of `qty`, `available_did_id` and `did_reservation_id`: more than one is rejected. With none of them, one number is bought. |
| qty | `integer` | No | The quantity of DIDs to be ordered. Defaults to `1`. |
| did\_reservation\_id | `string` | No | The ID of a previously reserved DID. Use this to complete the purchase of a reserved DID. |
| nanpa\_prefix\_id | `string` | 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 | `integer` | 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, `1` renews the DID for one month, `12` renews it for twelve months, and `0` disables automatic renewal. Allowed values: `0` to `999`. |
| available\_did\_id | `string` | No | The ID of a specific available DID to be ordered. Used when ordering a known available number. |

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| qty | `integer` | No | Number of channels to buy. Defaults to `1`. |
| capacity\_pool\_id | `string` | Yes | Capacity Pool ID. |

## Examples

Simple requestallow\_back\_ordering = falseAvailable DID IDDID Reservation IDCallback ExamplePurchasing
Capacitynanpa\_prefix\_idOrder Insufficient balance

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

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.

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | The body is malformed, or [Insufficient Balance Error Object](../../../specification/errors/index.html#api-insufficient-balance-error-object) |
| 422 | No | [Validation Error Object](../../../specification/errors/index.html#api-validation-error-object). The order was rejected. |
| 401 | No | [Unauthorized](../../authentication.html#authentication-v35) |
| 403 | No | The customer is in read-only mode. Also returned when the access token carries the `read` scope, which does not cover this method (title `Insufficient scope`, `WWW-Authenticate: Bearer error="insufficient_scope"`). See [Scopes](../../authentication.html#authentication-scopes-v35). |
| 429 | No | The request budget of the account for the current window is spent (`too_many_requests`). `Retry-After` gives the number of seconds to wait. |
