Create Order with Handling Unit Information

Overview

This scenario demonstrates how to create a purchase order (one of the order types) in the modern Shipwell Orders API framework that contains handling unit information. Combining or grouping order line items by handling units allows organizations to mix different order and product line items into the same handling unit (i.e. mix and match different line items or products in an order together in a pallet, case, etc. so they ship together). This functionality may be leveraged by both customers and their suppliers with Shipwell's Supplier Collaboration Portal and the steps are similar for sales orders (as a different order_type). For more information on the differences between pieces, packages, items, etc. see the Order FAQs.

  • An order may contain zero or more specified handling units. When line items are combined into a handling unit the system calls this a combined_handling_unit .
  • All line items with the same handling_unit_id are treated as being on the same handling unit. This includes line items that are within the same order or line items from different orders.
  • An order line item may be associated with zero or one handling unit by handling_unit_id
  • handling_unit_id is a custom string with a maximum length of 48 characters
    • When using the Shipwell admin user interface with handling units, the system will generate a handling_unit_id on your behalf.
    • When using the API, the handling_unit_id may be any string value that you set and will typically come from your ERP .
    • The handling_unit_id format is not validated beyond the maximum length in the API.
    • If you are creating the handling unit with the API instead of through the Shipwell admin user interface and your ERP does not generate an identifier for the handling unit then we recommend the following:
    • Randomly generating a unique string like a ULID or UUID (this random generation per handling unit will also work if you have multiple handling units per order).
  • combined_handling_unit_info represents the "combined" information (dimensions, weight, etc.) of all line items that are combined into the same mixed handling unit.
    • Example:
      • Three line items are combined into the same combined handling unit and have the same handling_unit_id :
        • Jeans, 15 CASE, 25 LB, 20x20x22 IN
        • Shirts, 18 BAG, 30.5 LB, 20x20x20 IN
        • Dress, 10 CASE, 38 LB, 18x18x18 IN
      • These items fit on 2 mixed pallets that has a freight class of 92.5, dimensions of 40x48x60 IN, and an aggregate weight of the two pallets of 1304 LB.
      • All three line items would have the same orders.items.shipping_requirements.handling_unit_id
      • All three line items would have the same orders.items.shipping_requirements.combined_handling_unit_info :
        Example JSON
        Copy
        Copied
        "combined_handling_unit_info": {
   "quantity": 2,
   "packaging_type": "PALLET",
   "freight_class": "92.5",
   "dimensions": {
     "unit": "IN",
     "length": "40",
     "height": "60",
     "width": "48"
    },
    "net_weight": {
      "unit": "LB",
      "value": "1304"
    }
}

Steps

1. Authenticate and Receive API Token

Authenticate to the API using these steps.

Note

Authorization HTTP headers in API requests, 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.

2. Create Address Book Entry

  • Create an address book entry for the receiving/ship-to location for the order with the details of the location, warehouse, site, etc.
  • After successfully creating the address book or location entry, you will receive a unique identifier to reference the address
  • Storing the details, equipment, and hours of the location allows you to easily reuse the location information in other orders, shipments, and use cases.
  • The following properties from the address book entry / location are used in creating the order in this scenario:
    • address book entry / location id
    • address_1
    • city
    • state
    • postal_code
    • country
Example request
About This Request Payload
  • This request creates an address book entry for a location with a dock or forklift that requires an appointment for pickup or delivery.
  • See the address book guide for more information on creating, updating, and retrieving addresses in the platform through the API.
  • See the create address book/locations API reference for a detailed list of fields or properties for the request and response bodies for address/location creation.
curljavascriptpython
Copy
Copied
curl --location --request POST 'https://sandbox-api.shipwell.com/v2/address-book/' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_AUTHORIZATION_HEADER' \
--data-raw '{
    "location_name": "IC-TEST-SAMPLE",
    "notes": "Location ICS-TEST Notes",
    "address": {
        "address_1": "10200 Park Meadows Dr",
        "address_2": null,
        "city": "Lone Tree",
        "state_province": "CO",
        "postal_code": "80124",
        "country": "US"
    },
    "point_of_contacts": [
        {
            "first_name": "SK",
            "last_name": "KM",
            "job_title": null,
            "phone_number": "+15555555555",
            "email": "ics@shipwell.com",
            "preferences": {
                "cancellation": true,
                "delayed": true,
                "delivered": true,
                "eta_changed": true,
                "picked_up": true,
                "receive_bol_on_shipment_booked": false,
                "shipment_booked": true,
                "trailer_assigned": false
            }
        }
    ],
    "location_type": {
        "id": 1,
        "name": "Business (with dock or forklift)"
    },
    "company_name": "TEST-IC",
    "is_default_origin": true,
    "external_reference": "FINT",
    "default_appointment_type": {
        "id": 3,
        "code": "BY_APPT",
        "name": "By appointment"
    }
}'
Copy
Copied
const payload = {
    "location_name": "IC-TEST-SAMPLE",
    "notes": "Location ICS-TEST Notes",
    "address": {
        "address_1": "10200 Park Meadows Dr",
        "address_2": null,
        "city": "Lone Tree",
        "state_province": "CO",
        "postal_code": "80124",
        "country": "US"
    },
    "point_of_contacts": [
        {
            "first_name": "SK",
            "last_name": "KM",
            "job_title": null,
            "phone_number": "+15555555555",
            "email": "ics@shipwell.com",
            "preferences": {
                "cancellation": true,
                "delayed": true,
                "delivered": true,
                "eta_changed": true,
                "picked_up": true,
                "receive_bol_on_shipment_booked": false,
                "shipment_booked": true,
                "trailer_assigned": false
            }
        }
    ],
    "location_type": {
        "id": 1,
        "name": "Business (with dock or forklift)"
    },
    "company_name": "TEST-IC",
    "is_default_origin": true,
    "external_reference": "FINT",
    "default_appointment_type": {
        "id": 3,
        "code": "BY_APPT",
        "name": "By appointment"
    }
};

const basePath = "/v2";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/address-book/`,
  {
    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 = "/v2"
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/address-book/"

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

payload = {
    "location_name": "IC-TEST-SAMPLE",
    "notes": "Location ICS-TEST Notes",
    "address": {
        "address_1": "10200 Park Meadows Dr",
        "address_2": None,
        "city": "Lone Tree",
        "state_province": "CO",
        "postal_code": "80124",
        "country": "US"
    },
    "point_of_contacts": [
        {
            "first_name": "SK",
            "last_name": "KM",
            "job_title": None,
            "phone_number": "+15555555555",
            "email": "ics@shipwell.com",
            "preferences": {
                "cancellation": True,
                "delayed": True,
                "delivered": True,
                "eta_changed": True,
                "picked_up": True,
                "receive_bol_on_shipment_booked": False,
                "shipment_booked": True,
                "trailer_assigned": False
            }
        }
    ],
    "location_type": {
        "id": 1,
        "name": "Business (with dock or forklift)"
    },
    "company_name": "TEST-IC",
    "is_default_origin": True,
    "external_reference": "FINT",
    "default_appointment_type": {
        "id": 3,
        "code": "BY_APPT",
        "name": "By appointment"
    }
}

response = requests.put(target_url, headers=headers, json=payload)
data = response.json()
print(data)
Example response
About This Response Payload
  • An address book entry / location id is generated by the system on successful creation of an address book entry
  • Use address book entry / location id when API endpoints accept the address book entry id as a way to reference the location hours, location type, etc. instead of needing to specify this information.
Copy
Copied
{
   "id":"a7ee2a4b-0d55-4202-b0f1-e8326bfe6109",
   "location_name":"IC-TEST-SAMPLE",
   "dock_hours_start":null,
   "dock_hours_end":null,
   "open_sunday":false,
   "sunday_open_time":null,
   "sunday_close_time":null,
   "open_monday":false,
   "monday_open_time":null,
   "monday_close_time":null,
   "open_tuesday":false,
   "tuesday_open_time":null,
   "tuesday_close_time":null,
   "open_wednesday":false,
   "wednesday_open_time":null,
   "wednesday_close_time":null,
   "open_thursday":false,
   "thursday_open_time":null,
   "thursday_close_time":null,
   "open_friday":false,
   "friday_open_time":null,
   "friday_close_time":null,
   "open_saturday":false,
   "saturday_open_time":null,
   "saturday_close_time":null,
   "notes":"Location ICS-TEST Notes",
   "address":{
      "id":"e9ef2cff-dea7-47bc-89f8-3c578b29f34b",
      "address_1":"10200 Park Meadows Dr",
      "address_2":null,
      "city":"Lone Tree",
      "state_province":"CO",
      "postal_code":"80124",
      "country":"US",
      "phone_number":null,
      "latitude":39.5475078,
      "longitude":-104.8750859,
      "timezone":"America/Denver",
      "formatted_address":"10200 Park Meadows Dr, Lone Tree, CO 80124, US",
      "created_at":"2024-06-06T21:17:57.841775Z",
      "updated_at":"2024-06-06T21:17:57.972259Z"
   },
   "point_of_contacts":[
      {
         "id":"499e1f28-a328-4d2d-9e71-689cbdd13640",
         "first_name":"SK",
         "last_name":"KM",
         "job_title":null,
         "phone_number":"+15555555555",
         "email":"ics@shipwell.com",
         "preferences":{
            "cancellation":true,
            "delayed":true,
            "delivered":true,
            "eta_changed":true,
            "picked_up":true,
            "receive_bol_on_shipment_booked":false,
            "shipment_booked":true,
            "trailer_assigned":false
         },
         "created_at":"2024-06-06T21:17:57.997338Z",
         "updated_at":"2024-06-06T21:17:58.008169Z"
      }
   ],
   "location_type":{
      "id":1,
      "name":"Business (with dock or forklift)"
   },
   "created_at":"2024-06-06T21:17:57.988813Z",
   "updated_at":"2024-06-06T21:17:57.992869Z",
   "company_name":"TEST-IC",
   "is_default_origin":true,
   "accessorials":[
      
   ],
   "external_reference":"FINT",
   "facility_id":null,
   "default_appointment_type":{
      "id":3,
      "code":"BY_APPT",
      "name":"By appointment"
   },
   "dock_external_id":null,
   "load_capacity_schedule":{
      "monday":null,
      "tuesday":null,
      "wednesday":null,
      "thursday":null,
      "friday":null,
      "saturday":null,
      "sunday":null,
      "interval":null,
      "interval_capacity":null,
      "open_on_us_holidays":null,
      "open_on_weekends":null
   },
   "account_reps":[
      
   ]
}

3. Get Custom Fields for Company

  • Companies may have custom data entry fields that are key-value pairs of custom data associated with an order, shipment, line item, etc. Learn more about custom data entry fields here .
  • If you want to set any of the custom data entry fields value(s) in the API without the user interface, then you will need the id of the custom data entry field.
  • Using the custom data entry field's id as the key, you may set the value when creating an order .
Example request
curljavascriptpython
Copy
Copied
curl --location --request GET \ 
'https://sandbox-api.shipwell.com/v2/companies/{companyId}/custom-fields/' \
--header 'Authorization: YOUR_AUTHORIZATION_HEADER'
Copy
Copied
const basePath = "/v2";
const host = "sandbox-api.shipwell.com";
const companyId = "YOUR_COMPANY_ID";
const resp = await fetch(
  `https://${host}${basePath}/companies/${companyId}/custom-fields/`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

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

base_path = ""
host = "sandbox-api.shipwell.com"
company_id = "YOUR_COMPANY_ID"
target_url = "https://" + host + base_path + "/companies/" + company_id + "/custom-fields/"

headers = {
    "Accept-Type": "application/json"
}

response = requests.get(target_url, headers=headers)
data = response.json()
print(data)
Example response
Copy
Copied
{
    "total_count": 2,
    "total_pages": 1,
    "page_size": 20,
    "results": [
        {
            "id": "b0466a0c-27f7-4f6b-bdb9-093d5669f458",
            "created_at": "2023-11-22T14:20:07.863017Z",
            "updated_at": "2024-06-30T17:37:21.245760Z",
            "entity_types": [
                "shipment",
                "purchase_order"
            ],
            "company": "{YOUR_COMPANY_ID}",
            "name": "free_form_custom_field_id",
            "label": "Free Form Custom Field",
            "required": false,
            "default_value": "",
            "field_type": "STRING",
            "display_order": 0,
            "allowed_values": [],
            "allow_carrier_edit": false,
            "allow_carrier_view": false,
            "ui_enabled": true,
            "key": "free_form_custom_field_id"
        },
        {
            "id": "ccea681d-60f9-41e3-b052-c75370255753",
            "created_at": "2023-11-22T14:20:07.863017Z",
            "updated_at": "2024-06-30T17:37:21.245760Z",
            "entity_types": [
                "shipment",
                "purchase_order"
            ],
            "company": "{YOUR_COMPANY_ID}",
            "name": "another_custom_field_id",
            "label": "Another Custom Field",
            "required": false,
            "default_value": "",
            "field_type": "STRING",
            "display_order": 0,
            "allowed_values": [],
            "allow_carrier_edit": false,
            "allow_carrier_view": false,
            "ui_enabled": true,
            "key": "another_custom_field_id"
        }
    ]
}

4. Create Order

Create an order (purchase order) that references the data from the address book entry / location (i.e. the order will have a reference to information like the hours and equipment of the location) and values for custom data entry fields (without needing to utilize the user interface to enter these values).

Use Case Examples
  • Core Example
    • In the following example in the requests and responses, the customer is only concerned with ensuring that items are grouped onto the same PALLET , so the amount type is PALLET and the packaging_type is PALLET .
    • This is a common use case where the customer is primarily concerned with grouping different products or line items onto the same PALLET (and potentially other items onto another PALLET / handling_unit )
  • Alternate Examples
    • Two layers of packaging and grouping that combine CASE and PALLET is also a common way to group items into handling units. For example:
    • 8 CASE s ( amount ) that fit on a PALLET (`packaging_type)
    • Three layers of packaging and grouping is an alternate way of grouping items which some customers utilize. For example:
      • 100 flowers ( amount , item , UNIT s) that fit into 4 CASE s ( piece ) that go on a PALLET ( packaging_type ).
Example request
About This Request Payload

In this method of specifying the combined_handling_unit information, on the combined_handling_unit object or property of the order:

  • quantity is set to 1 (items are placed on the same handling unit)
  • packaging_type is set to PALLET
  • gross_weight represents the aggregate weight of all pieces for that line item
  • length , width , and height linear dimensions represent the dimensions of the packaging_type (i.e PALLET )
  • Address book entries / locations have an IANA time zone calculated by the system, i.e. America/Chicago , America/New_York , etc. based on the geolocation information of the address.
  • Order stops (i.e. ship_to and ship_from ) may have reference data associated with the stop . The available qualifier (e.g. ADDRESS_BOOK_ENTRY_ID ) types of references are available in the API reference here .
  • All date/times properties are ISO 8601 date/time strings and follow the Shipwell API date/time standards . Date/time offsets, etc. are supported, but we recommend sending or adjusting dates/times passed in to be in the UTC time zone.
curljavascriptpython
Copy
Copied
curl --location --request POST 'https://sandbox-api.shipwell.com/orders/' \
--header 'Authorization: YOUR_AUTHORIZATION_HEADER' \
--header 'Content-Type: application/json' \
--data-raw '{
            "custom_data": {
                "shipwell_custom_data": {
                    "purchase_order": {
                        "b0466a0c-27f7-4f6b-bdb9-093d5669f458": "GRN",
                        "ccea681d-60f9-41e3-b052-c75370255753": "Trade Number"
                    }
                }
            },
            "order_number": "Order-45690",
            "ship_to": {
                "country": "US",
                "line_1": "Debartolo Dr",
                "line_2": null,
                "line_3": null,
                "locality": "North Jackson",
                "postal_code": "44451",
                "region": "OH",
                "urbanization": null,
                "residential": false,
                "geolocation": null,
                "custom_data": {
                    "shipwell_custom_data": {
                        "purchase_order_stop": {}
                    }
                },
                "timezone": "America/New_York",
                "location_number": null,
                "company_name": "SK",
                "references": [
                    {
                        "qualifier": "ADDRESS_BOOK_ENTRY_ID",
                        "value": "{YOUR_ADDRESS_BOOK_ENTRY_ID}"
                    }
                ],
                "shipping_requirements": {
                    "plan_window": {
                        "start": "2024-04-22T16:00:00+00:00",
                        "end": "2024-04-22T16:00:00+00:00"
                    }
                }
            },
            "name": "Order name",
            "ship_from": {
                "country": "US",
                "line_1": "7175 Kit Kat Rd, Elkridge, MD 21075, US",
                "line_2": null,
                "line_3": null,
                "locality": "Elkridge",
                "postal_code": null,
                "region": "CO",
                "urbanization": null,
                "residential": false,
                "geolocation": null,
                "custom_data": {
                    "shipwell_custom_data": {
                        "purchase_order_stop": {}
                    }
                },
                "timezone": "America/New_York",
                "location_number": null,
                "company_name": "ICS",
                "references": [
                    {
                        "qualifier": "ADDRESS_BOOK_ENTRY_ID",
                        "value": "{YOUR_ADDRESS_BOOK_ENTRY_ID}"
                    }
                ],
                "shipping_requirements": {
                    "plan_window": {
                        "start": "2024-04-20T05:00:00+00:00",
                        "end": "2024-04-20T05:00:00+00:00"
                    }
                }
            },
            "description": null,
            "source": null,
            "source_system_id": null,
            "start_date": null,
            "expiration_date": null,
            "references": [
                {
                    "qualifier": "PURCHASE_ORDER_NUMBER",
                    "value": "PO#-123"
                }
            ],
            "id": "01HW3H8ZR10A6A5S78Y6RNRA1B",
            "order_type": "PURCHASE_ORDER",
            "status": "READY",
            "items": [
                {
                    "custom_data": null,
                    "description": "Product description-123",
                    "references": [],
                    "shipping_requirements": {
                        "description": "Product description-123",
                        "identifying_marks": [],
                        "references": [],
                        "tare_weight": null,
                        "dimensions": {
                            "unit": "IN",
                            "length": "40",
                            "height": "48",
                            "width": "40"
                        },
                        "volume": null,
                        "customer_reference_number": null,
                        "hazmat": null,
                        "temperature": {
                            "unit": "F",
                            "minimum": "25",
                            "maximum": "35"
                        },
                        "product_id": null,
                        "freight_class": "50",
                        "nmfc_item_code": "25",
                        "nmfc_sub_code": "35",
                        "country_of_manufacture": "US",
                        "stackable": false,
                        "piece_type": null,
                        "total_pieces": null,
                        "value_per_piece": null,
                        "gross_weight": {
                            "unit": "LB",
                            "value": "250"
                        },
                        "quantity": 2,
                        "packaging_type": "PALLET",
                        "handling_unit_id": "1234",
                        "combined_handling_unit_info": {
                            "quantity": 1,
                            "packaging_type": "PALLET",
                            "freight_class": "50",
                            "dimensions": {
                                "unit": "IN",
                                "length": "40",
                                "height": "48",
                                "width": "40"
                            },
                            "net_weight": {
                                "unit": "LB",
                                "value": "1700"
                            }
                        }
                    },
                    "amount": {
                        "unit": "BAG",
                        "value": "200"
                    },
                    "id": "01HW3H8ZRBX7FWYV8KAGB3EKS7",
                    "available_amount": {
                        "unit": "BAG",
                        "value": "200"
                    }
                },
                {
                    "custom_data": null,
                    "description": "Product description- Test",
                    "references": [],
                    "shipping_requirements": {
                        "description": "Product description- Test",
                        "identifying_marks": [],
                        "references": [],
                        "tare_weight": null,
                        "dimensions": {
                            "unit": "IN",
                            "length": "40",
                            "height": "48",
                            "width": "40"
                        },
                        "volume": null,
                        "customer_reference_number": null,
                        "hazmat": null,
                        "temperature": {
                            "unit": "F",
                            "minimum": "110",
                            "maximum": "120"
                        },
                        "product_id": null,
                        "freight_class": "50",
                        "nmfc_item_code": "25",
                        "nmfc_sub_code": "35",
                        "country_of_manufacture": "US",
                        "stackable": false,
                        "piece_type": null,
                        "total_pieces": null,
                        "value_per_piece": null,
                        "gross_weight": {
                            "unit": "LB",
                            "value": "500"
                        },
                        "quantity": 2,
                        "packaging_type": "PALLET",
                        ""handling_unit_id": "1234",
                        "combined_handling_unit_info": {
                            "quantity": 1,
                            "packaging_type": "PALLET",
                            "freight_class": "50",
                            "dimensions": {
                                "unit": "IN",
                                "length": "40",
                                "height": "48",
                                "width": "40"
                            },
                            "net_weight": {
                                "unit": "LB",
                                "value": "1700"
                            }
                        }
                    },
                    "amount": {
                        "unit": "BAG",
                        "value": "200"
                    },
                    "id": "01HW3H8ZRFVT8QBZSA57GBRRJK",
                    "available_amount": {
                        "unit": "BAG",
                        "value": "200"
                    }
                }
            ],
            "supplier_created_releases_allowed": false,
            "supplier": {
                "name": "ICS",
                "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":{
      "shipwell_custom_data":{
         "purchase_order":{
            "b0466a0c-27f7-4f6b-bdb9-093d5669f458":"GRN",
            "ccea681d-60f9-41e3-b052-c75370255753":"Trade Number"
         }
      }
   },
   "order_number":"Order-45690",
   "ship_to":{
      "country":"US",
      "line_1":"Debartolo Dr",
      "line_2":null,
      "line_3":null,
      "locality":"North Jackson",
      "postal_code":"44451",
      "region":"OH",
      "urbanization":null,
      "residential":false,
      "geolocation":null,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               
            }
         }
      },
      "timezone":"America/New_York",
      "location_number":null,
      "company_name":"SK",
      "references":[
         {
            "qualifier":"ADDRESS_BOOK_ENTRY_ID",
            "value":"{YOUR_ADDRESS_BOOK_ENTRY_ID}"
         }
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-04-22T16:00:00+00:00",
            "end":"2024-04-22T16:00:00+00:00"
         }
      }
   },
   "name":"Order name",
   "ship_from":{
      "country":"US",
      "line_1":"7175 Kit Kat Rd, Elkridge, MD 21075, US",
      "line_2":null,
      "line_3":null,
      "locality":"Elkridge",
      "postal_code":null,
      "region":"CO",
      "urbanization":null,
      "residential":false,
      "geolocation":null,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               
            }
         }
      },
      "timezone":"America/New_York",
      "location_number":null,
      "company_name":"ICS",
      "references":[
         {
            "qualifier":"ADDRESS_BOOK_ENTRY_ID",
            "value":"{YOUR_ADDRESS_BOOK_ENTRY_ID}"
         }
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-04-20T05:00:00+00:00",
            "end":"2024-04-20T05:00:00+00:00"
         }
      }
   },
   "description":null,
   "source":null,
   "source_system_id":null,
   "start_date":null,
   "expiration_date":null,
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"PO#-123"
      }
   ],
   "id":"01HW3H8ZR10A6A5S78Y6RNRA1B",
   "order_type":"PURCHASE_ORDER",
   "status":"READY",
   "items":[
      {
         "custom_data":null,
         "description":"Product description-123",
         "references":[
            
         ],
         "shipping_requirements":{
            "description":"Product description-123",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":{
               "unit":"IN",
               "length":"40",
               "height":"48",
               "width":"40"
            },
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":{
               "unit":"F",
               "minimum":"25",
               "maximum":"35"
            },
            "product_id":null,
            "freight_class":"50",
            "nmfc_item_code":"25",
            "nmfc_sub_code":"35",
            "country_of_manufacture":"US",
            "stackable":false,
            "piece_type":null,
            "total_pieces":null,
            "value_per_piece":null,
            "gross_weight":{
               "unit":"LB",
               "value":"250"
            },
            "quantity":2,
            "packaging_type":"PALLET",
            "handling_unit_id":null,
            "combined_handling_unit_info":null
         },
         "amount":{
            "unit":"BAG",
            "value":"200"
         },
         "id":"01HW3H8ZRBX7FWYV8KAGB3EKS7",
         "available_amount":{
            "unit":"BAG",
            "value":"200"
         }
      },
      {
         "custom_data":null,
         "description":"Product description- Test",
         "references":[
            
         ],
         "shipping_requirements":{
            "description":"Product description- Test",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":{
               "unit":"IN",
               "length":"40",
               "height":"48",
               "width":"40"
            },
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":{
               "unit":"F",
               "minimum":"110",
               "maximum":"120"
            },
            "product_id":null,
            "freight_class":"50",
            "nmfc_item_code":"25",
            "nmfc_sub_code":"35",
            "country_of_manufacture":"US",
            "stackable":false,
            "piece_type":null,
            "total_pieces":null,
            "value_per_piece":null,
            "gross_weight":{
               "unit":"LB",
               "value":"500"
            },
            "quantity":2,
            "packaging_type":"PALLET",
            "handling_unit_id":null,
            "combined_handling_unit_info":null
         },
         "amount":{
            "unit":"BAG",
            "value":"200"
         },
         "id":"01HW3H8ZRFVT8QBZSA57GBRRJK",
         "available_amount":{
            "unit":"BAG",
            "value":"200"
         }
      }
   ],
   "supplier_created_releases_allowed":false,
   "supplier":{
      "name":"ICS",
      "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":{
      "shipwell_custom_data":{
         "purchase_order":{
            "b0466a0c-27f7-4f6b-bdb9-093d5669f458":"GRN",
            "ccea681d-60f9-41e3-b052-c75370255753":"Trade Number"
         }
      }
   },
   "order_number":"Order-45690",
   "ship_to":{
      "country":"US",
      "line_1":"Debartolo Dr",
      "line_2":None,
      "line_3":None,
      "locality":"North Jackson",
      "postal_code":"44451",
      "region":"OH",
      "urbanization":None,
      "residential":False,
      "geolocation":None,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{}
         }
      },
      "timezone":"America/New_York",
      "location_number":None,
      "company_name":"SK",
      "references":[
         {
            "qualifier":"ADDRESS_BOOK_ENTRY_ID",
            "value":"{YOUR_ADDRESS_BOOK_ENTRY_ID}"
         }
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-04-22T16:00:00+00:00",
            "end":"2024-04-22T16:00:00+00:00"
         }
      }
   },
   "name":"Order name",
   "ship_from":{
      "country":"US",
      "line_1":"7175 Kit Kat Rd, Elkridge, MD 21075, US",
      "line_2":None,
      "line_3":None,
      "locality":"Elkridge",
      "postal_code":None,
      "region":"CO",
      "urbanization":None,
      "residential":False,
      "geolocation":None,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{}
         }
      },
      "timezone":"America/New_York",
      "location_number":None,
      "company_name":"ICS",
      "references":[
         {
            "qualifier":"ADDRESS_BOOK_ENTRY_ID",
            "value":"{YOUR_ADDRESS_BOOK_ENTRY_ID}"
         }
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-04-20T05:00:00+00:00",
            "end":"2024-04-20T05:00:00+00:00"
         }
      }
   },
   "description":None,
   "source":None,
   "source_system_id":None,
   "start_date":None,
   "expiration_date":None,
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"PO#-123"
      }
   ],
   "id":"01HW3H8ZR10A6A5S78Y6RNRA1B",
   "order_type":"PURCHASE_ORDER",
   "status":"READY",
   "items":[
      {
         "custom_data":None,
         "description":"Product description-123",
         "references":[],
         "shipping_requirements":{
            "description":"Product description-123",
            "identifying_marks":[],
            "references":[],
            "tare_weight":None,
            "dimensions":{
               "unit":"IN",
               "length":"40",
               "height":"48",
               "width":"40"
            },
            "volume":None,
            "customer_reference_number":None,
            "hazmat":None,
            "temperature":{
               "unit":"F",
               "minimum":"25",
               "maximum":"35"
            },
            "product_id":None,
            "freight_class":"50",
            "nmfc_item_code":"25",
            "nmfc_sub_code":"35",
            "country_of_manufacture":"US",
            "stackable":False,
            "piece_type":None,
            "total_pieces":None,
            "value_per_piece":None,
            "gross_weight":{
               "unit":"LB",
               "value":"250"
            },
            "quantity":2,
            "packaging_type":"PALLET",
            "handling_unit_id":None,
            "combined_handling_unit_info":None
         },
         "amount":{
            "unit":"BAG",
            "value":"200"
         },
         "id":"01HW3H8ZRBX7FWYV8KAGB3EKS7",
         "available_amount":{
            "unit":"BAG",
            "value":"200"
         }
      },
      {
         "custom_data":None,
         "description":"Product description- Test",
         "references":[],
         "shipping_requirements":{
            "description":"Product description- Test",
            "identifying_marks":[],
            "references":[],
            "tare_weight":None,
            "dimensions":{
               "unit":"IN",
               "length":"40",
               "height":"48",
               "width":"40"
            },
            "volume":None,
            "customer_reference_number":None,
            "hazmat":None,
            "temperature":{
               "unit":"F",
               "minimum":"110",
               "maximum":"120"
            },
            "product_id":None,
            "freight_class":"50",
            "nmfc_item_code":"25",
            "nmfc_sub_code":"35",
            "country_of_manufacture":"US",
            "stackable":False,
            "piece_type":None,
            "total_pieces":None,
            "value_per_piece":None,
            "gross_weight":{
               "unit":"LB",
               "value":"500"
            },
            "quantity":2,
            "packaging_type":"PALLET",
            "handling_unit_id":None,
            "combined_handling_unit_info":None
         },
         "amount":{
            "unit":"BAG",
            "value":"200"
         },
         "id":"01HW3H8ZRFVT8QBZSA57GBRRJK",
         "available_amount":{
            "unit":"BAG",
            "value":"200"
         }
      }
   ],
   "supplier_created_releases_allowed":False,
   "supplier":{
      "name":"ICS",
      "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)
Example response
About This Response Payload
  • The response payload below includes custom data entry fields and address book entry references.
  • See the create order example response for an alternate simpler example and notes on a general order payload response.
Copy
Copied
{
   "custom_data":{
      "shipwell_custom_data":{
         "purchase_order":{
            "b0466a0c-27f7-4f6b-bdb9-093d5669f458":"GRN",
            "ccea681d-60f9-41e3-b052-c75370255753":"Trade Number"
         }
      }
   },
   "order_number":"Order-45690",
   "ship_to":{
      "country":"US",
      "line_1":"Debartolo Dr",
      "line_2":null,
      "line_3":null,
      "locality":"North Jackson",
      "postal_code":"44451",
      "region":"OH",
      "urbanization":null,
      "residential":false,
      "geolocation":null,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               
            }
         }
      },
      "timezone":"America/New_York",
      "location_number":null,
      "company_name":"SK",
      "references":[
         {
            "qualifier":"ADDRESS_BOOK_ENTRY_ID",
            "value":"{YOUR_ADDRESS_BOOK_ENTRY_ID}"
         }
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-04-22T16:00:00+00:00",
            "end":"2024-04-22T16:00:00+00:00"
         }
      }
   },
   "name":"Order name",
   "ship_from":{
      "country":"US",
      "line_1":"7175 Kit Kat Rd, Elkridge, MD 21075, US",
      "line_2":null,
      "line_3":null,
      "locality":"Elkridge",
      "postal_code":null,
      "region":"CO",
      "urbanization":null,
      "residential":false,
      "geolocation":null,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               
            }
         }
      },
      "timezone":"America/New_York",
      "location_number":null,
      "company_name":"ICS",
      "references":[
         {
            "qualifier":"ADDRESS_BOOK_ENTRY_ID",
            "value":"{YOUR_ADDRESS_BOOK_ENTRY_ID}"
         }
      ],
      "shipping_requirements":{
         "plan_window":{
            "start":"2024-04-20T05:00:00+00:00",
            "end":"2024-04-20T05:00:00+00:00"
         }
      }
   },
   "description":null,
   "source":null,
   "source_system_id":null,
   "start_date":null,
   "expiration_date":null,
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"PO#-123"
      }
   ],
   "id":"01HW3H8ZR10A6A5S78Y6RNRA1B",
   "order_type":"PURCHASE_ORDER",
   "status":"READY",
   "items":[
      {
         "custom_data":null,
         "description":"Product description-123",
         "references":[
            
         ],
         "shipping_requirements":{
            "description":"Product description-123",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":{
               "unit":"IN",
               "length":"40",
               "height":"48",
               "width":"40"
            },
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":{
               "unit":"F",
               "minimum":"25",
               "maximum":"35"
            },
            "product_id":null,
            "freight_class":"50",
            "nmfc_item_code":"25",
            "nmfc_sub_code":"35",
            "country_of_manufacture":"US",
            "stackable":false,
            "piece_type":null,
            "total_pieces":null,
            "value_per_piece":null,
            "gross_weight":{
               "unit":"LB",
               "value":"250"
            },
            "quantity":2,
            "packaging_type":"PALLET",
            "handling_unit_id":null,
            "combined_handling_unit_info":null
         },
         "amount":{
            "unit":"BAG",
            "value":"200"
         },
         "id":"01HW3H8ZRBX7FWYV8KAGB3EKS7",
         "available_amount":{
            "unit":"BAG",
            "value":"200"
         }
      },
      {
         "custom_data":null,
         "description":"Product description- Test",
         "references":[
            
         ],
         "shipping_requirements":{
            "description":"Product description- Test",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":{
               "unit":"IN",
               "length":"40",
               "height":"48",
               "width":"40"
            },
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":{
               "unit":"F",
               "minimum":"110",
               "maximum":"120"
            },
            "product_id":null,
            "freight_class":"50",
            "nmfc_item_code":"25",
            "nmfc_sub_code":"35",
            "country_of_manufacture":"US",
            "stackable":false,
            "piece_type":null,
            "total_pieces":null,
            "value_per_piece":null,
            "gross_weight":{
               "unit":"LB",
               "value":"500"
            },
            "quantity":2,
            "packaging_type":"PALLET",
            "handling_unit_id":null,
            "combined_handling_unit_info":null
         },
         "amount":{
            "unit":"BAG",
            "value":"200"
         },
         "id":"01HW3H8ZRFVT8QBZSA57GBRRJK",
         "available_amount":{
            "unit":"BAG",
            "value":"200"
         }
      }
   ],
   "supplier_created_releases_allowed":false,
   "supplier":{
      "name":"ICS",
      "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
}
Copyright © Shipwell 2024. All right reserved.