Orders (v2/Legacy)

Note

This documentation is for Shipwell's Orders (v2/Legacy) API. If you are a new Shipwell customer, use Shipwell Dock Scheduling, or Shipwell Supplier Portal then reference the modern Orders framework documentation here.

Purchase orders create a potential agreement between a shipper and a carrier, ensuring that all products, destinations, and pricing are agreed upon before the shipment begins. In many ways, a purchase order could be considered the first step in the shipping process.

In the case of Shipwell's API, creating an order ensures the following benefits:

Ability to incorporate purchase orders into your ERP system, such as Netsuite.
Ability to make automated carrier requests based on Webhooks .

Purchase orders are created using the POST purchase-order endpoint. When calling this endpoint, you can include line items in the request body (see example below, previously line items had to be created in a separate call).

Purchase Orders are updated using the PUT purchase-order/:purchase-order-id endpoint. When updating the Purchase Order, existing line items can be updated as well. If you want to add a new line item to an existing purchase order, you must create it using POST purchase-order/:purchase-order-id/line-items/, see example below.

Make a purchase order

To make a purchase order, the following fields are required:

order_number : This can be anything the user wants.
destination_address : An address in which will receive the order.
origin_address : Acts as the pickup address, the address in which the order originates.
customer_name : The name of the facility or customer who will receive the order.
planned_delivery_start_datetime : A dateTime that gives the beginning time an order can be delivered. _end_ is not required to build an order.
planned_pickup_start_datetime : A dateTime that provides the time that a carrier can pick up an order. _end_ is not required to build an order.

You can pull additional fields from shipments.

Example request

Copy

Copied

curl --location --request POST 'https://sandbox-api.shipwell.com/v2/purchase-orders/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <user-token>' \
--data-raw '{
    "order_number": "0567203d-8394-4fd1-bbd7-5db597f9c845",
    "destination_address": {
        "address_1": "220 Shipwell Ln",
        "address_2": "#440",
        "city": "Austin",
        "country": "US",
        "created_at": "2012-04-01T05:03:14.102Z",
        "formatted_address": "consectetur quis commodo exercitation",
        "id": "urn:uuid:07780a31-c0c2-c1ac-bafe-574c85068d56",
        "latitude": -90023785.56123425,
        "longitude": 55137538.876537085,
        "phone_number": "(210) 846-7868",
        "postal_code": "78752",
        "state_province": "TX",
        "timezone": "CST",
        "updated_at": "1975-06-10T05:49:47.017Z"
    },
    "origin_address": {
        "address_1": "250 Shipwell Ave",
        "address_2": "",
        "city": "San Francisco",
        "country": "US",
        "created_at": "2018-10-25T22:39:00.944Z",
        "latitude": 50564396.23809835,
        "longitude": -84721426.35087083,
        "postal_code": "94016",
        "state_province": "CA",
        "timezone": "PST",
        "updated_at": "1955-10-31T07:08:03.515Z"
    },
    "source": "IMPORT",
    "planned_pickup_start_datetime": "2020-09-01T13:14:00.000000Z",
    "planned_pickup_end_datetime": "2020-09-01T15:14:00.000000Z",
    "planned_delivery_start_datetime": "2020-09-05T20:44:00.000000Z",
    "planned_delivery_end_datetime": "2020-09-05T21:14:00.000000Z",
    "line_items": [
       {
                    "id": "7c4b797c-cfe3-4d1e-899b-4c78db21ec22",
                    "created_at": "2020-08-20T16:39:12.783492Z",
                    "updated_at": "2021-02-08T17:45:46.825606Z",
                    "piece_type": "BAG",
                    "package_type": "PLT",
                    "freight_class": "70",
                    "nmfc_item_code": "100",
                    "nmfc_sub_code": "300",
                    "stackable": false,
                    "hazmat_hazard_class": null,
                    "hazmat_identification_number": null,
                    "hazmat_proper_shipping_name": null,
                    "hazmat_packing_group": null,
                    "height": 14.0,
                    "length": 12.0,
                    "width": 12.0,
                    "length_unit": "IN",
                    "value_per_piece": 20.35,
                    "description": "Test",
                    "product_ref": "Test",
                    "total_packages": 2,
                    "total_pieces": 10,
                    "weight_unit": "LB",
                    "refrigeration_required": false,
                    "refrigeration_min_temp": null,
                    "refrigeration_max_temp": null,
                    "temp_unit": "F",
                    "provider_specific_packaging": null,
                    "package_weight": 50.0,
                    "total_line_item_weight": 100.0,
                    "country_of_manufacture": null
                }
    ]
}'

Example response

Copy

Copied

{
    "id": "3ebec19c-d195-4848-b226-85d0b5834827",
    "created_at": "2021-03-30T20:21:49.147856Z",
    "updated_at": "2021-03-30T20:21:49.149947Z",
    "order_number": "0567203d-8394-4fd1-bbd7-5db597f9c845",
    "description": null,
    "source": "IMPORT",
    "source_system_id": null,
    "status": "",
    "customer_external_id": null,
    "customer_name": null,
    "supplier_external_id": null,
    "supplier_name": null,
    "planned_pickup_start_datetime": "2020-09-01T13:14:00.000000Z",
    "planned_pickup_end_datetime": "2020-09-01T15:14:00.000000Z",
    "planned_delivery_start_datetime": "2020-09-05T20:44:00.000000Z",
    "planned_delivery_end_datetime": "2020-09-05T21:14:00.000000Z",
    "actual_pickup_datetime": null,
    "actual_delivery_datetime": null,
    "created_by_user": {
        "id": "ad2fc7eb-bc6f-4134-a0d2-2719fdc3321f",
        "first_name": "Nate",
        "last_name": "Archer",
        "email": "nate.archer@shipwell.com",
        "phone_number": "+12108467868",
        "avatar": "https://s3.us-west-2.amazonaws.com/dev.user-avatars.shipwell.com/user-avatars/custom/ad2fc7eb-bc6f-4134-a0d2-2719fdc3321f.png"
    },
    "origin_address": {
        "id": "bf7f30e4-071b-4dbe-82f2-54e1723c4551",
        "address_1": "250 Shipwell Ave",
        "address_2": "",
        "city": "San Francisco",
        "state_province": "CA",
        "postal_code": "94016",
        "country": "US",
        "phone_number": null,
        "latitude": 50564396.23809835,
        "longitude": -84721426.35087083,
        "timezone": "PST",
        "formatted_address": "250 Shipwell Ave, San Francisco, CA 94016, US",
        "created_at": "2021-03-30T20:21:49.137395Z",
        "updated_at": "2021-03-30T20:21:49.138509Z"
    },
    "destination_address": {
        "id": "04f4d2d5-bc49-4e10-9d0b-caebae157a8a",
        "address_1": "220 Shipwell Ln",
        "address_2": "#440",
        "city": "Austin",
        "state_province": "TX",
        "postal_code": "78752",
        "country": "US",
        "phone_number": "+12108467868",
        "latitude": -90023785.56123425,
        "longitude": 55137538.876537085,
        "timezone": "CST",
        "formatted_address": "220 Shipwell Ln #440, Austin, TX 78752, US",
        "created_at": "2021-03-30T20:21:49.144349Z",
        "updated_at": "2021-03-30T20:21:49.145321Z"
    },
    "subtotal_amount": null,
    "tax_amount": null,
    "invoice_external_id": null,
    "shipment": null,
    "origin_stop": null,
    "destination_stop": null,
    "archived": false,
    "origin_dock_external_id": null,
    "destination_dock_external_id": null,
    "company": "a54ef012-77d4-44a0-8ba5-115b09b655be",
    "line_items": [],
    "subtotal_amount_currency": "USD",
    "tax_amount_currency": "USD",
    "custom_data": null,
    "origin_address_book_entry": null,
    "destination_address_book_entry": null,
    "name": null,
    "origin_stop_alerts": [],
    "destination_stop_alerts": [],
    "transit_status": null,
    "transit_status_reason_code": null,
    "overall_status": "UNASSIGNED"
}

Add an order line item

Line items are a list of products associated with the order. The product_ref field is used to link the line item to products in either the Shipwell system or your ERP system, but it is not required. This body also includes product-related options, such as description, length, andlength_unit. As with shipments, you can add multiple line items.

In the following example, a type of glass cleaner is added to a purchase order. Before testing this example on your own, replace the purchaseOrderId with the purchase order you want to add the line item.

Example request

Copy

Copied

curl --location --request POST 'https://sandbox-api.shipwell.com/v2/purchase-orders/:purchaseOrderId/line-items/' \
--header 'Content-Type: application/json' \
--header 'Authorization: token {your-auth-token}' \
--data-raw '{
  "product_ref": null,
  "description": "SUPVA45 - 8/32OZ ESS.EVERY GLASS CLEANE",
  "package_type": "PLT",
  "package_weight": "6000",
  "length": 48,
  "width": 40,
  "height": 54,
  "weight_unit": "LB",
  "length_unit": "IN",
  "stackable": false,
  "refrigeration_min_temp": null,
  "refrigeration_max_temp": null,
  "custom_data": {
    "shipwell_custom_data": {}
  },
  "country_of_manufacture": null,
  "calculatedFreightClass": 50,
  "total_packages": "5"
}

Example response

Copy

Copied

{
    "id": "50b3b10c-acda-4604-88c5-61009fc58583",
    "created_at": "2021-06-28T13:02:17.567609Z",
    "updated_at": "2021-06-28T13:02:17.568864Z",
    "piece_type": null,
    "package_type": "PLT",
    "freight_class": null,
    "nmfc_item_code": null,
    "nmfc_sub_code": null,
    "stackable": false,
    "hazmat_hazard_class": null,
    "hazmat_identification_number": null,
    "hazmat_proper_shipping_name": null,
    "hazmat_packing_group": null,
    "height": 54.0,
    "length": 48.0,
    "width": 40.0,
    "length_unit": "IN",
    "value_per_piece": null,
    "purchase_order": "9c780b4c-1d6d-4ee6-b149-4d18860ecfc5",
    "description": "SUPVA45 - 8/32OZ ESS.EVERY GLASS CLEANE",
    "product_ref": null,
    "total_packages": 5,
    "total_pieces": null,
    "weight_unit": "LB",
    "refrigeration_required": false,
    "refrigeration_min_temp": null,
    "refrigeration_max_temp": null,
    "temp_unit": "F",
    "provider_specific_packaging": null,
    "custom_data": {
        "shipwell_custom_data": {}
    },
    "package_weight": 6000.0,
    "total_line_item_weight": 30000.0,
    "country_of_manufacture": null
}

Working with Orders and Shipments

To maintain high performance, Orders and Shipments are retrieved through separate API endpoints. As Orders move through the planning process and are assigned to Shipments for execution, you can retrieve the full details of an Order and the Stops it is associated with using the following pattern:

First, get the Shipment details - GET /shipments/:shipment-id/

The response will include the line items on the shipment, each of which contains a purchase_order field linking to the original order

Copy

Copied

    "line_items": [
        {
            "id": "27d186cf-2ffa-4d6f-96ce-e20848ae1eca",
            "formatted_description": "68,900 lb (31,252.51429 kg), Paper Clips",
            "insured_value": null,
            "value_per_piece": null,
            "deleted_at": null,
            "created_at": "2020-08-26T17:07:24.503043Z",
            "updated_at": "2020-08-26T17:07:24.503915Z",
            "custom_data": null,
            "piece_type": null,
            "package_type": null,
            "freight_class": null,
            "provider_specific_packaging": null,
            "nmfc_item_code": null,
            "nmfc_sub_code": null,
            "stackable": false,
            "hazmat_hazard_class": null,
            "hazmat_identification_number": null,
            "hazmat_proper_shipping_name": null,
            "hazmat_packing_group": null,
            "height": null,
            "length": null,
            "width": null,
            "length_unit": "IN",
            "value_per_piece_currency": "USD",
            "package_weight": 6890.0,
            "weight_unit": "LB",
            "refrigeration_required": false,
            "refrigeration_min_temp": null,
            "refrigeration_max_temp": null,
            "temp_unit": "F",
            "country_of_manufacture": null,
            "product_ref": null,
            "description": "Paper Clips",
            "total_packages": 10,
            "total_pieces": null,
            "insured_value_currency": "USD",
            "dry_ice_weight": null,
            "dry_ice_weight_unit": "LB",
            "purchase_order": "5d6b01b3-db34-475e-9693-9fa2549014d0"
        }
    ]

Next, fetch the Order details using the purchase_order ID found in the line item details above - GET /purchase-orders/:purchase-order-id/

Example Response

Copy

Copied

    "id":"5d6b01b3-db34-475e-9693-9fa2549014d0",
    "created_at":"2021-05-06T18:10:59.694397Z",
    "updated_at":"2021-05-06T18:10:59.697545Z",
    "order_number":"NC-1620324294398",
    "description":null,
    "purchase_order_number":null,
    "source":"SHIPWELL_WEB",
    "source_system_id":null,
    "status":"",
    "customer_external_id":"3420",
    "customer_name":"QA Test",
    "supplier_external_id":"3419",
    "supplier_name":"Nick Test",
    "planned_pickup_start_datetime":"2021-05-06T00:00:00.000000Z",
    "planned_pickup_end_datetime":"2021-05-07T00:00:00.000000Z",
    "planned_delivery_start_datetime":"2021-05-08T00:00:00.000000Z",
    "planned_delivery_end_datetime":"2021-05-09T00:00:00.000000Z",
    "actual_pickup_datetime":null,
    "actual_delivery_datetime":null,
    "origin_address":{"id":"36ca6809-a460-44bb-8d1b-7faf3baa1284",
    "address_1":"722 Preston Ave",
    "address_2":null,
    "city":"Charlottesville",
    "state_province":"VA",
    "postal_code":"22903",
    "country":"US",
    "phone_number":null,
    "latitude":38.0360074,
    "longitude":-78.4880701,
    "timezone":"America/New_York",
    "formatted_address":"722 Preston Ave, Charlottesville, VA 22903, US",
    "created_at":"2021-05-06T18:10:59.681280Z",
    "updated_at":"2021-05-06T18:10:59.682147Z"},
    "destination_address":{"id":"a7b9c8f9-744e-494a-a085-aad70ca34e0d",
    "address_1":"5391 Three Notched Rd",
    "address_2":null,
    "city":"Crozet",
    "state_province":"VA",
    "postal_code":"22932",
    "country":"US",
    "phone_number":null,
    "latitude":38.0693683,
    "longitude":-78.6861413,
    "timezone":"America/New_York",
    "formatted_address":"5391 Three Notched Rd, Crozet, VA 22932, US",
    "created_at":"2021-05-06T18:10:59.689880Z",
    "updated_at":"2021-05-06T18:10:59.691327Z"},
    "subtotal_amount":null,
    "tax_amount":null,
    "invoice_external_id":null,
    "shipment":,
    "origin_stop":"b3caa7c5-8c01-4762-8502-dead4c5d932b",
    "destination_stop":"e795f928-3b19-4767-b97b-b4c4eebd93b5",
    "archived":false,
    "origin_dock_external_id":null,
    "destination_dock_external_id":null,
    "company":"a54ef012-77d4-44a0-8ba5-115b09b655be",
    "line_items":[
        {
            "id": "99a186cf-2ffa-4d6f-96ce-e20848ae1eca",
            "formatted_description": "68,900 lb (31,252.51429 kg), Paper Clips",
            "insured_value": null,
            "value_per_piece": null,
            "deleted_at": null,
            "created_at": "2020-08-26T17:07:24.503043Z",
            "updated_at": "2020-08-26T17:07:24.503915Z",
            "custom_data": null,
            "piece_type": null,
            "package_type": null,
            "freight_class": null,
            "provider_specific_packaging": null,
            "nmfc_item_code": null,
            "nmfc_sub_code": null,
            "stackable": false,
            "hazmat_hazard_class": null,
            "hazmat_identification_number": null,
            "hazmat_proper_shipping_name": null,
            "hazmat_packing_group": null,
            "height": null,
            "length": null,
            "width": null,
            "length_unit": "IN",
            "value_per_piece_currency": "USD",
            "package_weight": 6890.0,
            "weight_unit": "LB",
            "refrigeration_required": false,
            "refrigeration_min_temp": null,
            "refrigeration_max_temp": null,
            "temp_unit": "F",
            "country_of_manufacture": null,
            "product_ref": null,
            "description": "Paper Clips",
            "total_packages": 10,
            "total_pieces": null,
        }
    ],
    "subtotal_amount_currency":"USD",
    "tax_amount_currency":"USD",
    "custom_data":null,
    "origin_address_book_entry":null,
    "destination_address_book_entry":null,
    "name":"NC Order-1620324294398",
    "origin_stop_alerts":[],
    "destination_stop_alerts":[],
    "transit_status":null,
    "transit_status_reason_code":null,
    "overall_status":"ASSIGNED"

Alternatively, you can fetch all Orders associated with a given Shipment at once using GET /purchase-orders/?archived=true&archived=false&shipment_id={shipmentId}

When an Order is assigned to a Shipment, the origin_stop and destination_stop field contain the UUID of the Shipment Stop that they are picking up from and delivering to, respectively. You can use this information, along with the Shipment details from the first API call, to associate Orders with individual Stops.