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
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
{
"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
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
{
"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
}