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

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.

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.

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 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.

Notifications Guide

Authentication#

Submitting Orders#

Order Creation#

Order Update#