Vendor Notifications Guide
Authentication
As a Vendor 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.
Receiving Orders
As a Vendor user, you can retrieve shipments from our system by subscribing to Shipment Created event Webhooks and obtaining a Shipment ID.
First, you must configure the Webhook that contains the shipment information. You can do so by following the instructions in this Webhook Configuration guide.
Shipment Created
Order Items within the order are grouped into Shipments that can get assigned to multiple vendors, depending on the product type and Merchants’ Routing Strategy. Shipment Created Webhook is triggered when a shipment is assigned to a vendor.
Next to the basic information that describes the event, the Webhook payload will also contain:
shipmentId- This is a unique shipment identifier - Shipment ID.{"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 Shipment ID in that payload to then send a GET API request to the Get details of a specific shipment by Shipment ID endpoint and retrieve the full shipment data.
Example Request URL:
https://api.ordermesh.io/shipment/v1/3ed09cf5-80c4-4450-8c64-245f2e2061bc
Example Response:
{
"id": "3ed09cf5-80c4-4450-8c64-245f2e2061bc",
"merchantId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
"vendorId": "d51d956a-e5c9-4e72-9fd6-6cebe5694515",
"facilityId": "F01290042",
"facilityName": "Plugin Test - California",
"vendorName": "Ant Plugin Test",
"orderId": "670e58fe7741035996cf7d20",
"shortId": "S08690279",
"orderExternalId": "WBTEST22",
"safeId": "WebhooksTest22",
"customerShippingAddressId": 0,
"shippingCountryCodeISO": "AF",
"shipmentStatus": "Fulfilled",
"currencyCode": "USD",
"languageCodeISO": "AB",
"createdDate": "2024-10-15T11:58:57.896Z",
"orderCreatedDate": "0001-01-01T00:00:00Z",
"lastModifiedDate": "0001-01-01T00:00:00",
"merchantOrderTotal": 8.9,
"merchantPackageTotal": 8.9,
"merchantTaxTotal": 0,
"merchantShippingTotal": 0,
"packageTotal": 2.44,
"taxTotal": 0,
"shippingTotal": 0,
"total": 2.44,
"costTotal": 2.44,
"costTaxTotal": 0,
"costShippingTotal": 0,
"costShippingTaxTotal": 0,
"packages": [
{
"id": "6e4d1eb2-493f-4664-a784-57d26412738a",
"shortId": "P09680270",
"shipmentId": "3ed09cf5-80c4-4450-8c64-245f2e2061bc",
"carrierName": "USPS",
"carrierMethodName": "USPS Ground Advantage",
"shippedDate": "2022-04-10T15:20:00Z",
"fulfilledDate": "2022-04-10T13:05:00Z",
"carrierTrackingNumber": "9400136208551280752547",
"carrierLink": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=9400136208551280752547",
"carrierAccount": false,
"orderItemIDs": [
"670e58fe7741035996cf7d21"
]
}
],
"orderItemIDs": [
"670e58fe7741035996cf7d21"
],
"orderItems": [
{
"id": "670e58fe7741035996cf7d21",
"sku": "Apparel-Tshirt-Gildan-5000-S-Black-Mens",
"variantId": "83188",
"vendorProductId": "0bd4f392-fd6a-4319-a274-2d15f61a4ab6",
"quantity": 1,
"merchantPrice": {
"currency": "USD",
"amount": 8.9,
"tax": 0
},
"price": {
"currency": "USD",
"amount": 2.44,
"tax": 0
}
}
]
}
Once you have obtained the packageId from the response payload, you can reference it to send tracking information back to our system once the items are produced and shipped. You can do so by sending a PATCH API request to Update a specific shipment packageendpoint.
Example Request URL:
https://api.dev.ordermesh.io/shipment/v1/3ed09cf5-80c4-4450-8c64-245f2e2061bc/package/6e4d1eb2-493f-4664-a784-57d26412738a
Example Payload:
{
"carrierName": "USPS",
"carrierMethodName": "USPS Ground Advantage",
"shippedDate": "2024-06-16T15:20:00",
"fulfilledDate": "2024-06-16T13:05:00",
"carrierTrackingNumber": "9400136208551280752547",
"carrierLink": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=9400136208551280752547",
"carrierAccount": false
}
If the request was successful, you should just receive a 204 status code in response.
Shipment Update
Shipment Update event Webhook is triggered whenever a shipment is updated or moves into a new status. For example, if an order item is updated or canceled, you should receive a Shipment Update event Webhook.
{
"ShipmentId": "452aa7ba-f46d-453a-9ad1-78ddb7d5ab0e",
"NewStatus": "ReadyForFulfillment",
"OldStatus": "Open",
"OrderId": "661407b68c031c880a9e2477",
"ExternalOrderId": "ORDER123456",
"SafeId": "OrderSafeID74658",
"Description": "OK",
"SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
"ResponseCode": 200,
"RequestId": "37ee5a6b-54fc-4f23-8ba3-5dd09afda370",
"EventType": "ShipmentUpdated"
}
Once you receive the Shipment Updated Webhook, you can use the Shipment ID in that payload to then send a GET API request to the Get details of a specific shipment by Shipment ID endpoint and retrieve the updated shipment data.