Create a new purchase order `(Legacy/v2)`

SecurityAuthToken
Request
Request Body schema: application/json

Create/Update an order

The route includes /purchase-orders/ but should be considered as generic orders. It does not imply there is a different route for sales orders and transfer orders. This will be updated in the future with an enhanced data model to support different order types, for now use the purchase order for all types of orders and if needed extend the the object with custom_data to specify the type of order.

actual_delivery_datetime
string or null <date-time>
actual_pickup_datetime
string or null <date-time>
archived
boolean

Default "false"

company
string or null <uuid>

Ignored in requests, returns UUID of the creating user's company

created_at
string or null <date-time>

Ignored in requests, date created

object or null

Ignored in requests, returns the creating user

object or null

Custom data for PurchaseOrder

customer_external_id
string or null
customer_name
string or null

The name of the facility or customer who will receive the order.

description
string or null
required
object

An address in which will receive the order.

destination_address_book_entry
string or null <uuid>

Can be used to reference an address book entry object but does not act as a helper function to populate the destination address

destination_dock_external_id
string or null

Destination dock id of the purchase order from the company's external system

destination_stop
string or null <uuid>

Can be used to reference stop object

Array of objects or null
id
string <uuid>

Ignored in requests, returns id of the purchase-order

invoice_external_id
string or null
Array of objects or null (PurchaseOrderLineItem)
name
string or null
order_number
required
string

This can be anything the user wants.

required
object

Acts as the pickup address, the address in which the order originates.

origin_address_book_entry
string or null <uuid>

Can be used to reference an address book entry object but does not act as a helper function to populate the origin address

origin_dock_external_id
string or null

Origin dock id of the purchase order from the company's external system

origin_stop
string or null <uuid>

Can be used to reference stop object

Array of objects or null
overall_status
string or null

Read-only status of a purchase order that, if no transit_status exists, will describe shipment assignment

Enum: "ASSIGNED" "UNASSIGNED" "IN_TRANSIT" "DELIVERED" "DISPATCHED" "OUT_FOR_DELIVERY"
planned_delivery_end_datetime
string or null <date-time>
planned_delivery_start_datetime
string or null <date-time>

A dateTime that gives the beginning time an order can be delivered.

planned_pickup_end_datetime
string or null <date-time>
planned_pickup_start_datetime
string or null <date-time>

A dateTime that provides the time that a carrier can pick up an order.

purchase_order_number
string or null
shipment
string or null <uuid>

Can be used to reference shipment object. If a purchase order is assigned to a shipment and the purchase order is updated without the shipment uuid, the stops on the shipment will be removed.

source
required
string
Enum: "SHIPWELL_WEB" "IMPORT" "TENDER" "SHIPWELL_WEB_UNAUTH"
source_system_id
string or null
status
string or null
subtotal_amount
number or null
subtotal_amount_currency
string or null
Default: "USD"
Enum: "CAD" "USD"
supplier_external_id
string or null
supplier_name
string or null
tax_amount
number or null
tax_amount_currency
string or null
Default: "USD"
Enum: "CAD" "USD"
transit_status
string or null
Enum: "PICKED_UP" "IN_TRANSIT" "DELIVERED" "EXCEPTIONS" "CANCELLED"
transit_status_reason_code
string or null
Enum: "ACCIDENT" "ADDRESS_CORRECTED_DELIVERY_ATTEMPTED" "ALTERNATE_CARRIER_DELIVERED" "ALTERNATE_CARRIER_PICKED_UP" "AWAITING_EXPORT" "AWAITING_IMPORT" "BORDER_CLEARANCE" "CARRIER_DISPATCH_ERROR" "CARRIER_KEYING_ERROR" "CARRIER_RELATED" "CARTAGE_AGENT" "CASH_NOT_AVAILABLE_FROM_CONSIGNEE" "CIVIL_EVENT" "COLLECT_ON_DELIVERY_REQUIRED" "CONSIGNEE_CLOSED" "CONSIGNEE_RELATED" "CONTAMINATED" "CREDIT_HOLD" "CUSTOMER_REQUESTED_DIFFERENT_DELIVERY_WINDOW" "CUSTOMER_REQUESTED_FUTURE_DELIVERY" "CUSTOMER_STRIKE" "CUSTOMER_VACATION" "CUSTOMER_WANTED_EARLIER_DELIVERY" "CUSTOMS_DOCUMENTATION_PROBLEM" "DAMAGED" "DELIVERY_SHORTAGE" "DRIVER_NOT_AVAILABLE" "DRIVER_RELATED" "EQUIPMENT_SHORTAGE" "EQUIPMENT_VOLUME_NOT_AVAILABLE" "EXCEEDS_SERVICE_LIMITATIONS" "FAILED_TO_RELEASE_BILLING" "FLATCAR_SHORTAGE" "HELD_FOR_CONSIGNEE" "HELD_FOR_FULL_CARRIER_LOAD" "HELD_FOR_PAYMENT" "HELD_FOR_PROTECTIVE_SERVICE" "HELD_PENDING_APPOINTMENT" "HELD_PER_SHIPPER" "HOLIDAY_CLOSED" "HOURS_OF_SERVICE_LIMIT" "IMPROPER_FACILITY_OR_EQUIPMENT" "IMPROPER_INTERNATIONAL_PAPERWORK" "IMPROPER_TEMPERATURE" "INCONSISTENT_WEIGHT" "INCORRECT_ADDRESS" "INDIRECT_DELIVERY" "INSUFFICIENT_DELIVERY_TIME" "INSUFFICIENT_PICKUP_TIME" "INSUFFICIENT_TRAVEL_TIME_DETECTED" "INTERNATIONAL_NON_CARRIER_DELAY" "LATE_TENDER_DISPATCH" "LOCATION_CHANGE" "LOAD_SHIFTED" "MECHANICAL_BREAKDOWN" "MIS_SORT" "MISSED_DELIVERY" "MISSED_PICK-UP" "MISSING_DOCUMENTS" "NON_EXPRESS_CLEARANCE_DELAY" "NORMAL_APPOINTMENT" "NORMAL_STATUS" "NO_APPOINTMENT_SCHEDULED" "NO_REQUESTED_ARRIVAL_DATE_OR_TIME" "NO_REQUESTED_ARRIVAL_TIME_PROVIDED_BY_SHIPPER" "OTHER" "PAST_CUT_OFF_TIME" "PREARRANGED_APPOINTMENT" "PREVIOUS_STOP" "PROCESSING_DELAY" "PRODUCTION_FALLDOWN" "RAILROAD_FAILED_TO_MEET_SCHEDULE" "RECIPIENT_UNAVAILABLE" "RECONSIGNED" "RECEIVING_TIME_RESTRICTED" "REFUSED_BY_CUSTOMER" "RESTRICTED_ARTICLES_UNACCEPTABLE" "RETURNED_TO_SHIPPER" "ROAD_CONDITIONS" "SHIPMENT_OVERWEIGHT" "SHIPPER_RELATED" "SUSPENDED_AT_CUSTOMER_REQUEST" "TRACKING_EVENT_AUTOMATED_CALL" "TRACKING_EVENT_EDI_UPDATE" "TRACKING_EVENT_ELD_UPDATE" "TRACKING_EVENT_GEOFENCE_BREACH" "TRACKING_EVENT_MANUAL_LOCATION_UPDATED" "TRACKING_EVENT_MOBILE_APP" "TRACKING_EVENT_MOBILE_APP_UPDATED_BY_DRIVER" "TRACTOR_CONVENTIONAL_NOT_AVAILABLE" "TRACTOR_WITH_SLEEPER_CAR_NOT_AVAILABLE" "TRAILER_CLASS_NOT_AVAILABLE" "TRAILER_NOT_AVAILABLE" "TRAILER_NOT_USABLE_DUE_TO_PRIOR_PRODUCT" "TRAIN_DERAILMENT" "TRAP_FOR_CUSTOMER" "UNABLE_TO_CONTACT_RECIPIENT" "UNABLE_TO_LOCATE" "UNKNOWN" "WAITING_FOR_CUSTOMER_PICKUP" "WAITING_FOR_CUSTOMER_SPECIFIED_CARRIER" "WAITING_INSPECTION" "WAITING_SHIPPING_INSTRUCTIONS" "WEATHER_OR_NATURAL_DISASTER"
updated_at
string or null <date-time>

Ignored in requests, date updated

Responses
201

Successfully returned a PurchaseOrder

Response Schema: application/json
actual_delivery_datetime
string or null <date-time>
actual_pickup_datetime
string or null <date-time>
archived
boolean

Default "false"

company
string or null <uuid>

Ignored in requests, returns UUID of the creating user's company

created_at
string or null <date-time>

Ignored in requests, date created

object or null

Ignored in requests, returns the creating user

object or null

Custom data for PurchaseOrder

customer_external_id
string or null
customer_name
string or null

The name of the facility or customer who will receive the order.

description
string or null
required
object

An address in which will receive the order.

destination_address_book_entry
string or null <uuid>

Can be used to reference an address book entry object but does not act as a helper function to populate the destination address

destination_dock_external_id
string or null

Destination dock id of the purchase order from the company's external system

destination_stop
string or null <uuid>

Can be used to reference stop object

Array of objects or null
id
string <uuid>

Ignored in requests, returns id of the purchase-order

invoice_external_id
string or null
Array of objects or null (PurchaseOrderLineItem)
name
string or null
order_number
required
string

This can be anything the user wants.

required
object

Acts as the pickup address, the address in which the order originates.

origin_address_book_entry
string or null <uuid>

Can be used to reference an address book entry object but does not act as a helper function to populate the origin address

origin_dock_external_id
string or null

Origin dock id of the purchase order from the company's external system

origin_stop
string or null <uuid>

Can be used to reference stop object

Array of objects or null
overall_status
string or null

Read-only status of a purchase order that, if no transit_status exists, will describe shipment assignment

Enum: "ASSIGNED" "UNASSIGNED" "IN_TRANSIT" "DELIVERED" "DISPATCHED" "OUT_FOR_DELIVERY"
planned_delivery_end_datetime
string or null <date-time>
planned_delivery_start_datetime
string or null <date-time>

A dateTime that gives the beginning time an order can be delivered.

planned_pickup_end_datetime
string or null <date-time>
planned_pickup_start_datetime
string or null <date-time>

A dateTime that provides the time that a carrier can pick up an order.

purchase_order_number
string or null
shipment
string or null <uuid>

Can be used to reference shipment object. If a purchase order is assigned to a shipment and the purchase order is updated without the shipment uuid, the stops on the shipment will be removed.

source
required
string
Enum: "SHIPWELL_WEB" "IMPORT" "TENDER" "SHIPWELL_WEB_UNAUTH"
source_system_id
string or null
status
string or null
subtotal_amount
number or null
subtotal_amount_currency
string or null
Default: "USD"
Enum: "CAD" "USD"
supplier_external_id
string or null
supplier_name
string or null
tax_amount
number or null
tax_amount_currency
string or null
Default: "USD"
Enum: "CAD" "USD"
transit_status
string or null
Enum: "PICKED_UP" "IN_TRANSIT" "DELIVERED" "EXCEPTIONS" "CANCELLED"
transit_status_reason_code
string or null
Enum: "ACCIDENT" "ADDRESS_CORRECTED_DELIVERY_ATTEMPTED" "ALTERNATE_CARRIER_DELIVERED" "ALTERNATE_CARRIER_PICKED_UP" "AWAITING_EXPORT" "AWAITING_IMPORT" "BORDER_CLEARANCE" "CARRIER_DISPATCH_ERROR" "CARRIER_KEYING_ERROR" "CARRIER_RELATED" "CARTAGE_AGENT" "CASH_NOT_AVAILABLE_FROM_CONSIGNEE" "CIVIL_EVENT" "COLLECT_ON_DELIVERY_REQUIRED" "CONSIGNEE_CLOSED" "CONSIGNEE_RELATED" "CONTAMINATED" "CREDIT_HOLD" "CUSTOMER_REQUESTED_DIFFERENT_DELIVERY_WINDOW" "CUSTOMER_REQUESTED_FUTURE_DELIVERY" "CUSTOMER_STRIKE" "CUSTOMER_VACATION" "CUSTOMER_WANTED_EARLIER_DELIVERY" "CUSTOMS_DOCUMENTATION_PROBLEM" "DAMAGED" "DELIVERY_SHORTAGE" "DRIVER_NOT_AVAILABLE" "DRIVER_RELATED" "EQUIPMENT_SHORTAGE" "EQUIPMENT_VOLUME_NOT_AVAILABLE" "EXCEEDS_SERVICE_LIMITATIONS" "FAILED_TO_RELEASE_BILLING" "FLATCAR_SHORTAGE" "HELD_FOR_CONSIGNEE" "HELD_FOR_FULL_CARRIER_LOAD" "HELD_FOR_PAYMENT" "HELD_FOR_PROTECTIVE_SERVICE" "HELD_PENDING_APPOINTMENT" "HELD_PER_SHIPPER" "HOLIDAY_CLOSED" "HOURS_OF_SERVICE_LIMIT" "IMPROPER_FACILITY_OR_EQUIPMENT" "IMPROPER_INTERNATIONAL_PAPERWORK" "IMPROPER_TEMPERATURE" "INCONSISTENT_WEIGHT" "INCORRECT_ADDRESS" "INDIRECT_DELIVERY" "INSUFFICIENT_DELIVERY_TIME" "INSUFFICIENT_PICKUP_TIME" "INSUFFICIENT_TRAVEL_TIME_DETECTED" "INTERNATIONAL_NON_CARRIER_DELAY" "LATE_TENDER_DISPATCH" "LOCATION_CHANGE" "LOAD_SHIFTED" "MECHANICAL_BREAKDOWN" "MIS_SORT" "MISSED_DELIVERY" "MISSED_PICK-UP" "MISSING_DOCUMENTS" "NON_EXPRESS_CLEARANCE_DELAY" "NORMAL_APPOINTMENT" "NORMAL_STATUS" "NO_APPOINTMENT_SCHEDULED" "NO_REQUESTED_ARRIVAL_DATE_OR_TIME" "NO_REQUESTED_ARRIVAL_TIME_PROVIDED_BY_SHIPPER" "OTHER" "PAST_CUT_OFF_TIME" "PREARRANGED_APPOINTMENT" "PREVIOUS_STOP" "PROCESSING_DELAY" "PRODUCTION_FALLDOWN" "RAILROAD_FAILED_TO_MEET_SCHEDULE" "RECIPIENT_UNAVAILABLE" "RECONSIGNED" "RECEIVING_TIME_RESTRICTED" "REFUSED_BY_CUSTOMER" "RESTRICTED_ARTICLES_UNACCEPTABLE" "RETURNED_TO_SHIPPER" "ROAD_CONDITIONS" "SHIPMENT_OVERWEIGHT" "SHIPPER_RELATED" "SUSPENDED_AT_CUSTOMER_REQUEST" "TRACKING_EVENT_AUTOMATED_CALL" "TRACKING_EVENT_EDI_UPDATE" "TRACKING_EVENT_ELD_UPDATE" "TRACKING_EVENT_GEOFENCE_BREACH" "TRACKING_EVENT_MANUAL_LOCATION_UPDATED" "TRACKING_EVENT_MOBILE_APP" "TRACKING_EVENT_MOBILE_APP_UPDATED_BY_DRIVER" "TRACTOR_CONVENTIONAL_NOT_AVAILABLE" "TRACTOR_WITH_SLEEPER_CAR_NOT_AVAILABLE" "TRAILER_CLASS_NOT_AVAILABLE" "TRAILER_NOT_AVAILABLE" "TRAILER_NOT_USABLE_DUE_TO_PRIOR_PRODUCT" "TRAIN_DERAILMENT" "TRAP_FOR_CUSTOMER" "UNABLE_TO_CONTACT_RECIPIENT" "UNABLE_TO_LOCATE" "UNKNOWN" "WAITING_FOR_CUSTOMER_PICKUP" "WAITING_FOR_CUSTOMER_SPECIFIED_CARRIER" "WAITING_INSPECTION" "WAITING_SHIPPING_INSTRUCTIONS" "WEATHER_OR_NATURAL_DISASTER"
updated_at
string or null <date-time>

Ignored in requests, date updated

default

Default error response

post/purchase-orders/
Request samples
application/json
{
  • "actual_delivery_datetime": "2019-08-24T14:15:22Z",
  • "actual_pickup_datetime": "2019-08-24T14:15:22Z",
  • "archived": true,
  • "company": "87340f10-f684-4b06-8427-5981380bd9a9",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_user": {
    },
  • "custom_data": {
    },
  • "customer_external_id": "string",
  • "customer_name": "string",
  • "description": "string",
  • "destination_address": {
    },
  • "destination_address_book_entry": "ec679ff9-f6ca-40cd-9240-fc673371afec",
  • "destination_dock_external_id": "string",
  • "destination_stop": "9f2c2b22-33f4-4d9a-8d9e-5bae44ad8c1e",
  • "destination_stop_alerts": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invoice_external_id": "string",
  • "line_items": [
    ],
  • "name": "string",
  • "order_number": "string",
  • "origin_address": {
    },
  • "origin_address_book_entry": "a3c225dc-c7d7-4c94-b9ff-16919e5a505f",
  • "origin_dock_external_id": "string",
  • "origin_stop": "ef4efbd8-cdf3-4968-b2ef-9780904c11d1",
  • "origin_stop_alerts": [
    ],
  • "overall_status": "ASSIGNED",
  • "planned_delivery_end_datetime": "2019-08-24T14:15:22Z",
  • "planned_delivery_start_datetime": "2019-08-24T14:15:22Z",
  • "planned_pickup_end_datetime": "2019-08-24T14:15:22Z",
  • "planned_pickup_start_datetime": "2019-08-24T14:15:22Z",
  • "purchase_order_number": "string",
  • "shipment": "040451d7-03ba-4b1e-94f7-5cacc36efb36",
  • "source": "SHIPWELL_WEB",
  • "source_system_id": "string",
  • "status": "string",
  • "subtotal_amount": 0,
  • "subtotal_amount_currency": "CAD",
  • "supplier_external_id": "string",
  • "supplier_name": "string",
  • "tax_amount": 0,
  • "tax_amount_currency": "CAD",
  • "transit_status": "PICKED_UP",
  • "transit_status_reason_code": "ACCIDENT",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "actual_delivery_datetime": "2019-08-24T14:15:22Z",
  • "actual_pickup_datetime": "2019-08-24T14:15:22Z",
  • "archived": true,
  • "company": "87340f10-f684-4b06-8427-5981380bd9a9",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_user": {
    },
  • "custom_data": {
    },
  • "customer_external_id": "string",
  • "customer_name": "string",
  • "description": "string",
  • "destination_address": {
    },
  • "destination_address_book_entry": "ec679ff9-f6ca-40cd-9240-fc673371afec",
  • "destination_dock_external_id": "string",
  • "destination_stop": "9f2c2b22-33f4-4d9a-8d9e-5bae44ad8c1e",
  • "destination_stop_alerts": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invoice_external_id": "string",
  • "line_items": [
    ],
  • "name": "string",
  • "order_number": "string",
  • "origin_address": {
    },
  • "origin_address_book_entry": "a3c225dc-c7d7-4c94-b9ff-16919e5a505f",
  • "origin_dock_external_id": "string",
  • "origin_stop": "ef4efbd8-cdf3-4968-b2ef-9780904c11d1",
  • "origin_stop_alerts": [
    ],
  • "overall_status": "ASSIGNED",
  • "planned_delivery_end_datetime": "2019-08-24T14:15:22Z",
  • "planned_delivery_start_datetime": "2019-08-24T14:15:22Z",
  • "planned_pickup_end_datetime": "2019-08-24T14:15:22Z",
  • "planned_pickup_start_datetime": "2019-08-24T14:15:22Z",
  • "purchase_order_number": "string",
  • "shipment": "040451d7-03ba-4b1e-94f7-5cacc36efb36",
  • "source": "SHIPWELL_WEB",
  • "source_system_id": "string",
  • "status": "string",
  • "subtotal_amount": 0,
  • "subtotal_amount_currency": "CAD",
  • "supplier_external_id": "string",
  • "supplier_name": "string",
  • "tax_amount": 0,
  • "tax_amount_currency": "CAD",
  • "transit_status": "PICKED_UP",
  • "transit_status_reason_code": "ACCIDENT",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Copyright © Shipwell 2024. All right reserved.