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 theorders
section of the Shipwell Developer Portal. We continue to maintain the strongOrders (Legacy/v2)
framework for existing customers that utilize this legacy framework, however functionality documented and described in thisorders
section does not pertain toOrders (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.
- Shipwell Google Colab Notebook for Creating an Order
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 freeformstring
that may be set to any value, but it must be unique within your account (i.e. two orders cannot have the sameorder_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
). - Theshipping_requirements
object and theplan_window
are utilized for Supplier Portal use cases and should be omitted if you are not utilizing this module or functionality.-
The
plan_window
'sstart
(i.e.2024-06-17T05:00:00+00:00
) andend
areISO 8601
date/timestrings
in theUTC
time zone and follow the Shipwell API date/time standards . -
The
plan_window
is not required to have anend
to the range or window forship_from
pickup orship_to
delivery, but if specified this data will be accessible in the order information.
-
The
-
geolocation
(i.e.latitude
andlongitude
) ,timezone
are needed properties forship_from
andship_to
to enable full platform functionality.-
Shipwell provides an
address validation and parsing endpoint
that will parse an address
string
into a structured address with the latitude, longitude, and time zone of the address. This is useful if you have one-line address strings and/or want to enrich your address information withgeocoding (latitude and longitude)
and time zone information.
-
Shipwell provides an
address validation and parsing endpoint
that will parse an address
- 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 ofAuthorization: Token <user-token>
. For more information on API authentication, navigate to the Authenticate documentation. -
All date/times properties are
ISO 8601
date/timestrings
in theUTC
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.
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
}'
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);
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.
{
"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.
{
"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"
}
}
]
}