Orders

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://dev-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://dev-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
}