Merchant Notifications Guide

Authentication


As a Merchant user that calls into our APIs, you must authenticate by including an OAuth 2.0 access token in the request header. You can obtain this token by following the instructions in this Authentication guide.

Submitting Orders

There are two ways you can submit orders to our system, depending on what order format you want to use:

  1. You can submit individual orders using our recommended order format by sending a POST API request directly to a Create a new Order endpoint and even submit multiple orders in a single POST API request to our Create multiple orders endpoint. 

  2. If you wish to keep using your order format, you can also submit orders by sending a POST API request to the inbound/orders endpoint at which point you should receive a response that the request was successfully received. That does not indicate that the order was successfully created as your request will be queued and processed asynchronously. For this to work, you’ll need to follow the steps below:

    • Create a Transformation that would transform your order payload into the format our system can ingest //need more info

    • Reference the Transformation in the body of the request for each order you submit

Example Request URL:

https://api.ordermesh.io/v1/inbound/orders

Example Payload:

{

  "body": "request body to be transformed and published",

  "merchantId": "2575fc98-b0e5-4124-92ae-7a5f27bd7210",

  "transformationId": "c03ecd9c-7a64-4282-b2bd-32bd18e0b417",

}

To be notified if your order was successfully created or failed to be created in our system, as well as keep track of all the order updates that happen after the order submission, you’ll need to subscribe to Webhooks that contain event information related to a specific order. You can configure your Webhooks by following the instructions in this Webhook Configuration guide.

Order Creation

First, you’ll need to set up a webhook for order creation events. Order Creation webhook is triggered whenever an order is successfully created or whenever an order has failed to be created in our system. 

Next to the basic information that describes the event, the webhook payload will also contain:

  • OrderId - This is your new Order ID.

  • ExternalOrderId - Your internal Order ID.

  • SafeId - The Safe ID for the order.

You’ll be able to distinguish a successfully created from a failed order notification by responseCode and responseDescription values:

  • Order has been successfully created - at which point you should receive:

    {

        "IsSuccessful": true,

        "OrderId": "670e58fe7741035996cf7d20",

        "ExternalOrderId": "WBTEST22",

        "SafeId": "WebhooksTest22",

        "Description": "Order information created successfully",

        "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",

        "RequestId": "0HN7A6B4H3FCT:0000000A",

        "EventType": "OrderCreation"

    }

  • Order failed to be created - at which point you should receive:

    {

        "IsSuccessful": false,

        "ResponseCode": 400,

        "ExternalOrderId": "WBTEST23",

        "SafeId": "WebhooksTest23",

        "Description": "Order could not be created",

        "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",

        "RequestId": "116e90b04bf38fbf53b83933abdae219",

        "EventType": "OrderCreation"

    }

Please note that the failed order Webhook is triggered only in case you're submitting orders via POST API request to the inbound/orders endpoint and transforming your order payload. In case you're submitting orders via POST API request directly to a Create a new Order endpoint, you'll receive a response directly from our Orders API notifying you that the order creation failed.

Order Update

You’ll also need to set up a Webhook for Order Update events. Order Update Webhook is triggered whenever an order information is updated/changed. Some of those updates include order status changes, order item status changes, shipping or billing address updates, image file updates, etc.  

Next to the basic information that describes the event, the webhook payload will also contain:

  • OldStatus - This is the order status before the update.

  • NewStatus - This is the order status after the update.

{

    "NewStatus": "ReadyForFulfillment",

    "OldStatus": "Open",

    "OrderId": "670e58fe7741035996cf7d20",

    "ExternalOrderId": "WBTEST22",

    "SafeId": "WebhooksTest22",

    "Description": "Order updated: status updated from Open to ReadyForFulfillment",

    "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",

    "RequestId": "0HN7A6B4H3FDT:00000009",

    "EventType": "OrderUpdate"

}

Once you receive an Order Update event Webhook you can use the OrderID or Order SafeID in that payload to then make a GET call to the Order API and retrieve the full order data if needed.

Shipment Created

Order Items within the order are grouped into Shipments that can get assigned to multiple vendors, depending on the product type and your Routing Strategy. Shipment Created Webhook is triggered when a shipment is created. 

Next to the basic information that describes the event, the Webhook payload will also contain:

  • shipmentId - This is a unique shipment identifier. 

    {

        "ShipmentId": "3ed09cf5-80c4-4450-8c64-245f2e2061bc",

        "ResponseCode": 200,

        "OrderId": "670e58fe7741035996cf7d20",

        "ExternalOrderId": "WBTEST22",

        "SafeId": "WebhooksTest22",

        "Description": "OK",

        "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",

        "RequestId": "0HN78H2O036DR:00000004",

        "EventType": "ShipmentCreated"

    }

Once you receive a Shipment Created event Webhook you can use the ShipmentID in that payload to then make a GET call to the Shipment API and retrieve the full shipment data.

Shipment Update

Shipment Update is triggered whenever a shipment is updated or moves into a new status. For example, once a shipment is produced and shipped it will be updated with tracking information. At that point you’ll receive a Webhook that contains the tracking information for that specific shipment. 

{

    "ShipmentId": "3ed09cf5-80c4-4450-8c64-245f2e2061bc",

    "Package": {

        "PackageId": "6e4d1eb2-493f-4664-a784-57d26412738a",

        "ShortId": "P09680270",

        "CarrierName": "USPS",

        "CarrierMethodName": "USPS Ground Advantage",

        "ShippedDate": "2022-04-10T15:20:00",

        "FulfilledDate": "2022-04-10T13:05:00",

        "CarrierTrackingNumber": "9400136208551280752547",

        "CarrierLink": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=9400136208551280752547",

        "CarrierAccount": false,

        "OrderItemIDs": [

            "670e58fe7741035996cf7d21"

        ],

        "PackingSlipId": null

    },

    "OrderId": "670e58fe7741035996cf7d20",

    "ExternalOrderId": "WBTEST22",

    "SafeId": "WebhooksTest22",

    "Description": "Package was successfully updated with tracking information",

    "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",

    "RequestId": "0HN78H2O038E4:0000001C",

    "EventType": "ShipmentUpdate"

}

Once you receive a Shipment Updated event Webhook you can use the information in that payload to pass it back into your system and update the order with the corresponding tracking information.