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	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 Callback details for information about callback_url and callback_method.

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, Capacity Order Item Attributes	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 that this DID will automatically renew before expiration.
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.

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 .

Examples

Simple requestallow_back_ordering = falseAvailable DID IDDID Reservation IDCallback ExamplePurchasing Capacitynanpa_prefix_idAvailable DID with prorate_days_qtyOrder Insufficient balance

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"
          }
        }
      ]
    }
  }
}

Other Responses

Code	Success	Description
400	No	Insufficient Balance Error Object
404	No	Not Found
401	No	Unauthorized