Order event callbacks can now be triggered by posting to the Data Factory. You can trigger the MasonHub API to create a shipment against and mark an order fulfilled by posting an Order ID to /data_factory/shipOrder. Please note that in order for MasonHub’s API to successfully post a callback of this type to your client API, you must have a callback url registered for the orderEvent message_type, and the order_customer_id used must correspond with a valid order that was previously uploaded to the API.
Let’s take a look at an example:
First, register your callback with a POST to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/callbacks with message_type = orderEvent and your target url
{
"url": "https://api.clienturl.com/api/orderEvent",
"message_type": "orderEvent"
}
Now that your callback url is registered, you can tell the MasonHub API to mock the shipment of one of your orders.
Trigger the shipment instruction with a POST to https://sandbox.masonhub.co/{your-client-slug-here}/api/v1/data_factory/shipOrder with the ID of the order you want to ship:
[
{
"order_customer_id": "12345"
}
]
That’s it! The targeted order will now be in ‘fulfilled’ status in the MasonHub API, and the API will have sent a callback message to your registered endpoint:
{
"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": "12345",
"status": "packed",
"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": "PNTS-NVY-LG",
"quantity": 1
},
{
"sku_customer_id": "PNTS-NVY-SM",
"quantity": 2
}
]
}
],
"shorts": null
}
]
}
The full spec for the callback type can be found here: https://docs.masonhub.co/api/v1#tag/Callback-Events/paths/~1orderEvent/post
One of the core functions necessary for our clients is the ability to group skus together into a kit. Essentially, that means there is a parent sku made up of one or more child skus with a quantity attached. For example, a kit could be a shirt and pair of pants sold together at a special price. Our OMS now handles that gracefully. Simply create a parent sku in the item master by marking the is_kit flag as true and providing the list of skus and quantities necessary to satisfy the kit. The MasonHub OMS will immediately calculate how many skus are available in each inventory location and make that inventory available for sale on your site.
There are essentially two different types of kits: Pre-built and Kit-to-Ship. A Pre-built kit is, as you would guess, already assembled at our warehouse and ready for shipment to your customer. The time to process will be less and it is overall more efficient, especially at scale. Kit-to-ship, on the other hand, is assembled as orders arrive at the distribution center. In a pre-built kit, the child units that make up the kit are no longer available for sale individually because they are already boxed and waiting. In a kit-to-ship kit, the child units are available for individual sale on your site as is the kit.
The OMS inventory ledger keeps everything in sync automatically and can handle any combination of pre-built and kit-to-ship inventory levels. The skuInventoryChange events are the same. The total_available_to_sell for a kit sku is made up of how many kits we have pre-built and how many kits are available based on child sku inventory levels. Your system doesn’t need to know the difference. Our OMS will automatically allocate kits to orders that are pre-built first and then fall through to kit-to-ship. You do not need to submit child skus in your order…just the parent kit sku. As child inventory levels change, the parent inventory changes will automatically change and you will continue to get updates for both child and parent inventory levels.
Creating a kit in the item master is easy. It’s the same end point as you normally use for sku creation. Jus add the is_kit and kit_skus attributes to your post and put messages:
[
{
"customer_identifier": "kit00001",
"brand_name": "Freddie's",
"customer_bar_code": "kit234523",
"customer_brand_code": "pp",
"customer_color": "w",
"brand_code": "3",
"dim_height": 12,
"dim_weight": 10,
"dim_length": 2,
"dim_volume": 3,
"image_url": "http://bohemianrhapsody.com/img432523.jpg",
"price": 15.95,
"unit_cost": 5.95,
"product_category": "kit",
"product_sub_category": "ready-for-life-at-sea",
"size": "M",
"vendor_bar_code": "kit675443",
"vendor_brand_code": "pete's",
"vendor_color": "Mixed",
"product_name": "Shirt and Pants Combo",
"product_description": "Look fabulous in this blousy pirate shirt and pair of sea-faring pantaloons.",
"is_kit": true,
"kit_skus": [
{
"customer_identifier": "3342336",
"quantity": 2
},
{
"customer_identifier": "33423367",
"quantity": 1
}
]
}
]
If you send us the wrong child skus or quantities, issue a put with your changes and our system will automatically recalculate how many kits are available based on existing inventory levels and send an update to your system. This change is backwards compatible with previous incarnations of our sku endpoint, so no changes are needed to your systems, but you now have a new tool in your toolbox.
We’ve been lying to you this whole time…well not really. We just kept giving you fake inventory counts in the sku detail and sku summary GET requests. That has all changed, and the inventory totals you receive in the response are now based on true totals.
As always, don’t be afraid to reach out to Chris or Andy with any questions.