Managing purchase orders

Shipwell Supplier portal is a complete set of functionality that is available via a user interface as well as API access for key features.

Note

Shipwell Supplier Portal is in early access for select customers. If you are an existing Shipwell customer and want early access to Shipwell Supplier Portal contact your customer service representative. If you want to learn more as a new Shipwell customer contact sales here.

Purchase Orders vs. Sales Orders

Depending on which party you belong to on the Order, we will use different terminology to describe the same Order. If you are apart of the Customer on the Order, we will often refer to the Order as a Purchase Order. If you are apart of the Supplier on the Order, we will often refer to the Order as a Sales Order. This is encoded in our API as Customers will use /purchase-orders endpoints and Suppliers will use /sales-orders endpoints. The term Order(s) encompasses both items, but it is often useful to have a distinction in the terminology from the Customer or Supplier viewpoint.

Order Visibility

Click the image of the flow diagram below for a larger version.

Order visibility diagram

Customers have access to all of their orders and where they are in the fulfillment process, while suppliers have a similar level of visibility into purchase orders but only the purchase orders that they have access.

Purchase order visibility

Going into the On Shipments tab will provide orders that have been placed on a shipment and either are ready to be transported or are being transported.

Purchase order on shipments

Create a Purchase Order (Customer)

Customers can create and edit purchase orders within Shipwell. There are multiple methods to import purchase orders into Shipwell:

  1. UI-based order entry
  2. API integration
  3. Order importer upload
  4. SFTP flat file delivery

Create Purchase Order Flow Diagram

Click the image of the flow diagram below for a larger version.

Create purchase order flow diagram

This guide will cover creating a purchase order through the UI and via API integration. Contact your customer support representative if you need more information about other order import options.

Creating a new order within the Shipwell web interface is done by going to the Orders tab and select Add Order. There is the option to choose Purchase Order - Supplier Access and Purchase Order - No Supplier Access. Choose Purchase Order - Supplier Access if looking to create a purchase order that is accessible by the supplier identified on it. This also supports the back-and-forth collaboration process around the order. Alternatively, if Purchase Order - No Supplier Access is selected then it will be the same order creation process as within Shipwell for orders which only the customer can create and view.

Add order navigation

If creating an order with a supplier access enabled, then you will be directed to the following page, where you will complete the standard order information.

Create order data entry

Import Purchase Orders via UI Upload

Customers may import one or more purchase order by through the Shipwell web UI by uploading a CSV (comma-separated values) spreadsheet with the purchase order information.

From the UI, navigate to the Orders section then click or tap the Import button.

Import order button

Then download the example template for the purchase order import template format and instructions to prepare a file for upload that matches the format. A Google Sheets link for a publicly accessible sheet may also be utilized as long as the Google Sheet follows the same format or template.

Upload or link to the file or Google Sheet that contains the purchase orders that will be imported into the system. Follow the instructions in the Import Orders modal after uploading and clicking Next to complete the import.

Import order modal

Create a Purchase Order via API

Customers may create a purchase order that a supplier may interact with and fulfill via API. The essential components of creating a purchase order that may be interacted with in the Shipwell Supplier Portal are outlined in the example request below.

Note

Authorization headers, e.g. Authorization: YOUR_AUTHORIZATION_HEADER, typically take the form of Authorization: Token <user-token>. For more information on API authentication, navigate to the Authenticate documentation.

Example request
curljavascriptpython
Copy
Copied
curl --location --request POST 'https://sandbox-api.shipwell.com/purchase-orders/' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_AUTHORIZATION_HEADER' \
--data-raw '{
   "order_number":"ABC123",
   "name":"Example",
   "supplier":{
      "name":"Test Supplier",
      "supplier_id":"01H2XMX72CBBKN5WGQMCXGQ18G",
      "email":"test@example.com",
      "address":{
         "country":"US",
         "postal_code":"60661",
         "line_1":"567 W Lake St",
         "region":"IL",
         "locality":"Chicago",
         "timezone":"America/Chicago"
      },
      "phone_number":"+15555555555"
   },
   "supplier_created_releases_allowed":"true",
   "start_date":"2024-03-01",
   "expiration_date":"2024-05-01",
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"345"
      }
   ],
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "timezone":"America/Chicago",
      "company_name":"Test Address"
   },
   "ship_to":{
      "country":"US",
      "geolocation":{
         "latitude":30.2729209,
         "longitude":-97.74438630000002
      },
      "locality":"Austin",
      "postal_code":"78701",
      "region":"TX",
      "timezone":"America/Chicago",
      "company_name":"Shipwell"
   },
   "items":[
      {
         "amount":{
            "value":"2",
            "unit":"PALLET"
         },
         "shipping_requirements":{
            "product_id":"112994ff-dc26-4fd3-a25b-b214db4522e5",
            "description":"Test Product",
            "freight_class":null,
            "dimensions":{
               "length":"60",
               "width":"54",
               "height":"42",
               "unit":"IN"
            },
            "packaging_type":"PALLET",
            "gross_weight":{
               "value":"700",
               "unit":"LB"
            },
            "piece_type":null,
            "stackable":true
         }
      }
   ]
}'
Copy
Copied
const payload = {
    'order_number': 'ABC123',
    'name': 'Example',
    'supplier': {
      'name': 'Test Supplier',
      'supplier_id': '01H2XMX72CBBKN5WGQMCXGQ18G',
      'email': 'test@example.com',
      'address': {
        'country': 'US',
        'postal_code': '60661',
        'line_1': '567 W Lake St',
        'region': 'IL',
        'locality': 'Chicago',
        'timezone': 'America/Chicago'
      },
      'phone_number': '+15555555555'
    },
    'supplier_created_releases_allowed': 'true',
    'start_date': '2024-03-01',
    'expiration_date': '2024-05-01',
    'references': [
      {
        'qualifier': 'PURCHASE_ORDER_NUMBER',
        'value': '345'
      }
    ],
    'ship_from': {
      'country': 'US',
      'line_1': '567 W Lake St',
      'locality': 'Chicago',
      'postal_code': '60661',
      'region': 'IL',
      'timezone': 'America/Chicago',
      'company_name': 'Test Address'
    },
    'ship_to': {
      'country': 'US',
      'geolocation': {
        'latitude': 30.2729209,
        'longitude': -97.74438630000002
      },
      'locality': 'Austin',
      'postal_code': '78701',
      'region': 'TX',
      'timezone': 'America/Chicago',
      'company_name': 'Shipwell'
    },
    'items': [
      {
        'amount': {
          'value': '2',
          'unit': 'PALLET'
        },
        'shipping_requirements': {
          'product_id': '112994ff-dc26-4fd3-a25b-b214db4522e5',
          'description': 'Test Product',
          'freight_class': null,
          'dimensions': {
            'length': '60',
            'width': '54',
            'height': '42',
            'unit': 'IN'
          },
          'packaging_type': 'PALLET',
          'gross_weight': {
            'value': '700',
            'unit': 'LB'
          },
          'piece_type': null,
          'stackable': true
        }
      }
    ]
};

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

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

payload = {
    'order_number': 'ABC123',
    'name': 'Example',
    'supplier': {
        'name': 'Test Supplier',
        'supplier_id': '01H2XMX72CBBKN5WGQMCXGQ18G',
        'email': 'test@example.com',
        'address': {
            'country': 'US',
            'postal_code': '60661',
            'line_1': '567 W Lake St',
            'region': 'IL',
            'locality': 'Chicago',
            'timezone': 'America/Chicago',
        },
        'phone_number': '+15555555555',
    },
    'supplier_created_releases_allowed': 'true',
    'start_date': '2024-03-01',
    'expiration_date': '2024-05-01',
    'references': [
        {
            'qualifier': 'PURCHASE_ORDER_NUMBER',
            'value': '345',
        },
    ],
    'ship_from': {
        'country': 'US',
        'line_1': '567 W Lake St',
        'locality': 'Chicago',
        'postal_code': '60661',
        'region': 'IL',
        'timezone': 'America/Chicago',
        'company_name': 'Test Address',
    },
    'ship_to': {
        'country': 'US',
        'geolocation': {
            'latitude': 30.2729209,
            'longitude': -97.74438630000002,
        },
        'locality': 'Austin',
        'postal_code': '78701',
        'region': 'TX',
        'timezone': 'America/Chicago',
        'company_name': 'Shipwell',
    },
    'items': [
        {
            'amount': {
                'value': '2',
                'unit': 'PALLET',
            },
            'shipping_requirements': {
                'product_id': '112994ff-dc26-4fd3-a25b-b214db4522e5',
                'description': 'Test Product',
                'freight_class': None,
                'dimensions': {
                    'length': '60',
                    'width': '54',
                    'height': '42',
                    'unit': 'IN',
                },
                'packaging_type': 'PALLET',
                'gross_weight': {
                    'value': '700',
                    'unit': 'LB',
                },
                'piece_type': None,
                'stackable': True,
            },
        },
    ],
}

response = requests.post(target_url, headers=headers, json=payload)
data = response.json()
print(data)
Example response
Copy
Copied
{
    "custom_data": {
        "shipwell_custom_data": {
            "purchase_order": {}
        }
    },
    "order_number": "ABC123",
    "ship_to": {
        "country": "US",
        "line_1": null,
        "line_2": null,
        "line_3": null,
        "locality": "Austin",
        "postal_code": "78701",
        "region": "TX",
        "urbanization": null,
        "residential": false,
        "geolocation": {
            "latitude": 30.2729209,
            "longitude": -97.74438630000002
        },
        "custom_data": null,
        "timezone": "America/Chicago",
        "location_number": null,
        "company_name": "Shipwell",
        "references": [],
        "shipping_requirements": {
            "plan_window": null
        }
    },
    "name": "Example",
    "ship_from": {
        "country": "US",
        "line_1": "567 W Lake St",
        "line_2": null,
        "line_3": null,
        "locality": "Chicago",
        "postal_code": "60661",
        "region": "IL",
        "urbanization": null,
        "residential": false,
        "geolocation": null,
        "custom_data": null,
        "timezone": "America/Chicago",
        "location_number": null,
        "company_name": "Test Supplier",
        "references": [],
        "shipping_requirements": {
            "plan_window": null
        }
    },
    "description": null,
    "source": null,
    "source_system_id": null,
    "start_date": "2023-12-01",
    "expiration_date": "2023-12-31",
    "references": [
        {
            "qualifier": "PURCHASE_ORDER_NUMBER",
            "value": "345"
        }
    ],
    "id": "01HGGVYMNRY2MVP0ECBW5P1VRR",
    "order_type": "PURCHASE_ORDER",
    "status": "NOT_READY",
    "items": [
        {
            "custom_data": null,
            "amount": {
                "unit": "PALLET",
                "value": "2"
            },
            "shipping_requirements": {
                "description": "Test Product",
                "identifying_marks": [],
                "references": [],
                "tare_weight": null,
                "dimensions": {
                    "unit": "IN",
                    "length": "60",
                    "height": "42",
                    "width": "54"
                },
                "volume": null,
                "customer_reference_number": null,
                "hazmat": null,
                "temperature": null,
                "product_id": "112994ff-dc26-4fd3-a25b-b214db4522e5",
                "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": {
                    "unit": "LB",
                    "value": "700"
                },
                "quantity": null,
                "packaging_type": "PALLET"
            },
            "id": "01HGGVYMP4EGX6MSDN4FDDTF91",
            "available_amount": {
                "unit": "PALLET",
                "value": "2"
            }
        }
    ],
    "supplier_created_releases_allowed": true,
    "supplier": {
        "name": "Test Supplier",
        "address": {
            "country": "US",
            "line_1": "567 W Lake St",
            "line_2": null,
            "line_3": null,
            "locality": "Chicago",
            "postal_code": "60661",
            "region": "IL",
            "urbanization": null,
            "residential": false,
            "geolocation": null
        },
        "identification_codes": [],
        "phone_number": "+15555555555",
        "email": "test@example.com",
        "supplier_id": "01H2XMX72CBBKN5WGQMCXGQ18G"
    },
    "releases": [],
    "released_from_release_id": null,
    "created_from_order_id": null,
    "cancelled_at": null,
    "archived": false
}

To perform other actions on a purchase order via API, reference the purchase order API documentation related to the Supplier Portal here and expand the sections.

Accessing and Releasing Sales Orders (Supplier)

Suppliers can access all the orders in which they are identified within their Order Dashboard. Suppliers may fulfill sales orders partially (i.e. part of the order is ready for shipment) or completely in the platform. When an order is ready to be fulfilled suppliers select the order in question.

Note

See This functionality and associated order release actions are for Suppliers to perform to indicate when purchase orders are being fulfilled via shipments either partially or completely.

Supplier view orders

Suppliers can view detailed information about the order and when ready to fulfill it then they select Ready.

Supplier order ready

This will populate an order release modal where Suppliers can fill some or all of the order. The Supplier identifies the ready to ship date, pickup address, the quantity of items being shipped (whole or part of each order line item), the transportation detail around the items being shipped, and upload any order documents like a packing slip. Once an order is ready then the Shipwell customer is notified and can schedule the shipment. Customers can then ship orders similarly how they do within Shipwell today.

Supplier order release data entry

The process identified above is the Supplier initiated release workflow. In the future, Shipwell will also support a Customer initiated workflow where customers do the initial request for Order fulfillment from suppliers.

Releasing Sales Orders via API (Supplier)

Suppliers with API access may release an order via API.

Note

Authorization headers, e.g. Authorization: YOUR_AUTHORIZATION_HEADER, typically take the form of Authorization: Token <user-token>. For more information on API authentication, navigate to the Authenticate documentation.

Get the Sales Order Id

Retrieve the sales order by id. The sales order will contain the items and item identifiers (ids) that are needed to create a release for part or all of the sales order.

Example request
curljavascriptpython
Copy
Copied
curl --location --request GET 'https://sandbox-api.shipwell.com/sales-orders/{orderId}' \
    --header 'Authorization: YOUR_AUTHORIZATION_HEADER'
Copy
Copied
const orderId = "YOUR_orderId_PARAMETER";
const basePath = "";
const hostPath = "sandbox-api.shipwell.com";

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

const resp = await fetch(
  targetUrl,
  {
    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_path = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host_path
    + base_path
    + "/sales-orders/" 
    + order_id
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

response = requests.get(target_url, headers=headers)
data = response.json()
print(data)
Example response
Copy
Copied
{
   "custom_data":{
      "shipwell_custom_data":{
         "purchase_order":{
            
         }
      }
   },
   "order_number":"1272",
   "ship_to":{
      "country":"US",
      "line_1":"515 Congress Ave.",
      "line_2":"Unit 2650",
      "line_3":null,
      "locality":"Austin",
      "postal_code":"78701",
      "region":"TX",
      "urbanization":null,
      "residential":false,
      "geolocation":{
         "latitude":30.2677547,
         "longitude":-97.74260179999999
      },
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               "bb0312a6-4145-40df-9b17-06d93a03dce6":"22222"
            }
         }
      },
      "timezone":"America/Chicago",
      "location_number":null,
      "company_name":"Shipwell",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":null
      }
   },
   "name":null,
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "line_2":null,
      "line_3":null,
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "urbanization":null,
      "residential":false,
      "geolocation":null,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               "bb0312a6-4145-40df-9b17-06d93a03dce6":"11111"
            }
         }
      },
      "timezone":"America/Chicago",
      "location_number":null,
      "company_name":"Test Supplier",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":null
      }
   },
   "description":null,
   "source":null,
   "source_system_id":null,
   "start_date":"2023-12-01",
   "expiration_date":"2024-01-31",
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"11112222"
      }
   ],
   "id":"01HH2S8YMYPYWSY67C2PRWKQHV",
   "order_type":"SALES_ORDER",
   "status":"NOT_READY",
   "items":[
      {
         "custom_data":null,
         "amount":{
            "unit":"PALLET",
            "value":"3"
         },
         "shipping_requirements":{
            "description":"DASDry1",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":{
               "unit":"IN",
               "length":"60",
               "height":"42",
               "width":"54"
            },
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":null,
            "product_id":"112994ff-dc26-4fd3-a25b-b214db4522e5",
            "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":{
               "unit":"LB",
               "value":"700"
            },
            "quantity":null,
            "packaging_type":"PALLET"
         },
         "id":"01HH2S8YNAF2QYSE9YC1AGJZXB",
         "available_amount":{
            "unit":"PALLET",
            "value":"3"
         }
      }
   ],
   "supplier_created_releases_allowed":true,
   "supplier":{
      "name":"Test Supplier",
      "address":{
         "country":"US",
         "line_1":"567 W Lake St",
         "line_2":null,
         "line_3":null,
         "locality":"Chicago",
         "postal_code":"60661",
         "region":"IL",
         "urbanization":null,
         "residential":false,
         "geolocation":null
      },
      "identification_codes":[
         
      ],
      "phone_number":"+15555555555",
      "email":"test@example.com",
      "supplier_id":"01H2XMX72CBBKN5WGQMCXGQ18G"
   },
   "releases":[
      
   ],
   "released_from_release_id":null,
   "created_from_order_id":null,
   "cancelled_at":null,
   "customer":{
      "name":"Example Customer",
      "address":{
         "country":"US",
         "line_1":"10101 Bren Rd E",
         "line_2":null,
         "line_3":null,
         "locality":"Hopkins",
         "postal_code":"55343",
         "region":"MN",
         "urbanization":null,
         "residential":false,
         "geolocation":{
            "latitude":44.894716,
            "longitude":-93.40717719999999
         }
      },
      "identification_codes":[
         
      ],
      "phone_number":"+15555555555",
      "email":"example-customer@example.com"
   }
}

Release the Sales Order by Id

Note

The process documented below is a Supplier initiated release workflow. In the future, Shipwell will also support a Customer initiated workflow where customers do the initial request for order fulfillment from Suppliers.

To indicate that part or all of a sales order is ready to be fulfilled, a release is created. Just like the user interface workflow for a Supplier, the Supplier calling the API to create a release identifies the ready to ship date, pickup address, the quantity of items being shipped (whole or part of each order line item), the transportation detail around the items being shipped, and other details and submits the API request to create the release.

The Supplier's Customer will then know that the item(s) are ready to ship and the Customer can then ship orders similarly how they do within Shipwell today. The following is an example of the API call to Create a Sales Order Release.

Example request
curljavascriptpython
Copy
Copied
curl --location --request POST 'https://sandbox-api.shipwell.com/sales-orders/{orderId}/releases/' \
--header 'Authorization: YOUR_AUTHORIZATION_HEADER' \
--form 'data="{
   \"release_type\":\"ORDER\",
   \"items\":[
      {
         \"released_from_item_id\":\"01HH2S8YNAF2QYSE9YC1AGJZXB\",
         \"released_amount\":{
            \"unit\":\"PALLET\",
            \"value\":\"1\"
         },
         \"shipping_requirements\":{
            \"description\":\"DASDry1\",
            \"identifying_marks\":[
               
            ],
            \"references\":[
               
            ],
            \"product_id\":\"112994ff-dc26-4fd3-a25b-b214db4522e5\",
            \"stackable\":true,
            \"quantity\":1,
            \"packaging_type\":\"PALLET\",
            \"dimensions\":{
               \"length\":\"60\",
               \"height\":\"42\",
               \"width\":\"54\",
               \"unit\":\"IN\"
            },
            \"gross_weight\":{
               \"value\":\"700\",
               \"unit\":\"LB\"
            }
         }
      }
   ],
   \"ship_from\":{
      \"country\":\"US\",
      \"postal_code\":\"60661\",
      \"line_1\":\"567 W Lake St\",
      \"region\":\"IL\",
      \"locality\":\"Chicago\",
      \"timezone\":\"America/Chicago\",
      \"residential\":false,
      \"custom_data\":{
         \"shipwell_custom_data\":{
            \"purchase_order_stop\":{
               \"bb0312a6-4145-40df-9b17-06d93a03dce6\":\"11111\"
            }
         }
      },
      \"company_name\":\"Test Supplier\",
      \"references\":[
         
      ],
      \"shipping_requirements\":{
         
      }
   },
   \"message\":\"Part of the shipment is ready. This is just an example note.\"
}"'
Copy
Copied
const form = new FormData();
const payload = {
   "release_type":"ORDER",
   "items":[
      {
         "released_from_item_id":"01HH2S8YNAF2QYSE9YC1AGJZXB",
         "released_amount":{
            "unit":"PALLET",
            "value":"1"
         },
         "shipping_requirements":{
            "description":"DASDry1",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "product_id":"112994ff-dc26-4fd3-a25b-b214db4522e5",
            "stackable":true,
            "quantity":1,
            "packaging_type":"PALLET",
            "dimensions":{
               "length":"60",
               "height":"42",
               "width":"54",
               "unit":"IN"
            },
            "gross_weight":{
               "value":"700",
               "unit":"LB"
            }
         }
      }
   ],
   "ship_from":{
      "country":"US",
      "postal_code":"60661",
      "line_1":"567 W Lake St",
      "region":"IL",
      "locality":"Chicago",
      "timezone":"America/Chicago",
      "residential":false,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               "bb0312a6-4145-40df-9b17-06d93a03dce6":"11111"
            }
         }
      },
      "company_name":"Test Supplier",
      "references":[
         
      ],
      "shipping_requirements":{
         
      }
   },
   "message":"Part of the shipment is ready. This is just an example note."
};
form.append("data", JSON.stringify(payload));

const orderId = "YOUR_orderId_PARAMETER";
const basePath = "";
const hostPath = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${hostPath}${basePath}/sales-orders/${orderId}/releases/`,
  {
    method: "POST",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    },
    body: form
  }
);

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

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

headers = {"Content-Type": "multipart/form-data", "Authorization": "YOUR_AUTHORIZATION_HEADER"}

payload = {
   "release_type":"ORDER",
   "items":[
      {
         "released_from_item_id":"01HH2S8YNAF2QYSE9YC1AGJZXB",
         "released_amount":{
            "unit":"PALLET",
            "value":"1"
         },
         "shipping_requirements":{
            "description":"DASDry1",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "product_id":"112994ff-dc26-4fd3-a25b-b214db4522e5",
            "stackable":True,
            "quantity":1,
            "packaging_type":"PALLET",
            "dimensions":{
               "length":"60",
               "height":"42",
               "width":"54",
               "unit":"IN"
            },
            "gross_weight":{
               "value":"700",
               "unit":"LB"
            }
         }
      }
   ],
   "ship_from":{
      "country":"US",
      "postal_code":"60661",
      "line_1":"567 W Lake St",
      "region":"IL",
      "locality":"Chicago",
      "timezone":"America/Chicago",
      "residential":False,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               "bb0312a6-4145-40df-9b17-06d93a03dce6":"11111"
            }
         }
      },
      "company_name":"Test Supplier",
      "references":[
         
      ],
      "shipping_requirements":{
         
      }
   },
   "message":"Part of the shipment is ready. This is just an example note."
}

multipart_data = {
    "data": (None, json.dumps(payload)),
}

response = requests.post(target_url, headers=headers, files=multipart_data)
data = response.json()
print(data)
Example response
Copy
Copied
{
   "release_type":"ORDER",
   "ready_to_ship_at":null,
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "line_2":null,
      "line_3":null,
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "urbanization":null,
      "residential":false,
      "geolocation":null,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               "bb0312a6-4145-40df-9b17-06d93a03dce6":"11111"
            }
         }
      },
      "timezone":"America/Chicago",
      "location_number":null,
      "company_name":"Test Supplier",
      "references":[
         
      ]
   },
   "id":"01HH2SDJTZG8SZ33CNYWSRXBPM",
   "created_from_order_id":"01HH2S8YMYPYWSY67C2PRWKQHV",
   "status":"ACCEPTED",
   "released_onto_order_id":"01HH2SDJT83M0YS2PKQQ7RJ6K2",
   "accepted_at":"2023-12-07T18:42:39.503390+00:00",
   "rejected_at":null,
   "cancelled_at":null,
   "items":[
      {
         "released_from_item_id":"01HH2S8YNAF2QYSE9YC1AGJZXB",
         "released_amount":{
            "unit":"PALLET",
            "value":"1"
         },
         "shipping_requirements":{
            "description":"DASDry1",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":{
               "unit":"IN",
               "length":"60",
               "height":"42",
               "width":"54"
            },
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":null,
            "product_id":"112994ff-dc26-4fd3-a25b-b214db4522e5",
            "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":{
               "unit":"LB",
               "value":"700"
            },
            "quantity":1,
            "packaging_type":"PALLET"
         },
         "released_to_item_id":"01HH2SDJTM15H3BWEP8306N812"
      }
   ],
   "documents":[
      
   ]
}

From this a new child sales order is created from the parent/original sales order and the order number is incremented with a -N where N is the number of releases created from the sales order, e.g. {orderNumber}-1. In the response above the child sales order is identified as "released_onto_order_id": "01HH2SDJT83M0YS2PKQQ7RJ6K2".

Now get the details of the newly created child sales order if needed by calling the same Get Sales Order by Id documented above using the child sales order's id. The response will look similar to the following:

Example response
Copy
Copied
{
   "custom_data":{
      "shipwell_custom_data":{
         "purchase_order":{
            
         }
      }
   },
   "order_number":"1272-1",
   "ship_to":{
      "country":"US",
      "line_1":"515 Congress Ave.",
      "line_2":"Unit 2650",
      "line_3":null,
      "locality":"Austin",
      "postal_code":"78701",
      "region":"TX",
      "urbanization":null,
      "residential":false,
      "geolocation":{
         "latitude":30.2677547,
         "longitude":-97.74260179999999
      },
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               "bb0312a6-4145-40df-9b17-06d93a03dce6":"22222"
            }
         }
      },
      "timezone":"America/Chicago",
      "location_number":null,
      "company_name":"Shipwell",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":null
      }
   },
   "name":null,
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "line_2":null,
      "line_3":null,
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "urbanization":null,
      "residential":false,
      "geolocation":null,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               "bb0312a6-4145-40df-9b17-06d93a03dce6":"11111"
            }
         }
      },
      "timezone":"America/Chicago",
      "location_number":null,
      "company_name":"Test Supplier",
      "references":[
         
      ],
      "shipping_requirements":{
         "plan_window":null
      }
   },
   "description":null,
   "source":null,
   "source_system_id":null,
   "start_date":"2023-12-01",
   "expiration_date":"2024-01-31",
   "references":[
      {
         "qualifier":"PURCHASE_ORDER_NUMBER",
         "value":"11112222"
      }
   ],
   "id":"01HH2SDJT83M0YS2PKQQ7RJ6K2",
   "order_type":"SALES_ORDER",
   "status":"READY",
   "items":[
      {
         "custom_data":null,
         "amount":{
            "unit":"PALLET",
            "value":"1"
         },
         "shipping_requirements":{
            "description":"DASDry1",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":{
               "unit":"IN",
               "length":"60",
               "height":"42",
               "width":"54"
            },
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":null,
            "product_id":"112994ff-dc26-4fd3-a25b-b214db4522e5",
            "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":{
               "unit":"LB",
               "value":"700"
            },
            "quantity":1,
            "packaging_type":"PALLET"
         },
         "id":"01HH2SDJTM15H3BWEP8306N812",
         "available_amount":{
            "unit":"PALLET",
            "value":"1"
         }
      }
   ],
   "supplier_created_releases_allowed":true,
   "supplier":{
      "name":"Test Supplier",
      "address":{
         "country":"US",
         "line_1":"567 W Lake St",
         "line_2":null,
         "line_3":null,
         "locality":"Chicago",
         "postal_code":"60661",
         "region":"IL",
         "urbanization":null,
         "residential":false,
         "geolocation":null
      },
      "identification_codes":[
         
      ],
      "phone_number":"+15555555555",
      "email":"test@example.com",
      "supplier_id":"01H2XMX72CBBKN5WGQMCXGQ18G"
   },
   "releases":[
      
   ],
   "released_from_release_id":"01HH2SDJTZG8SZ33CNYWSRXBPM",
   "created_from_order_id":"01HH2S8YMYPYWSY67C2PRWKQHV",
   "cancelled_at":null,
   "customer":{
      "name":"Example Customer",
      "address":{
         "country":"US",
         "line_1":"10101 Bren Rd E",
         "line_2":null,
         "line_3":null,
         "locality":"Hopkins",
         "postal_code":"55343",
         "region":"MN",
         "urbanization":null,
         "residential":false,
         "geolocation":{
            "latitude":44.894716,
            "longitude":-93.40717719999999
         }
      },
      "identification_codes":[
         
      ],
      "phone_number":"+15555555555",
      "email":"example-customer@example.com"
   }
}

To obtain the details and status of the release, this may be looked up from the child order's id and the released_from_release_id property, e.g. "released_from_release_id":"01HH2SDJTZG8SZ33CNYWSRXBPM", together.

Example request
curljavascriptpython
Copy
Copied
curl --location --request GET 'https://sandbox-api.shipwell.com/sales-orders/{orderId}/releases/{releaseId}' \
    --header 'Authorization: YOUR_AUTHORIZATION_HEADER'
Copy
Copied
const orderId = "YOUR_orderId_PARAMETER";
const releaseId = "YOUR_releaseId_PARAMETER";
const basePath = "";
const hostPath = "sandbox-api.shipwell.com";

const targetUrl = `https://${hostPath}${basePath}/sales-orders/${orderId}/releases/${releaseId}`;

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

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

order_id = "YOUR_orderId_PARAMETER"
release_id = "YOUR_releaseId_PARAMETER";
base_path = ""
host_path = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host_path
    + base_path
    + "/sales-orders/" 
    + order_id 
    + "/releases/"
    + release_id
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

response = requests.get(target_url, headers=headers)
data = response.json()
print(data)
Example response
Copy
Copied
{
   "release_type":"ORDER",
   "ready_to_ship_at":null,
   "ship_from":{
      "country":"US",
      "line_1":"567 W Lake St",
      "line_2":null,
      "line_3":null,
      "locality":"Chicago",
      "postal_code":"60661",
      "region":"IL",
      "urbanization":null,
      "residential":false,
      "geolocation":null,
      "custom_data":{
         "shipwell_custom_data":{
            "purchase_order_stop":{
               "bb0312a6-4145-40df-9b17-06d93a03dce6":"11111"
            }
         }
      },
      "timezone":"America/Chicago",
      "location_number":null,
      "company_name":"Test Supplier",
      "references":[
         
      ]
   },
   "id":"01HH2SDJTZG8SZ33CNYWSRXBPM",
   "created_from_order_id":"01HH2S8YMYPYWSY67C2PRWKQHV",
   "status":"ACCEPTED",
   "released_onto_order_id":"01HH2SDJT83M0YS2PKQQ7RJ6K2",
   "accepted_at":"2023-12-07T18:42:39.503390+00:00",
   "rejected_at":null,
   "cancelled_at":null,
   "items":[
      {
         "released_from_item_id":"01HH2S8YNAF2QYSE9YC1AGJZXB",
         "released_amount":{
            "unit":"PALLET",
            "value":"1"
         },
         "shipping_requirements":{
            "description":"DASDry1",
            "identifying_marks":[
               
            ],
            "references":[
               
            ],
            "tare_weight":null,
            "dimensions":{
               "unit":"IN",
               "length":"60",
               "height":"42",
               "width":"54"
            },
            "volume":null,
            "customer_reference_number":null,
            "hazmat":null,
            "temperature":null,
            "product_id":"112994ff-dc26-4fd3-a25b-b214db4522e5",
            "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":{
               "unit":"LB",
               "value":"700"
            },
            "quantity":1,
            "packaging_type":"PALLET"
         },
         "released_to_item_id":"01HH2SDJTM15H3BWEP8306N812"
      }
   ],
   "documents":[
      
   ]
}

Order Statuses

See the order statuses page for details on each order status.

Order Release Statuses

See the order release statuses page for details on each order release status.

Supplier Portal Future Enhancements

Supplier Portal is a place for flexible engagement and collaboration between customers and suppliers, and Shipwell will continue to iterate Supplier Portal to drive to this vision. There are a variety of enhancements that are planned for the Supplier Portal soon including support for the following items:

  • Support for load optimization and bulk creation of multiple shipments from multiple orders
  • Order dashboard side panel containing shipment details and timeline
  • Support for a customer-initiated order-fulfillment workflow
  • In-platform messaging between customers and suppliers
Copyright © Shipwell 2024. All right reserved.