Order status update
Sent when an order's status changes. One order per request.
Bigblue sends this event when an order's status code changes. See Order statuses. Changes inside Bigblue that don't change the code aren't sent.
Headers
X-Bigblue-Event-Type: ORDER_STATUS_UPDATE
X-Bigblue-Hmac-SHA256: <base64 HMAC-SHA256 of the raw body>
Content-Type: application/json
User-Agent: Bigblue-Webhook-EngineBody
update_timestringrequiredWhen Bigblue created this event, RFC 3339 UTC.
order_statusOrderStatusUpdaterequiredThe order and its new status.
OrderStatusUpdate
idstringBigblue order ID.
external_idstringYour order reference.
codestringThe new status code.
carrierstringCarrier service of the most advanced fulfillment. Empty until there is one.
tracking_numberstringTracking number of that fulfillment. Empty until a label exists.
tracking_urlstringTracking page for the customer.
If an order changes status several times in a short period, only the latest status is sent.
Example
{
"update_time": "2026-03-15T16:20:11Z",
"order_status": {
"id": "BGBL0K3M9XQ2",
"external_id": "web-10231",
"code": "SHIPPED",
"carrier": "colissimo-fr-home",
"tracking_number": "6A12345678901",
"tracking_url": "https://track.bigblue.co/BGBL0K3M9XQ2"
}
}Before the order ships, the tracking fields are empty:
{
"update_time": "2026-03-14T09:31:02Z",
"order_status": {
"id": "BGBL0K3M9XQ2",
"external_id": "web-10231",
"code": "PENDING",
"carrier": "",
"tracking_number": "",
"tracking_url": ""
}
}Handling the event
Statuses move forward, so ignore an event that would move an order backwards.
EXCEPTION is different: it can happen at any step and the order can continue
afterwards, so record it without blocking later statuses.
const RANK: Record<string, number> = {
PENDING: 1,
BACKORDER: 1,
IN_PREPARATION: 2,
HANDED_OVER: 3,
SHIPPED: 4,
DELIVERED: 5,
RETURNED: 6,
CANCELLED: 7,
FULFILLMENTS_CANCELLED: 7,
};
async function onOrderStatusUpdate(body: OrderStatusPayload) {
const { id, code, carrier, tracking_number, tracking_url } = body.order_status;
const stored = await db.orders.find(id);
// A retry of an older event.
if (stored && body.update_time < stored.statusUpdateTime) return;
if (code === 'EXCEPTION') {
await db.orders.update(id, { hasException: true, statusUpdateTime: body.update_time });
return;
}
// Don't move backwards. EXCEPTION isn't ranked, so it never blocks.
if (stored && (RANK[code] ?? 0) < (RANK[stored.status] ?? 0)) return;
await db.orders.update(id, {
status: code,
hasException: false,
carrier,
trackingNumber: tracking_number,
trackingUrl: tracking_url,
statusUpdateTime: body.update_time,
});
}Before your first event
Events are only created after you register an ORDER_STATUS_UPDATE webhook. Past
changes aren't sent. Load recent orders with
ListOrders after registering.