Order updates are now live in Sandbox! See the full API spec here: https://docs.masonhub.co/api/v1#tag/Orders/paths/~1order_update_requests/post
Making updates to orders isn’t as simple as making a synchronous PUT request to the /orders endpoint. Because orders go through a picking and packing lifecycle, there is a certain point at which orders can no longer be updated. For that reason, any updates to orders are in actuality requests to update the order, to which the MasonHub API will eventually advise whether the update was successful or unsuccessful.
For this reason, all updates are submitted in the form of a POST to the /order_update_requests endpoint. The body of the request is the fully qualified order object (meaning all order attributes need to be included), just as if you were posting a new order to the /orders endpoint for creation. The MasonHub API will do a full replacement of the order information, so it is imperative any update requests contain a fully qualified order as the body.
Immediately after an order update request is submitted, the request is automatically in ‘pending’ status. This status will update after the request propagates to the distribution center, and it is determined whether the order can in fact be updated or not. The most common reason an order update would fail would be because the order is already picked and packed, and changes to delivery or line items would be impossible.
Let’s walk through an example:
POST to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/order_update_requests (the body is a full order details)
[
{
"customer_identifier": "129374",
"order_type": "customer",
"priority": 100,
"shipping_provider": "rate_shop",
"shipper_service_level": "ground",
"value_added_services": [
"Complimentary Hankerchief"
],
"special_instructions": "Triple Fold the Sleeves and wrap in Tissue Paper.",
"gift_message": "Happy Birthday Freddie!",
"shipping_address_name": "John Jacob JingleHeimer-Schmidt III",
"shipping_address_street_line_one": "234 House Lane",
"shipping_address_city": "Little Falls",
"shipping_address_locale": "NJ",
"shipping_address_postal_code": "07972",
"shipping_address_phone_number": "973-999-3333",
"shipping_address_type": "residential",
"billing_address_name": "John Jacob JingleHeimer-Schmidt III",
"billing_address_street_line_one": "234 House Lane",
"billing_address_city": "Little Falls",
"billing_address_locale": "NJ",
"billing_address_postal_code": "07972",
"billing_address_phone_number": "973-999-3333",
"billing_address_type": "residential",
"submitted_at": "2018-08-01T00:00:00Z",
"line_items": [
{
"sku_customer_id": "shirts872340",
"quantity": 2,
"promised_delivery_date": "2018-08-15T17:32:28Z",
"estimated_delivery_date": "2018-08-15T17:32:28Z"
},
{
"sku_customer_id": "pants3422",
"quantity": 1,
"pick_from": [
{
"match_type": "purchase_order",
"match_value": [
"PO23423",
"PO42322"
],
"match_style": "hard"
}
],
"promised_delivery_date": "2018-08-15T17:32:28Z",
"estimated_delivery_date": "2018-08-15T17:32:28Z"
}
]
}
]
The API will do validation to make sure the order does in fact exist and is in a status eligible for updating.
You can now pull a list of OrderUpdateRequests by making a GET request to /order_update_requests.
Or, if you want see an update on the OrderUpdateRequest for a specific order, you can specify so with the cid attribute in the url parameters:
GET to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/order_update_requests?cid=129374
{
"limit": 1,
"offset": 0,
"list_type": "detail",
"data": [
{
"id": "f393aeb2-dcf5-48d9-bcbe-d9bb71f07c3a",
"customer_order_id": "129374",
"status": "pending",
"order_update_body": "[
{
"customer_identifier": "129374",
"order_type": "customer",
"priority": 100,
"shipping_provider": "rate_shop",
"shipper_service_level": "ground",
"value_added_services": [
"Complimentary Hankerchief"
],
"special_instructions": "Triple Fold the Sleeves and wrap in Tissue Paper.",
"gift_message": "Happy Birthday Freddie!",
"shipping_address_name": "John Jacob JingleHeimer-Schmidt III",
"shipping_address_street_line_one": "234 House Lane",
"shipping_address_city": "Little Falls",
"shipping_address_locale": "NJ",
"shipping_address_postal_code": "07972",
"shipping_address_phone_number": "973-999-3333",
"shipping_address_type": "residential",
"billing_address_name": "John Jacob JingleHeimer-Schmidt III",
"billing_address_street_line_one": "234 House Lane",
"billing_address_city": "Little Falls",
"billing_address_locale": "NJ",
"billing_address_postal_code": "07972",
"billing_address_phone_number": "973-999-3333",
"billing_address_type": "residential",
"submitted_at": "2018-08-01T00:00:00Z",
"line_items": [
{
"sku_customer_id": "shirts872340",
"quantity": 2,
"promised_delivery_date": "2018-08-15T17:32:28Z",
"estimated_delivery_date": "2018-08-15T17:32:28Z"
},
{
"sku_customer_id": "pants3422",
"quantity": 1,
"pick_from": [
{
"match_type": "purchase_order",
"match_value": [
"PO23423",
"PO42322"
],
"match_style": "hard"
}
],
"promised_delivery_date": "2018-08-15T17:32:28Z",
"estimated_delivery_date": "2018-08-15T17:32:28Z"
}
]
}
]",
"created_at": "2018-12-08T01:25:45.693997-05:00",
"updated_at": "2018-12-08T01:25:45.693998-05:00",
"deleted_at": null
}
]
}
As of now, order update requests will remain in ‘pending’ status, as there is no distribution center in place to make a final confirmation on success/failure of change requests.
Shortly, there will be a Data Factory endpoint in order to initiate Order Update Request successes and failures, in order to simulate the Distribution Center accepting or rejecting the update. There will also be a subsequent callback (OrderUpdateResponse) that will notify client APIs of the result of update requests.
As always, don’t be afraid to reach out to Chris or Andy with any questions.