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:

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.

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.

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. The Order Creation webhook is triggered whenever an order is successfully created or whenever an order fails to be created in our system.

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

OrderId – Unique identifier for the order generated by our system upon order creation.

ExternalOrderId – Your own internal order identifier submitted with the order.

SafeId – The globally unique and URL-safe identifier for the order, generated by the system upon order creation.

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,
  "Reprint": null,
  "OrderId": "670e58fe7741035996cf7d20",
  "ExternalOrderId": "WBTEST22",
  "SafeId": "WebhooksTest22",
  "Description": "Order created", 
  "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
  "ChildSubscriberId": null,
  "RequestId": "20260114T175400Z-15865bd54cdnnv7zhC1ATL7twc000000087g000000008mh4",
  "EventType": "OrderCreation"
}

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

{
  "IsSuccessful": false,
  "Reprint": null,
  "ResponseCode": 400,
  "ExternalOrderId": "WBTEST23",
  "SafeId": "WebhooksTest23",
  "Description": "Order could not be created",
  "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
  "ChildSubscriberId": null,
  "RequestId": "20260114T175400Z-15865bd54cdnnv7zhC1ATL7twc000000087g000000008mh4",
  "EventType": "OrderCreation"
}

Please note: The failed order Webhook is triggered only in case you're submitting orders via a POST API request to the inbound/orders endpoint and transforming your order payload. In case you're submitting orders via a 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 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 – The order status before the update was applied.

NewStatus – The order status after the update was applied.

{
  "NewStatus": "ReadyForFulfillment",
  "OldStatus": "Open",
  "Reprint": null,
  "OrderId": "670e58fe7741035996cf7d20",
  "ExternalOrderId": "WBTEST22",
  "SafeId": "WebhooksTest22",
  "Description": "Order updated: status updated from Open to ReadyForFulfillment",
  "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
  "ChildSubscriberId": null,
  "RequestId": "20260114T175400Z-176b66d6fcbrtv95hS1BNRzww00000000n4000000000b0ua",
  "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. The 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 – Unique identifier for the shipment generated by our system.

{
  "ShipmentId": "3ed09cf5-80c4-4450-8c64-245f2e2061bc",
  "ResponseCode": 200,
  "OrderId": "670e58fe7741035996cf7d20",
  "ExternalOrderId": "WBTEST22",
  "SafeId": "WebhooksTest22",
  "Description": "OK",
  "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
  "ChildSubscriberId": null,
  "RequestId": "20260114T175400Z-15865bd54cdnnv7zhC1ATL7twc000000087g000000008mh4",
  "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.

{
  "ShipmentId": "3ed09cf5-80c4-4450-8c64-245f2e2061bc",
  "NewStatus": "InProduction",
  "OldStatus": "ReadyForFulfillment",
  "Packages": [],
  "OrderMeta": {},
  "OrderId": "670e58fe7741035996cf7d20",
  "ExternalOrderId": "WBTEST_123",
  "SafeId": "WebhooksTest123",
  "Description": "",
  "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
  "ChildSubscriberId": null,
  "RequestId": "20260114T175400Z-15865bd54cdnnv7zhC1ATL7twc000000087g000000008mh4",
  "EventType": "ShipmentUpdate"
}

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",
  "NewStatus": "Fulfilled",
  "OldStatus": "InProduction",
  "Packages": {
    "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"
    ],
    "PackageOrderItems": [
      {
        "OrderItemId": "670e58fe7741035996cf7d21",
        "ExternalId": "16862939873452-16740582916268",
        "Quantity": 1,
        "ItemMeta": {
          "shopifyVariantId": "45094067830956",
          "shopifyFulfillmentOrderLineItemId": "16862939873452",
          "shopifyOrderLineItemId": "16740582916268"
        }
      }
    ],
    "PackingSlipId": null
  },
  "OrderMeta": {
    "integrator": "Shopify",
    "shopifyFulfillmentOrderId": "8048734273708",
    "shopifyOrderId": "7061367619756"
  },
  "OrderId": "670e58fe7741035996cf7d20",
  "ExternalOrderId": "WBTEST22",
  "SafeId": "WebhooksTest22",
  "Description": "Package was successfully updated with tracking information",
  "SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
  "ChildSubscriberId": null,
  "RequestId": "20260114T175400Z-15865bd54cdnnv7zhC1ATL7twc000000087g000000008mh4",
  "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.

Merchant Notifications Guide

Authentication#

Submitting Orders#

Order Creation#

Order Update#