There’s a new callback event you can now register for, called orderUpdateResolution.
Full API spec details can be found here: https://docs.masonhub.co/api/v1#tag/Callback-Events/paths/~1orderUpdateResolution/post
This callback will act as the asynchronous response from the MasonHub API to your client to advise on whether order update requests succeed or fail. If you remember from the Order Updates release, any desired updates to order information is made in the form of a request, because after an order is submitted and has reached the distribution center, it is possible that it is in a state that it can no longer be updated (think… it’s already in a box with a shipping label on it).
The orderUpdateResolution callback provides an end state to that request, and advises to your client API whether or not that request succeeded or not. Because of the asynchronous nature of this request/response dialog, it’s important that your client system keep track of which updates you’ve submitted to MasonHub, so that you have a record of any changes that are outstanding and may or may not take hold before the order gets shipped.
Let’s look at an example.
First, you’ll need to register for this callback like all other callbacks, specifying the url and (optionally) bearer token to which the callback events will be posted.
POST to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/callbacks with message_type = orderUpdateResolution
{
"url": "https://api.clienturl.com/api/orderUpdateResolution",
"message_type": "orderUpdateResolution",
"token": "long_token_string_goes_here"
}
Now MasonHub will know where to send the update resolutions. Say you now post an order update request with a POST to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/order_update_requests (the body is a full order details). MasonHub will respond with an update identifier:
{
"records_submitted": 1,
"records_processed": 1,
"records_failed": 0,
"records_succeeded": 1,
"results": [
{
"system_id": "0b744e29-b668-4486-85dd-82528b5da0dd",
"customer_identifier": "12345",
"status": "success",
"uri": "https://sandbox.masonhub.co/test/api/v1/order_update_requests?cid=12345"
}
]
}
Note here that the presence of “status”: “success” refers to the fact that the MasonHub API successfully received the update request, not that it already took affect. The other thing you may want to keep track of is the system_id of the update request. That UUID will eventually be sent back on the order update request resolution callback, so you can reference exactly which update the callback is in reference to.
Eventually, MasonHub will send the orderUpdateResolution callback. It will be posted to the url you registered in the callback, and the body will look something like this:
{
"callback_url": "https://client.com/api/orderUpdateResolution",
"message_type": "orderUpdateResolution",
"message_id": "0896116f-e54b-4756-9d3e-1b0c4a25d821",
"data": [
{
"id": "0b744e29-b668-4486-85dd-82528b5da0dd",
"customer_order_id": "12345",
"status": "success",
"created_at": "2018-08-05T17:32:28Z",
"updated_at": "2018-08-05T17:32:28Z",
"deleted_at": null
}
]
}
You can see the id specified in the callback corresponds with the system_id that was returned on the initial update request. Once you receive this callback, you can process it on your side and consider whatever changes you made to the order in the update request fully propagated onto the order.
It is possible the update request will fail, and it will be noted as such on the callback:
{
"callback_url": "https://client.com/api/orderUpdateResolution",
"message_type": "orderUpdateResolution",
"message_id": "0896116f-e54b-4756-9d3e-1b0c4a25d821",
"data": [
{
"id": "0b744e29-b668-4486-85dd-82528b5da0dd",
"customer_order_id": "12345",
"status": "failure",
"reason": "Order already packed"
"created_at": "2018-08-05T17:32:28Z",
"updated_at": "2018-08-05T17:32:28Z",
"deleted_at": null
}
]
}
What good are those orderUpdateResolutions if you don’t have a way to test them? Well now you can, by posting to /data_factory/resolveOrderUpdate. Full API documentation here: https://docs.masonhub.co/api/v1#tag/DataFactory/paths/~1data_factory~1resolveOrderUpdate/post
A new endpoint has been added to the Data Factory so that you can trigger update resolutions at will. If we expand on the example above, suppose you just made an update request to an order, and the MasonHub API responded with the following:
{
"records_submitted": 1,
"records_processed": 1,
"records_failed": 0,
"records_succeeded": 1,
"results": [
{
"system_id": "0b744e29-b668-4486-85dd-82528b5da0dd",
"customer_identifier": "12345",
"status": "success",
"uri": "https://sandbox.masonhub.co/test/api/v1/order_update_requests?cid=12345"
}
]
}
If you perform a GET on this particular update request, you’ll see it’ll be in ‘pending’ status:
GET to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/order_update_requests?cid=12345
{
"limit": 1,
"offset": 0,
"list_type": "detail",
"data": [
{
"id": "0b744e29-b668-4486-85dd-82528b5da0dd ",
"customer_order_id": "129374",
"status": "pending",
"order_update_body": "[
...additional update information
]
}
]
}
Using the new Data Factory resolveOrderUpdate endpoint, you can tell the sandbox environment to resolve that update to either a success or failure status:
POST to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/data_factory/resolveOrderUpdate with body:
[
{
"order_update_request_id": "0b744e29-b668-4486-85dd-82528b5da0dd",
"resolution": "success"
}
]
As is probably expected, if you specify a resolution of “success”, the information in the order update request will now persist on the order, and will be reflected when you do a GET for that specific order information. This will also kick off the orderUpdateResolution callback message to your API. Alternatively, you can set a resolution of “failure”, and the changes to the order will not take hold, and you will receive an orderUpdateResolution callback message notifying your system of the unsuccessful update.
As always, don’t be afraid to reach out to Chris or Andy with any questions.