You can now use it by making GET requests to /orders. The spec has been updated in our docs, along with examples: https://docs.masonhub.co/api/v1#tag/Orders/paths/~1orders/get
There’s not a whole lot that needs to be explained here. This is your classic GET request, which will return an array of order objects. As with our other GET endpoints, you have the option via url parameter of choosing whether to get a detailed (list_type=detail) or summarized (list_type=summary) response back. Right now GET requests to this endpoint should be mostly used to verify that the POSTS you’re making to create orders are in fact persisting correctly on the MasonHub backend.
Once there is more of a lifecycle taking place on the backend, you’ll see the order status attribute update accordingly when an order reaches our distribution center, and eventually gets picked, packed, and shipped. You’ll also notice that once there is a shipment against an order, you’ll get all the shipment information as a nested object of the order.
Example response to a GET request to https://sandbox.masonhub.co/test/api/v1/orders
[
{
"id": "cb65fyn5-534t-7892-hg67-57g173b54133",
"customer_identifier": "129374",
"order_type": "customer",
"status": "fulfilled",
"priority": 100,
"shipping_provider": "rate_shop",
"shipper_service_level": "ground",
"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"
}
],
"shipments": [
{
"shipment_id": "db79huy5-ec61-7892-ae7b-57a563b68133",
"customer_order_id": "cb65fyn5-534t-7892-hg67-57g173b54133",
"provider": "USPS",
"shipment_method": "priority",
"tracking_number": "3451csda23423",
"tracking_url": "http://usps.gov/tracking/3451csda23423",
"shipment_date_time": "2018-08-06T17:32:28Z",
"shipment_line_items": [
{
"sku_customer_id": "shirts872340",
"quantity": 2
},
{
"sku_customer_id": "pants3422",
"quantity": 1
}
]
}
],
"created_at": "2018-08-05T17:32:28Z",
"updated_at": "2018-08-05T17:32:28Z",
"deleted_at": null
}
]
If you navigate to https://docs.masonhub.co/api/v1#tag/Callback-Events, you’ll see there’s a new heading for ‘Callback Events’. This section defines what the payload will be when the MasonHub API makes a callback post to your client API. The url that Masonhub posts to is based on urls that you register by making POST reqeusts to the /api/v1/callbacks endpoint. Right now there are only callbacks for two types of messages: skuInventoryChange and orderEvent, but there are lots more on the way (think RMAs, Purchase Order Events, etc.)
To give an example, suppose you want to be able to listen in on every time an order gets updated from one status to another (like packed to fulfilled).
First, you need to register an endpoint on your server that will accept POST requests from MasonHub.
You make a POST to https://app.masonhub.co/{your_account_here}/api/v1/callbacks specifying which type of callback you want sent to your url:
[
{
"url": "api.clienturl.com/api/orderEvent",
"message_type": "orderEvent"
}
]
Now, whenever there is a change of status on one of your orders, MasonHub will send a POST to your endpoint, with the body being of the type defined under Order Events: https://docs.masonhub.co/api/v1#tag/Callback-Events/paths/~1orderEvent/post
{
"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",
"shipping_service_level": "ground",
"tracking_url": "http://ups.com/tracking/1z324897234nferg45",
"tracking_number": "1z324897234nferg45",
"shipment_date_time": "2018-08-06T15:11:19Z",
"shipment_line_items": [
{
"customer_identifier": "PNTS-NVY-LG",
"sku_id": "ea957a79-9605-4948-b9f4-6c115d881626",
"quantity": 1
},
{
"customer_identifier": "PNTS-NVY-SM",
"sku_id": "ea957a79-9605-4948-b9f4-6c115d881627",
"quantity": 2
}
]
}
],
"shorts": [
{
"customer_identifier": "PNTS-NVY-LG",
"sku_id": "ea957a79-9605-4948-b9f4-6c115d881626",
"quantity": 1,
"reason": "damage"
},
{
"customer_identifier": "PNTS-NVY-SM",
"sku_id": "ea957a79-9605-4948-b9f4-6c115d881627",
"quantity": 1,
"reason": "lost"
}
]
}
]
}
You can then handle and process that payload appropriately on your backend and play out any business logic that is appropriate. You can see how this can be much more efficient and real-time than having to poll the MasonHub API repeatedly to track order status changes and other real-time events.
You’ll very soon be able to trigger order event callback messages in your sandbox environment by making a request to the Data Factory. There will be additional information in release notes when that goes live.
As always, don’t be afraid to reach out to Chris or Andy with any questions.