Create an Order

The following is an order creation quickstart guide on how to create an order using the modern order framework in the Shipwell Orders API.

Note
  • Shipwell Orders is the modern order framework that we build new functionality upon and the order framework that is documented in the orders section of the Shipwell Developer Portal. We continue to maintain the strong Orders (Legacy/v2) framework for existing customers that utilize this legacy framework, however functionality documented and described in this orders section does not pertain to Orders (Legacy/v2) .
  • Frequently Asked Questions (FAQs) for orders are located here .

Orders are created using the POST /orders endpoint. The Shipwell Orders API supports polymorphic order creation which means purchase orders and any other type of order may be created using the same endpoint with the appropriate request body payload for the order_type.

In the quickstart below, we will walk through creating a purchase order as the most common customer workflow for order creation. For supplier-oriented workflows and for supplier access reference the Supplier Portal guide.

Interactive and Runnable Code

Below is an interactive and runnable Google Colab code notebook that allows you to run code and see the results. The python notebook demonstrates how to create an order.

Order Create Python Notebook

Create Order Request

The example below demonstrates how to create a single line item order with a single ship_from and ship_to for an item that has temperature shipping requirements.

  • The order_number property is a freeform string that may be set to any value, but it must be unique within your account (i.e. two orders cannot have the same order_number ).
  • The optional plan_window , a range or window of time, is set on the order pickup ( ship_from ) and the delivery recipient ( ship_to ). - The shipping_requirements object and the plan_window are utilized for Supplier Portal use cases and should be omitted if you are not utilizing this module or functionality.
    • The plan_window 's start (i.e. 2024-06-17T05:00:00+00:00 ) and end are ISO 8601 date/time strings in the UTC time zone and follow the Shipwell API date/time standards .
    • The plan_window is not required to have an end to the range or window for ship_from pickup or ship_to delivery, but if specified this data will be accessible in the order information.
  • geolocation (i.e. latitude and longitude) , timezone are needed properties for ship_from and ship_to to enable full platform functionality.
  • See the create order API reference for a detailed list of fields or properties for the request and response bodies for order creation.
Example request
About This Request Payload
  • Authorization headers, e.g. Authorization: YOUR_AUTHORIZATION_HEADER , typically take the form of Authorization: Token <user-token> . For more information on API authentication, navigate to the Authenticate documentation.
  • All date/times properties are ISO 8601 date/time strings in the UTC time zone and follow the Shipwell API date/time standards .
  • See the create order API reference for a detailed list of fields or properties for the request and response bodies for order creation.
curljavascriptpython
Copy
Copied
curl -i -X POST \
  'https://sandbox-api.shipwell.com/orders' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
   "custom_data":{},
   "order_number":"QUICKSTART-1",
   "name":"Optional Order Name or Alias",
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "line_2":null,
      "line_3":null,
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "geolocation": {
        "latitude": 41.8855449,
        "longitude": -87.6425198
      },
      "timezone": "America/Chicago",
      "urbanization":null,
      "residential":false,
      "custom_data":null,
      "location_number":null,
      "company_name":"Example Ship From Company Name",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-06-18T17:00:00+00:00",
            "end":null
         }
      }
   },
   "ship_to":{
      "country":"US",
      "line_1":"14 N Moore St",
      "line_2":null,
      "line_3":null,
      "locality":"New York",
      "postal_code":"10013",
      "region":"NY",
      "geolocation": {
        "latitude": 40.7195656,
        "longitude": -74.0066124
      },
      "timezone": "America/New_York",
      "urbanization":null,
      "residential":false,
      "custom_data":null,
      "location_number":null,
      "company_name":"Example Ship To Company Name",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-06-28T17:00:00+00:00",
            "end":"2024-06-28T20:00:00+00:00"
         }
      }
   },
   "description":null,
   "source":null,
   "source_system_id":null,
   "start_date":null,
   "expiration_date":null,
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"TESTPO12349234823-123"
      }
   ],
   "order_type":"PURCHASE_ORDER",
   "status":"READY",
   "items":[
      {
         "custom_data":{
         },
         "description":"Cold item example description",
         "references":[
         ],
         "shipping_requirements":{
            "identifying_marks":[
            ],
            "references":[
            ],
            "tare_weight":null,
            "dimensions":null,
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":{
               "unit":"F",
               "minimum":"5",
               "maximum":"30"
            },
            "freight_class":null,
            "nmfc_item_code":null,
            "nmfc_sub_code":null,
            "country_of_manufacture":null,
            "stackable":true,
            "piece_type":null,
            "total_pieces":null,
            "value_per_piece":null,
            "gross_weight":null,
            "quantity":null,
            "packaging_type":null,
            "handling_unit_id":null,
            "combined_handling_unit_info":null
         },
         "amount":{
            "unit":"BAG",
            "value":"5"
         }
      }
   ],
   "supplier_created_releases_allowed":false,
   "supplier":{
      "name":"Example Ship From Company Name",
      "address":null,
      "identification_codes":[
         
      ],
      "phone_number":null,
      "email":null,
      "supplier_id":null
   },
   "releases":[
   ],
   "released_from_release_id":null,
   "created_from_order_id":null,
   "cancelled_at":null,
   "archived":false
}'
Copy
Copied
const payload = {
   "custom_data":{},
   "order_number":"QUICKSTART-1",
   "name":"Optional Order Name or Alias",
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "line_2":null,
      "line_3":null,
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "geolocation": {
        "latitude": 41.8855449,
        "longitude": -87.6425198
      },
      "timezone": "America/Chicago",
      "urbanization":null,
      "residential":false,
      "custom_data":null,
      "location_number":null,
      "company_name":"Example Ship From Company Name",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-06-18T17:00:00+00:00",
            "end":null
         }
      }
   },
   "ship_to":{
      "country":"US",
      "line_1":"14 N Moore St",
      "line_2":null,
      "line_3":null,
      "locality":"New York",
      "postal_code":"10013",
      "region":"NY",
      "geolocation": {
        "latitude": 40.7195656,
        "longitude": -74.0066124
      },
      "timezone": "America/New_York",
      "urbanization":null,
      "residential":false,
      "custom_data":null,
      "location_number":null,
      "company_name":"Example Ship To Company Name",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-06-28T17:00:00+00:00",
            "end":"2024-06-28T20:00:00+00:00"
         }
      }
   },
   "description":null,
   "source":null,
   "source_system_id":null,
   "start_date":null,
   "expiration_date":null,
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"TESTPO12349234823-123"
      }
   ],
   "order_type":"PURCHASE_ORDER",
   "status":"READY",
   "items":[
      {
         "custom_data":{
         },
         "description":"Cold item example description",
         "references":[
         ],
         "shipping_requirements":{
            "identifying_marks":[
            ],
            "references":[
            ],
            "tare_weight":null,
            "dimensions":null,
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":{
               "unit":"F",
               "minimum":"5",
               "maximum":"30"
            },
            "freight_class":null,
            "nmfc_item_code":null,
            "nmfc_sub_code":null,
            "country_of_manufacture":null,
            "stackable":true,
            "piece_type":null,
            "total_pieces":null,
            "value_per_piece":null,
            "gross_weight":null,
            "quantity":null,
            "packaging_type":null,
            "handling_unit_id":null,
            "combined_handling_unit_info":null
         },
         "amount":{
            "unit":"BAG",
            "value":"5"
         }
      }
   ],
   "supplier_created_releases_allowed":false,
   "supplier":{
      "name":"Example Ship From Company Name",
      "address":null,
      "identification_codes":[
         
      ],
      "phone_number":null,
      "email":null,
      "supplier_id":null
   },
   "releases":[
   ],
   "released_from_release_id":null,
   "created_from_order_id":null,
   "cancelled_at":null,
   "archived":false
};

const basePath = "";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/orders`,
  {
    method: "POST",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const data = await resp.json();
console.log(data);
Copy
Copied
import requests

base_path = ""
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/orders"

headers = {
    "Content-Type": "application/json",
    "Authorization": "YOUR_AUTHORIZATION_HEADER",
}

payload = {
   "custom_data": {},
   "order_number": "QUICKSTART-1",
   "name": "Optional Order Name or Alias",
   "ship_from": {
      "country": "US",
      "line_1": "567 W Lake St",
      "line_2": None,
      "line_3": None,
      "locality": "Chicago",
      "postal_code": "60661",
      "region": "IL",
      "geolocation": {
        "latitude": 41.8855449,
        "longitude": -87.6425198
      },
      "timezone": "America/Chicago",
      "urbanization": None,
      "residential": False,
      "custom_data": None,
      "location_number": None,
      "company_name": "Example Ship From Company Name",
      "references": [
         
      ],
      "shipping_requirements": {
         "plan_window": {
            "start": "2024-06-18T17:00:00+00:00",
            "end": None
         }
      }
   },
   "ship_to": {
      "country": "US",
      "line_1": "14 N Moore St",
      "line_2": None,
      "line_3": None,
      "locality": "New York",
      "postal_code": "10013",
      "region": "NY",
      "geolocation": {
        "latitude": 40.7195656,
        "longitude": -74.0066124
      },
      "timezone": "America/New_York",
      "urbanization": None,
      "residential": False,
      "custom_data": None,
      "location_number": None,
      "company_name": "Example Ship To Company Name",
      "references": [
         
      ],
      "shipping_requirements": {
         "plan_window": {
            "start": "2024-06-28T17:00:00+00:00",
            "end": "2024-06-28T20:00:00+00:00"
         }
      }
   },
   "description": None,
   "source": None,
   "source_system_id": None,
   "start_date": None,
   "expiration_date": None,
   "references": [
      {
         "qualifier": "PURCHASE_ORDER_NUMBER",
         "value": "TESTPO12349234823-123"
      }
   ],
   "order_type": "PURCHASE_ORDER",
   "status": "READY",
   "items": [
      {
         "custom_data": {
         },
         "description": "Cold item example description",
         "references": [
         ],
         "shipping_requirements": {
            "identifying_marks": [
            ],
            "references": [
            ],
            "tare_weight": None,
            "dimensions": None,
            "volume": None,
            "customer_reference_number": None,
            "hazmat": None,
            "temperature": {
               "unit": "F",
               "minimum": "5",
               "maximum": "30"
            },
            "freight_class": None,
            "nmfc_item_code": None,
            "nmfc_sub_code": None,
            "country_of_manufacture": None,
            "stackable": True,
            "piece_type": None,
            "total_pieces": None,
            "value_per_piece": None,
            "gross_weight": None,
            "quantity": None,
            "packaging_type": None,
            "handling_unit_id": None,
            "combined_handling_unit_info": None
         },
         "amount": {
            "unit": "BAG",
            "value": "5"
         }
      }
   ],
   "supplier_created_releases_allowed": False,
   "supplier": {
      "name": "Example Ship From Company Name",
      "address": None,
      "identification_codes": [
         
      ],
      "phone_number": None,
      "email": None,
      "supplier_id": None
   },
   "releases": [
   ],
   "released_from_release_id": None,
   "created_from_order_id": None,
   "cancelled_at": None,
   "archived": False
}

response = requests.post(target_url, headers=headers, json=payload)
data = response.json()
print(data)

Create Order Response

Example response
About This Response Payload
  • The system will autogenerate unique identifiers for the order and each line item in the order. This will allow other API operations to utilize the order id , order item id , etc.
  • See the create API reference for a detailed list of fields or properties for the response payload body for order creation.
Copy
Copied
{
   "custom_data":{
      
   },
   "order_number":"QUICKSTART-1",
   "name":"Optional Order Name or Alias",
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "line_2":null,
      "line_3":null,
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "geolocation": {
        "latitude": 41.8855449,
        "longitude": -87.6425198
      },
      "timezone": "America/Chicago",
      "urbanization":null,
      "residential":false,
      "custom_data":null,
      "location_number":null,
      "company_name":"Example Ship From Company Name",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-06-18T17:00:00+00:00",
            "end":null
         }
      }
   },
   "ship_to":{
      "country":"US",
      "line_1":"14 N Moore St",
      "line_2":null,
      "line_3":null,
      "locality":"New York",
      "postal_code":"10013",
      "region":"NY",
      "urbanization":null,
      "residential":false,
      "custom_data":null,
      "location_number":null,
      "company_name":"Example Ship To Company Name",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-06-28T17:00:00+00:00",
            "end":"2024-06-28T20:00:00+00:00"
         }
      }
   },
   "description":null,
   "source":null,
   "source_system_id":null,
   "start_date":null,
   "expiration_date":null,
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"TESTPO12349234823-123"
      }
   ],
   "id":"01HW34Q13HTT9PXT2THJ1VMTPH",
   "order_type":"PURCHASE_ORDER",
   "status":"READY",
   "items":[
      {
         "custom_data":{
            
         },
         "description":"Cold item example description",
         "references":[
            
         ],
         "shipping_requirements":{
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":null,
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":{
               "unit":"F",
               "minimum":"5",
               "maximum":"30"
            },
            "freight_class":null,
            "nmfc_item_code":null,
            "nmfc_sub_code":null,
            "country_of_manufacture":null,
            "stackable":true,
            "piece_type":null,
            "total_pieces":null,
            "value_per_piece":null,
            "gross_weight":null,
            "quantity":null,
            "packaging_type":null,
            "handling_unit_id":null,
            "combined_handling_unit_info":null
         },
         "amount":{
            "unit":"BAG",
            "value":"5"
         },
         "id":"01HW34Q13VTSSBMNSX29EJH903",
         "available_amount":{
            "unit":"BAG",
            "value":"5"
         }
      }
   ],
   "supplier_created_releases_allowed":false,
   "supplier":{
      "name":"Example Ship From Company Name",
      "address":null,
      "identification_codes":[
         
      ],
      "phone_number":null,
      "email":null,
      "supplier_id":null
   },
   "releases":[
      
   ],
   "released_from_release_id":null,
   "created_from_order_id":null,
   "cancelled_at":null,
   "archived":false
}

Minimal Create Order Request

Example minimal order request
About This Request Payload
  • This example represents a streamlined basic starter order.
  • The example below is minimal payload for order creation and extra illustrative properties beyond a single order line item have been removed from this payload.
  • Orders may be composed and updated by starting with a basic order then updating the order with additional information.
  • See the create order API reference for a detailed list of fields or properties for the request and response bodies for order creation.
Copy
Copied
{
   "order_number":"QUICKSTART-BASIC-STARTER-MINIMAL-1",
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "geolocation": {
        "latitude": 41.8855449,
        "longitude": -87.6425198
      },
      "timezone": "America/Chicago"
   },
   "ship_to":{
      "country":"US",
      "line_1":"14 N Moore St",
      "locality":"New York",
      "postal_code":"10013",
      "region":"NY"
   },
   "order_type":"PURCHASE_ORDER",
   "items":[
      {
         "amount":{
            "unit":"BAG",
            "value":"5"
         }
      }
   ]
}
Copyright © Shipwell 2025. All right reserved.