# 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-v34) for information about
`callback_url`, `callback_method`, and the Order callback payload.

### Order Item

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| type | `string` | No | 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-v34),   [Capacity Order Item Attributes](#capacity-order-item-attributes-v34) | No | 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. Must be used with one of the optional parameters: `qty`, `available_did_id` or `did_reservation_id`. |
| qty | `integer` | Conditional | The quantity of DIDs to be ordered. Required when ordering multiple DIDs in bulk. Not needed if ordering a specific `available_did_id` or `did_reservation_id`. |
| 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. |
| prorate\_days\_qty | `integer` | No | The number of service days to be included in the order, if prorated billing is applicable. |

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| qty | `integer` | No | Quantity of DIDs. |
| capacity\_pool\_id | `string` | Yes | Capacity Pool ID. |

Attention

Please note that the `prorate_days_qty` attribute will be ignored if prorated billing is not enabled for your DIDWW
account. To enable this billing option, please contact the Sales department via email at
[sales@didww.com](mailto:sales%40didww.com).

## Examples

Simple requestallow\_back\_ordering = falseAvailable DID IDDID Reservation IDCallback ExamplePurchasing
Capacitynanpa\_prefix\_idAvailable DID with prorate\_days\_qtyOrder Insufficient balance

[[DIDWW-API-EXAMPLE-START]]

http

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "attributes": {
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "qty": 1,
            "sku_id": "a78bb6d8-b05e-4e12-afe6-ad84ac979088"
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"items": [{"type": "did_order_items", "attributes": {"qty": 1, "sku_id": "a78bb6d8-b05e-4e12-afe6-ad84ac979088"}}]}, "type": "orders"}}'
```

response

```
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "9eeaab6c-b758-41b8-af86-8978a86603a2",
    "type": "orders",
    "attributes": {
      "reference": "FZH-374899",
      "external_reference_id": null,
      "amount": "79.2",
      "status": "pending",
      "created_at": "2017-06-25T14:56:31.513Z",
      "description": "DID",
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "qty": 15,
            "nrc": "5.00",
            "mrc": "5.00",
            "prorated_mrc": true,
            "billed_from": "2018-08-15",
            "billed_to": "2018-09-15",
            "did_group_id": "d01704b0-6522-47d5-8865-3398c417ed1d"
          }
        }
      ]
    }
  }
}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "attributes": {
      "allow_back_ordering": false,
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "qty": 15,
            "sku_id": "b6d9d793-578d-42d3-bc33-73dd8155e615"
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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

```
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
    "type": "orders",
    "attributes": {
      "amount": "79.2",
      "status": "pending",
      "created_at": "2017-06-25T14:56:31.513Z",
      "description": "DID",
      "reference": "NXH-560588",
      "external_reference_id": null,
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "qty": 15,
            "nrc": "5.00",
            "mrc": "5.00",
            "prorated_mrc": true,
            "billed_from": "2018-08-15",
            "billed_to": "2018-09-15",
            "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
          }
        }
      ]
    }
  }
}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "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"
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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

```
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
    "type": "orders",
    "attributes": {
      "amount": "10.0",
      "status": "pending",
      "created_at": "2017-06-25T14:56:31.513Z",
      "description": "DID",
      "reference": "NXH-560588",
      "external_reference_id": null,
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "qty": 1,
            "nrc": "5.00",
            "mrc": "5.00",
            "prorated_mrc": true,
            "billed_from": "2018-08-15",
            "billed_to": "2018-09-15",
            "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
          }
        }
      ]
    }
  }
}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "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"
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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

```
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
    "type": "orders",
    "attributes": {
      "amount": "10.0",
      "status": "pending",
      "created_at": "2017-06-25T14:56:31.513Z",
      "description": "DID",
      "reference": "NXH-560588",
      "external_reference_id": null,
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "qty": 1,
            "nrc": "5.00",
            "mrc": "5.00",
            "prorated_mrc": true,
            "billed_from": "2018-08-15",
            "billed_to": "2018-09-15",
            "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
          }
        }
      ]
    }
  }
}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "attributes": {
      "allow_back_ordering": true,
      "callback_url": "http://example.com",
      "callback_method": "get",
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "qty": 1,
            "sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7"
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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

```
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
    "data": {
        "id": "76b20d6b-f9a8-47bf-8715-bc5fbfd59f55",
        "type": "orders",
        "attributes": {
            "amount": "0.5",
            "status": "pending",
            "created_at": "2021-09-06T16:54:28.659Z",
            "description": "DID",
            "reference": "TQR-660582",
            "external_reference_id": null,
            "items": [
                {
                    "type": "did_order_items",
                    "attributes": {
                        "qty": 1,
                        "nrc": "0.0",
                        "mrc": "0.5",
                        "prorated_mrc": false,
                        "billed_from": null,
                        "billed_to": null,
                        "did_group_id": "fce19421-b6b4-4f31-99f4-699bc0300bbc"
                    }
                }
            ],
            "callback_method": "get",
            "callback_url": "http://example.com"
        }
    },
    "meta": {
        "api_version": "2026-04-16"
    }
}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "attributes": {
      "items": [
        {
          "type": "capacity_order_items",
          "attributes": {
            "capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228",
            "qty": 1
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"items": [{"type": "capacity_order_items", "attributes": {"capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228", "qty": 1}}]}, "type": "orders"}}'
```

response

```
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
    "type": "orders",
    "attributes": {
      "amount": "21.33",
      "status": "completed",
      "created_at": "2017-06-25T14:56:31.513Z",
      "description": "Capacity",
      "reference": "NXH-560588",
      "external_reference_id": null,
      "items": [
        {
          "type": "capacity_order_items",
          "attributes": {
            "qty": 1,
            "nrc": "20.0",
            "mrc": "1.33",
            "prorated_mrc": true,
            "billed_from": "2018-08-15",
            "billed_to": "2018-09-15",
            "capacity_pool_id": "c5f87307-7c80-417c-9ec3-18e0241c4228"
          }
        }
      ]
    }
  }
}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "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"
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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

```
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "75dae051-7508-4a9b-ab1b-9bbd75de18c5",
    "type": "orders",
    "attributes": {
      "amount": "10.0",
      "status": "pending",
      "created_at": "2017-06-25T14:56:31.513Z",
      "description": "DID",
      "reference": "NXH-560588",
      "external_reference_id": null,
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "qty": 1,
            "nrc": "5.00",
            "mrc": "5.00",
            "prorated_mrc": true,
            "billed_from": "2018-08-15",
            "billed_to": "2018-09-15",
            "did_group_id": "a7b2abcb-6251-475f-b6e0-fd9acf2579ef"
          }
        }
      ]
    }
  }
}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "attributes": {
      "allow_back_ordering": false,
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "available_did_id": "6c82282c-8193-43ca-9876-8ddef1ade253",
            "sku_id": "644c2449-0e23-4a67-9f81-565ad5137bb6",
            "prorate_days_qty": 10
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"allow_back_ordering": false, "items": [{"type": "did_order_items", "attributes": {"available_did_id": "6c82282c-8193-43ca-9876-8ddef1ade253", "sku_id": "644c2449-0e23-4a67-9f81-565ad5137bb6", "prorate_days_qty": 10}}]}, "type": "orders"}}'
```

response

```
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

        {
    "data": {
        "id": "3276e7e6-559a-4344-95d8-1a83657f46ba",
        "type": "orders",
        "attributes": {
            "amount": "0.03",
            "status": "pending",
            "created_at": "2022-03-04T07:45:24.471Z",
            "description": "DID",
            "reference": "EHF-778400",
            "external_reference_id": null,
            "items": [
                {
                    "type": "did_order_items",
                    "attributes": {
                        "qty": 1,
                        "nrc": "0.0",
                        "mrc": "0.03",
                        "prorated_mrc": true,
                        "billed_from": null,
                        "billed_to": null,
                        "did_group_id": "239e74ad-9da1-4802-90dd-e1ce148da19e"
                    }
                }
            ],
            "callback_method": null,
            "callback_url": null
        }
    },
    "meta": {
        "api_version": "2026-04-16"
    }
}
```

[[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

```
POST /v3/orders HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
  "data": {
    "type": "orders",
    "attributes": {
      "allow_back_ordering": false,
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "sku_id": "a7a7ffae-14cc-4e24-8682-6083a050fae7",
            "qty": 1
          }
        }
      ]
    }
  }
}
```

curl

```
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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

```
HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "title": "Insufficient balance",
      "detail": "Insufficient balance",
      "code": "400",
      "status": "400",
      "meta": {
        "available_balance": "1.5",
        "total_cost": "5.67"
      }
    }
  ]
}
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | [Insufficient Balance Error Object](../../../specification/errors/index.html#api-insufficient-balance-error-object) |
| 404 | No | [Not Found](../../../specification/errors/index.html#api-not-found) |
| 401 | No | [Unauthorized](../../../configuration.html#api-key) |

On this page