This is a short one, but a goody. We now provide functionality, via the DataFactory, to trigger shorts on orders and callbacks. Full API spec here: https://docs.masonhub.co/api/v1#tag/DataFactory/paths/~1data_factory~1shipOrder/post
There’s no new endpoint needed to trigger shorts. Instead, the functionality is wrapped into the already-existing /data_factory/shipOrder endpoint. Previously, the only attribute that endpoint accepted was order_customer_id, which is the order you want to target for fulfillment. We now accept a second attribute, shorts, for you to dictate which items you want to have shorted on the order, if any. Shorts takes a string array of sku IDs from the order that you want to short. Make sure you’re using skus that are actually on the order, or the API will advise the request is invalid. The number of skus you include in the array will result in that number of items shorted from the order. If you want to short multiple of the same sku, just include that sku multiple times in the array.
Let’s see an example:
If I already have an order posted to the API, I can see its status with a GET to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/orders?cid=129374
[
{
"id": "cb79fyn5-ec61-7892-ae7b-57a173b68133",
"customer_identifier": "129374",
"order_type": "customer",
"status": "open",
"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.",
"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-05T17:32:28Z",
"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,
"promised_delivery_date": "2018-08-15T17:32:28Z",
"estimated_delivery_date": "2018-08-15T17:32:28Z"
}
],
"created_at": "2018-08-05T17:32:28Z",
"updated_at": "2018-08-05T17:32:28Z",
"deleted_at": null
}
]
Note the order is in open status, and has two skus on it, shirts872340 & pants3422. Now if we want to trigger fulfillment on the order, we know we post to /data_factory/shipOrder. This time, we’ll specify that one of the items should be shorted, by including the sku in the shorts array:
POST to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/data_factory/shipOrder
[
{
"order_customer_id": "129374",
"shorts": [
"pants3422"
]
}
]
That will in turn trigger a callback message of type orderEvent, which will post to the orderEvent callback url you’ve previously registered in the API, telling you that the order was fulfilled, and providing shipment and short information. It’ll look like this:
POST to your url
{
"callback_url": "https://client.com/api/orderEvent",
"message_type": "orderEvent",
"message_id": "0896116f-e54b-4756-9d3e-1b0c4a25d821",
"data": [
{
"order_id": "8f1316d5-859f-4802-98b0-63d03a9517ac",
"customer_identifier": "129374",
"status": "fulfilled",
"shipments": [
{
"shipment_id": "88888",
"shipping_provider": "UPS",
"shipper_service_level": "ground",
"tracking_url": "http://ups.com/tracking/1z324897234nferg45",
"tracking_number": "1z324897234nferg45",
"shipment_date_time": "2018-08-06T15:11:19Z",
"shipment_line_items": [
{
"sku_customer_id": "shirts872340",
"quantity": 2
}
]
}
],
"shorts": [
{
"sku_customer_id": "pants3422",
"quantity": 1,
"reason": "damage"
}
]
}
]
}
And now you can perform any appropriate business logic for the shorts within your system. Take note that any items you don’t explicitly flag for shorting will end up shipped.
You can also now see the shorts on a GET to /orders?cid=129374
[
{
"id": "cb79fyn5-ec61-7892-ae7b-57a173b68133",
"customer_identifier": "129374",
"order_type": "customer",
"status": "fulfilled",
... additional order attributes ...
"shipments": [
{
"shipment_id": "88888",
"shipping_provider": "UPS",
"shipper_service_level": "ground",
"tracking_url": "http://ups.com/tracking/1z324897234nferg45",
"tracking_number": "1z324897234nferg45",
"shipment_date_time": "2018-08-06T15:11:19Z",
"shipment_line_items": [
{
"sku_customer_id": "shirts872340",
"quantity": 2
}
]
}
],
"shorts": [
{
"sku_customer_id": "pants3422",
"quantity": 1,
"reason": "damage"
}
]
"created_at": "2018-08-05T17:32:28Z",
"updated_at": "2018-08-05T17:32:28Z",
"deleted_at": null
}
]
Contrary to popular belief, we are only human, and sometimes make mistakes. We’ve recently patched a couple things that weren’t working as intended:
Our Order Archiving logic was a little buggy, and you may have noticed multiple ‘versions’ of orders returning after making updates to an order, and then retrieving the order with a GET.
{
"limit": 30,
"offset": 2121,
"list_type": "detail",
"include_counts": false,
"data": [
{
"id": "fe2b68e3-30bc-4c4c-8a5c-da0d122065ac",
"customer_identifier": "100384534",
"status": "open",
... more order info
},
{
"id": "249cbeaa-7c47-4c34-9707-6776fcebce4a",
"customer_identifier": "100384534",
"status": "canceled",
... more order info
}
]
}
This has been patched and is being revamped in order to provide a more robust versioning system, so we have a full audit of all changes made on orders.
We also discovered a bug that was preventing shipment information from populating on GET requests to the Orders endpoint. It resulted in an empty array for shipment_line_items, although the rest of the shipment information was correctly populated.
{
"limit": 30,
"offset": 0,
"list_type": "detail",
"include_counts": false,
"data": [
{
"id": "87e1aae3-c1c0-46b1-9379-60f7a4454002",
"customer_identifier": "88888",
"status": "fulfilled",
... more order attributes
"shipments": [
{
"shipment_id": "1trlz2t",
"customer_order_id": "88888",
"shipping_provider": "rate_shop",
"shipper_service_level": "ground",
"tracking_number": "shg79oi04yf60",
"tracking_url": "https://www.fedex.com/apps/fedextrack/index.html?action=track&tracknumbers=shg79oi04yf60&locale=en_US&cntry_code=en",
"shipment_date_time": "2018-12-18T18:07:29.747757Z",
"shipment_line_items": []
}
]
"created_at": "2018-12-18T14:06:39.674469Z",
"updated_at": "2018-12-18T14:07:29.779045Z",
"deleted_at": null
}
]
}
Interestingly, the orderEvent callback messages did include full shipment_line_item information, so it was only absent on the response from a GET. The bug has since been patched and fix deployed.
As always, don’t be afraid to reach out to Chris or Andy with any questions.