Manage Orders

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 .

Get Orders

Retrieving one or multiple orders in the API uses the same flexible GET /orders order list endpoint that supports querying for an order or orders. Obtaining one or more orders will follow the same paginated data access pattern and only vary in the number of results returned in the API response from your request. The GET /orders API route or endpoint parameters are documented here in the API reference and this same endpoint may be utilized to query for purchase orders, sales orders, etc.

The base API call to get a paginated list of orders is:

Example orders list query request

About This Request Payload

The example below is default query for the GET /orders order list endpoint . You may specify additional query/querystring parameters to filter, sort, change the number of items returned, etc.
Set the limit query parameter to set the maximum number of items returned in the response (i.e. ?limit=25 , ?existing_param=abc&limit=50 ).
Set the order_by parameter to sort the data/items by a particular property value (i.e. ?order_by=order_number , ?limit=20&order_by=order_number ).
Add a - (minus sign) to the order_by parameter value to sort by that parameter in descending sort order instead of the default ascending sort order (i.e. ?order_by=-id , ?limit=20&order_by=-id ).
Generated order id s are ulids or uulids meaning that order id s may be sorted by monotonically by create date of the order
See the order list API reference for a detailed list of fields or properties for the request and response bodies for order listing/querying.

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/orders' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

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

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

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

Example orders list query response

Copy

Copied

{
  "data": [
      {
        "order_number":"QUICKSTART-1",
        "id":"01HW71W0F52A4S9MME04E053EN",
        "order_type":"PURCHASE_ORDER",
        // ...
      },
    // ... other orders ...
  ],
  "count": 20, // number of items in the "data" array for this response
  "total_count": 80, // number of total items that match the query
  "links": {
    "next": "https://sandbox-api.shipwell.com/orders?page=1", // next set of results that match the query
    "prev": null, // previous set of results that match the query
    "first": "https://sandbox-api.shipwell.com/orders?page=1", // first set of results that match the query (i.e. first page)
    "last": "https://sandbox-api.shipwell.com/orders?page=1" // last set of results that match the query (i.e. last page)
  }
}

Get one specific order

Retrieve the details of an existing order by the order id.

Tip

You may also get an existing order by the order_number (aka purchase order number, sales order number, etc.) using GET /orders?order_number=YOUR_ORDER_NUMBER. In certain use cases, this is preferred to the id of the order.

Example request

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/orders?id=YOUR_ORDER_ID' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const orderId = "YOUR_orderId_PARAMETER";
const basePath = "";
const host = "sandbox-api.shipwell.com";

const query = new URLSearchParams({
  id: orderId,
}).toString();

const resp = await fetch(
  `https://${host}${basePath}/orders?${query}`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

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

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

query_params = {
    "id": order_id
}

response = requests.get(target_url, headers=headers, params=query_params)
data = response.json()
print(data)

Example response

Copy

Copied

{
  "data": [
      {
        "order_number":"QUICKSTART-1",
        "id":"01HW71W0F52A4S9MME04E053EN",
        "order_type":"PURCHASE_ORDER",
        // ...
      },
    // ... other orders ...
  ],
  "count": 1, // number of items in the "data" array for this response
  "total_count": 1, // number of total items that match the query
  "links": {
    "next": null, // next set of results that match the query
    "prev": null, // previous set of results that match the query
    "first": "https://sandbox-api.shipwell.com/orders?order_number=<YOUR_orderNumber_PARAMETER>&page=1", // first set of results that match the query (i.e. first page)
    "last": "https://sandbox-api.shipwell.com/orders?order_number=YOUR_orderNumber_PARAMETER&page=1" // last set of results that match the query (i.e. last page)
  }
}

Get multiple orders

Obtaining multiple orders is purposefully similar to obtaining a single order. You may combine various search or query criteria to filter orders and apply an order_by querystring parameter if you which to sort the orders by a particular property on the order.

Set limit querystring parameter in the request to restrict the number of results returned from the request. Example: /orders?limit=10 .
Set the page querystring parameter in the request to select a specific page of results (i.e. if there are 20 total items, total_count is 20 in the response body, that match the query and the limit is 10 then orders?limit=10&page=2 would return the second page of results which are items 11-20 )
When querying for orders by date/times, use the UTC time zone instead of a local time zone.
Date/times are represented as ISO 8601 date/time strings in the UTC time zone (a Z or +00:00 at the end of the date/time string is the indicator for UTC ).
See the orders list API reference for a detailed list of fields or properties for the request and response structures for this operation.

Example request

About This Request

This is an example of querying for orders that have the READY status.
To see the full list of order statuses see the order status documentation here .
You may also request code samples in other programming languages by utilizing Shipwell's AI-powered developer chatbot on the developer portal. Ask the chatbot to "Translate the following code sample into programming language X." where X is your desired programming language.

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/orders?status=READY&limit=100' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const orderStatus = "YOUR_orderStatus_PARAMETER";
const basePath = "";
const host = "sandbox-api.shipwell.com";

const query = new URLSearchParams({
  status: orderStatus,
  limit: 100, 
  // ... other parameters
}).toString();

const resp = await fetch(
  `https://${host}${basePath}/orders?${query}`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

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

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

query_params = {
    "status": order_status,
    "limit": 100
}

response = requests.get(target_url, headers=headers, params=query_params)
data = response.json()
print(data)

Example response

Copy

Copied

{
  "data": [
      {
        "order_number":"QUICKSTART-1",
        "id":"01HW71W0F52A4S9MME04E053EN",
        "order_type":"PURCHASE_ORDER",
        // ...
      },
    // ... other orders ...
  ],
  "count": 100, // number of items in the "data" array for this response
  "total_count": 1000, // number of total items that match the query
  "links": {
    "next": "https://sandbox-api.shipwell.com/orders?status=READY&limit=100&page=2", // next set of results that match the query
    "prev": null, // previous set of results that match the query
    "first": "https://sandbox-api.shipwell.com/orders?status=READY&limit=100&page=1", // first set of results that match the query (i.e. first page)
    "last": "https://sandbox-api.shipwell.com/orders?status=READY&limit=100&page=10" // last set of results that match the query (i.e. last page)
  }
}

Interactive Code Notebook

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, update, and get orders.

Shipwell Google Colab Notebook for Creating, Updating, and Retrieving Orders
- https://colab.research.google.com/drive/1sWtlrLSkrMXg7iXgA6_-gLwYnVWCFGkJ?usp=sharing

Create an Order

Reference the quickstart order creation guide for details on how to create an order.

Update an Order

Orders are updated using the PUT /orders/{order_id} endpoint. The Shipwell Orders API supports polymorphic order creation which means purchase order, sales orders, and any other type of order may be updated using the same endpoint with the appropriate request body payload for the order_type.

Tip

You may update and order at any time (even after all shipments have been delivered, etc.) which allows you to correct any issues, update descriptions, etc.
Updating the date/time in the planning_window for a start or end date/time on an order does not propagate to shipments created from that order (i.e. shipments do not inherit updates to planning_window date/times from the order they were created from and must be updated independently).
- shipping_requirements and the planning_window object are typically utilized for Supplier Portal use cases.
When you use PUT at the top-level for an order update using PUT /orders/{order_id} , you must supply the full resource representation. If you leave out any fields, they may be cleared or reset on the server. To preserve existing data, first GET the resource, then apply your changes locally, and finally PUT the complete object back (including the fields that you did not modify). Learn more about PUT for updates in REST APIs here . There are specific endpoints for partial order updates at particular levels of the order object.

Example request

About This Request Payload

The example below is a single line item order with a single ship_from and ship_to for an item that has temperature shipping requirements that we are updating.
The order update is an HTTP PUT operation and the order will reflect the state of the data sent in the PUT after an update (excluding calculated or readonly properties).
Common reasons to update an order include (but are not limited to) updates to:
- Line item quantity or amounts (i.e. 5 pallets instead of 6 pallets)
- Location information (i.e. ship_to , ship_from , or generally pickup and delivery stop locations)
- Pick-up or delivery date/times
See the API reference for a detailed list of fields or properties for the request and response bodies for order update.

curljavascriptpython

Copy

Copied

curl -i -X PUT \
  'https://sandbox-api.shipwell.com/orders/{orderId}' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
   "custom_data":{},
   "order_number":"QUICKSTART-1",
   "name":"Changed - 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 orderId = "YOUR_orderId_PARAMETER";
const payload = {
   "custom_data":{},
   "order_number":"QUICKSTART-1",
   "name":"Changed - 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/${orderId}`,
  {
    method: "PUT",
    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

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

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

payload = {
   "custom_data": {},
   "order_number": "QUICKSTART-1",
   "name": "Changed - 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.put(target_url, headers=headers, json=payload)
data = response.json()
print(data)

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 API reference for a detailed list of fields or properties for the response payload body for order update.

Copy

Copied

{
   "custom_data":{
      
   },
   "order_number":"QUICKSTART-1",
   "name":"Changed - 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"
      }
   ],
   "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
}

Partial Order Updates

Orders may be partially updated in particular frequently updated sections instead of requiring the entire order payload to be updated.

Example request

About This Request Payload

The example below is an update to the ship-to for an order. The ship-from and supplier may also be updated in isolation without requiring updates to the rest of the order.
See the API reference for a detailed list of fields or properties for the request and response bodies for order update.

curljavascriptpython

Copy

Copied

curl -i -X PUT \
  'https://sandbox-api.shipwell.com/orders/{orderId}/{sectionName}' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
   "country":"US",
   "geolocation":{
      "latitude":40.7195656,
      "longitude":-74.0066124
   },
   "line_1":"14 N Moore St",
   "locality":"New York",
   "postal_code":"10013",
   "region":"NY",
   "timezone":"America/New_York",
   "shipping_requirements":{
      "plan_window":{
         "start":"2024-06-28T17:00:00+00:00",
         "end":"2024-06-28T21:00:00+00:00"
      }
   },
   "company_name":"Updated name"
}'

Copy

Copied

const orderId = "YOUR_orderId_PARAMETER";
const payload = {
   "country":"US",
   "geolocation":{
      "latitude":40.7195656,
      "longitude":-74.0066124
   },
   "line_1":"14 N Moore St",
   "locality":"New York",
   "postal_code":"10013",
   "region":"NY",
   "timezone":"America/New_York",
   "shipping_requirements":{
      "plan_window":{
         "start":"2024-06-28T17:00:00+00:00",
         "end":"2024-06-28T21:00:00+00:00"
      }
   },
   "company_name":"Updated name"
};

const basePath = "";
const host = "sandbox-api.shipwell.com";
const sectionName = "ship-to"; // "ship-from", "supplier", etc.
const resp = await fetch(
  `https://${host}${basePath}/orders/${orderId}/${sectionName}`,
  {
    method: "PUT",
    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

order_id = "YOUR_orderId_PARAMETER"
base_path = ""
host = "sandbox-api.shipwell.com"
section_name = "ship-to"
target_url = "https://" + host + base_path + "/orders/" + order_id + "/" + section_name

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

payload = {
   "country":"US",
   "geolocation":{
      "latitude":40.7195656,
      "longitude":-74.0066124
   },
   "line_1":"14 N Moore St",
   "locality":"New York",
   "postal_code":"10013",
   "region":"NY",
   "timezone":"America/New_York",
   "shipping_requirements":{
      "plan_window":{
         "start":"2024-06-28T17:00:00+00:00",
         "end":"2024-06-28T21:00:00+00:00"
      }
   },
   "company_name":"Updated name"
}

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

Example response

About This Response Payload

The response for a partial update to a section of an order like ship-to will be just that section in the response.

Copy

Copied

{
   "country":"US",
   "geolocation":{
      "latitude":40.7195656,
      "longitude":-74.0066124
   },
   "line_1":"14 N Moore St",
   "locality":"New York",
   "postal_code":"10013",
   "region":"NY",
   "timezone":"America/New_York",
   "shipping_requirements":{
      "plan_window":{
         "start":"2024-06-28T17:00:00+00:00",
         "end":"2024-06-28T21:00:00+00:00"
      }
   },
   "company_name":"Updated name"
}

Cancel (Delete) an Order

To cancel an order you make an HTTP POST to the cancel order action endpoint with the orderId/order_id as part of the route/URL. Orders are not deleted, but are cancelled and the order status is modified.

After an order is cancelled (note: Shipwell uses the international English spelling of cancelled with "l" letters vs. the US-only English spelling with one "l"), the order status field will change to CANCELLED and the canceled_at field will be set to date/time that the order was cancelled in the UTC time zone (as an ISO 8601 date/time string).

Copy

Copied

"cancelled_at": "2025-07-22T14:54:37.942489+00:00",
"status": "CANCELLED",
// ... other properties

Note

If an order is on one or more shipments, then it cannot be cancelled. An API caller attempting to cancel an order in this state will receive an error message. See the Order FAQs for more information.

Example request

Note

To cancel a purchase order , use the route /purchase-orders/{order_id}/cancel and to cancel a sales order use the route /sales-orders/{order_id}/cancel
The system will have a new [polymorphic] ( https://en.wikipedia.org/wiki/Polymorphism_(computer_science ) endpoint at /orders/{order_id}/cancel in the future.

curljavascriptpython

Copy

Copied

curl -i -X POST \
  'https://sandbox-api.shipwell.com/purchase-orders/{orderId}/cancel' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const orderId = "YOUR_orderId_PARAMETER";
const basePath = "";
const hostPath = "sandbox-api.shipwell.com";

const targetUrl = `https://${hostPath}${basePath}/purchase-orders/${orderId}/cancel`;

const resp = await fetch(
  targetUrl,
  {
    method: "POST",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    },
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

order_id = "YOUR_orderId_PARAMETER"
base_path = ""
host_path = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host_path
    + base_path
    + "/purchase-orders/" 
    + order_id
    + "/cancel" 
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

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

Example response

Copy

Copied

{
   "custom_data":{},
   "order_number":"TESTPO12349234823BZ-1",
   "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":null
      }
   },
   "name":"Test Order Name",
   "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-17T05:00:00+00:00",
            "end":null
         }
      }
   },
   "description":null,
   "source":null,
   "source_system_id":null,
   "start_date":null,
   "expiration_date":null,
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"TESTPO12349234823"
      }
   ],
   "id":"01HW34C5AW3M6BCV75JVX6NH9H",
   "order_type":"PURCHASE_ORDER",
   "status":"CANCELLED",
   "items":[
      {
         "custom_data":{},
         "description":"Example item 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":"10"
         },
         "id":"01HW34C5B6H0HMSZ2QPKPMFGAM",
         "available_amount":{
            "unit":"BAG",
            "value":"10"
         }
      }
   ],
   "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":"2025-07-22T14:54:37.942489+00:00",
   "archived":false
}

Manage Order Items

The Shipwell Orders API enables adding, getting/retrieving, updating, or deleting purchase order items on a purchase order in isolation of updating other parts of the order. This helps prevent code race conditions that in other systems may drop order items or issue the incorrect command due to timing.

Note

Currently, only purchase orders may have their order items modified as a set of available endpoints in the API.

Add Order Item

Example request

About This Request Payload

The example below is an addition of an order item to an order. The payload is purposefully as basic order item.
Items may have shipping_requirements set to enable creating shipments from orders in other processes.
See the create order item API reference for a detailed list of fields or properties for the request and response bodies for this operation.

curljavascriptpython

Copy

Copied

curl -i -X POST \
  'https://sandbox-api.shipwell.com/purchase-orders/{orderId}/items' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
   "amount":{
      "value":"10",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "description":"Example",
      "stackable":true
   }
}'

Copy

Copied

const orderId = "YOUR_orderId_PARAMETER";
const payload = {
   "amount":{
      "value":"10",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "description":"Example",
      "stackable":true
   }
};

const basePath = "";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/purchase-orders/${orderId}/items`,
  {
    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

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

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

payload = {
   "amount":{
      "value":"10",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "description":"Example",
      "stackable": True
   }
}

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

Example response

About This Response Payload

The response for creating a new order item will generate an order item id and return a full response of the item's available properties.

Copy

Copied

{
   "custom_data":null,
   "description":"Example",
   "references":[
      
   ],
   "shipping_requirements":{
      "description":"Example",
      "identifying_marks":[
         
      ],
      "references":[
         
      ],
      "tare_weight":null,
      "dimensions":null,
      "volume":null,
      "customer_reference_number":null,
      "hazmat":null,
      "temperature":null,
      "product_id":null,
      "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":"PALLET",
      "value":"10"
   },
   "id":"01HW8D66Z2H9HA0FW7J6A9DGJX",
   "available_amount":{
      "unit":"PALLET",
      "value":"10"
   }
}

Get Order Item

This operation allows retrieving a single order item by the order_item_id/orderItemId without the full payload of the order or any other order items.

Example request

About This Request Payload

See the get order item API reference for a detailed list of fields or properties for the request and response bodies for this operation.

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/purchase-orders/{orderId}/items/{orderItemId}' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const orderId = "YOUR_orderId_PARAMETER";
const orderItemId = "YOUR_orderItemId_PARAMETER";

const basePath = "";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/purchase-orders/${orderId}/items/${orderItemId}`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

order_id = "YOUR_orderId_PARAMETER"
order_item_id = "YOUR_orderItemId_PARAMETER"
base_path = ""
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/purchase-orders/" + order_id + "/items/" + order_item_id

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

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

Example response

Copy

Copied

{
   "custom_data":null,
   "description":"Order item description",
   "references":[
      
   ],
   "shipping_requirements":{
      "identifying_marks":[
         
      ],
      "references":[
         
      ],
      "tare_weight":null,
      "dimensions":null,
      "volume":null,
      "customer_reference_number":null,
      "hazmat":null,
      "temperature":null,
      "product_id":null,
      "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":"PALLET",
      "value":"5"
   },
   "id":"01HW8D66Z2H9HA0FW7J6A9DGJX",
   "available_amount":{
      "unit":"PALLET",
      "value":"5"
   }
}

Update Order Item

Example request

About This Request Payload

The example below is an update of an existing order item on an order. The payload is purposefully as basic order item.
Items may have shipping_requirements set to enable creating shipments from orders in other processes.
See the update order item API reference for a detailed list of fields or properties for the request and response bodies for this operation.

curljavascriptpython

Copy

Copied

curl -i -X PUT \
  'https://sandbox-api.shipwell.com/purchase-orders/{orderId}/items/{orderItemId}' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
   "description":"Modified description",
   "amount":{
      "value":"10",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "description":"Example",
      "stackable":true
   }
}'

Copy

Copied

const orderId = "YOUR_orderId_PARAMETER";
const orderItemId = "YOUR_orderItemId_PARAMETER";
const payload = {
   "description":"Modified description",
   "amount":{
      "value":"5",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "stackable":true
   }
};

const basePath = "";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/purchase-orders/${orderId}/items/${orderItemId}`,
  {
    method: "PUT",
    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

order_id = "YOUR_orderId_PARAMETER"
order_item_id = "YOUR_orderItemId_PARAMETER"
base_path = ""
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/purchase-orders/" + order_id + "/items/" + order_item_id

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

payload = {
   "description":"Modified description",
   "amount":{
      "value":"5",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "stackable": True
   }
}

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

Example response

Copy

Copied

{
   "custom_data":null,
   "description":"Modified description",
   "references":[
      
   ],
   "shipping_requirements":{
      "identifying_marks":[
         
      ],
      "references":[
         
      ],
      "tare_weight":null,
      "dimensions":null,
      "volume":null,
      "customer_reference_number":null,
      "hazmat":null,
      "temperature":null,
      "product_id":null,
      "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":"PALLET",
      "value":"5"
   },
   "id":"01HW8D66Z2H9HA0FW7J6A9DGJX",
   "available_amount":{
      "unit":"PALLET",
      "value":"5"
   }
}

Delete Order Item

Example request

About This Request Payload

The example below is an update of an existing order item on an order. The payload is purposefully as basic order item.
Items may have shipping_requirements set to enable creating shipments from orders in other processes.
See the delete order item API reference for a detailed list of fields or properties for the request and response bodies for this operation.

curljavascriptpython

Copy

Copied

curl -i -X PUT \
  'https://sandbox-api.shipwell.com/purchase-orders/{orderId}/items' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
   "description":"Modified description",
   "amount":{
      "value":"10",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "description":"Example",
      "stackable":true
   }
}'

Copy

Copied

const orderId = "YOUR_orderId_PARAMETER";
const orderItemId = "YOUR_orderItemId_PARAMETER";
const payload = {
   "description":"Modified description",
   "amount":{
      "value":"5",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "stackable":true
   }
};

const basePath = "";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/purchase-orders/${orderId}/items/${orderItemId}`,
  {
    method: "PUT",
    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

order_id = "YOUR_orderId_PARAMETER"
order_item_id = "YOUR_orderItemId_PARAMETER"
base_path = ""
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/purchase-orders/" + order_id + "/items/" + order_item_id

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

payload = {
   "description":"Modified description",
   "amount":{
      "value":"5",
      "unit":"PALLET"
   },
   "shipping_requirements":{
      "stackable": True
   }
}

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

Example response

About This Response Payload

DELETE of an order item will return an 204 (Deleted) HTTP status code and no response body on success.
If the DELETE encounters a validation error, an error status code and response will be returned in this error format .