Sous Chef API
Sous Chef Ordering API
Documentation

Order intake

Order intake is how your channel hands Sous Chef the orders it takes for the stores on your channel. Four operations, all under /ordering/orders:

OperationWhat it does
createOrderPlaces an order at one of your channel's stores.
cancelOrderCancels an order you placed.
updateOrderDeliveryStatusTells us where a delivery stands, and who the courier is.
fetchOrderReads one of your orders back by your own id.

What happens to an order afterwards comes back as signed order.* webhooks (see Webhooks). The stores and menus you order against are the ones fetchStores and fetchMenu return.

Addressing a store

Orders are addressed by store code: the code on each store from fetchStores. Send it as storeCode on every call. A code that is unknown, retired or not on your channel answers 404, and the three are indistinguishable by design. A store on your channel that does not take orders through this API answers 422.

createOrder

Required: storeCode, platformOrderId, fulfillment, at least one entry in items, subtotal and total. A scheduled order also needs a future estimatedPickupAt, and a restaurantDelivery order needs a deliveryAddress. Everything else is optional. Anything missing, empty or unknown is a 400.

fulfillmentMeaning
pickupThe guest collects the order.
platformDeliveryA courier your channel dispatches collects it.
restaurantDeliveryThe restaurant delivers it; deliveryAddress is required.

Money is an integer in the currency's minor unit (cents for USD) — 1250 is $12.50, never 12.5. Times are ISO-8601 UTC.

Item and modifier ids are the ones fetchMenu returns: MenuItem.id for an item and MenuModifierOption.itemId for a modifier option (use the option's id when the menu does not carry itemId yet).

What 200 means

200 means we queued the order, not that the restaurant accepted it. The restaurant's decision arrives as order.created (accepted and on the tablet; not sent yet, coming before sandbox access) or order.rejected. The response status is queued today.

Idempotency

storeCode together with platformOrderId identifies the order. Sending the same pair again answers 200 and creates nothing twice, so a retry after a timeout is always safe. The platformOrderId comes back on every order.* webhook and on fetchOrder, beside Sous Chef's own id, which is how you match our events to your orders.

cancelOrder

Send storeCode, platformOrderId, and optionally a reason (itemOutOfStock, storeClosed, kitchenBusy or other, the default) and free-text details. Cancelling an order that is already cancelled, finished or rejected does nothing and still answers 200. A cancellation that reaches us before its order is retried until the order exists; it is not lost.

updateOrderDeliveryStatus

Send storeCode, platformOrderId and deliveryStatus — one of ASSIGNED, EN_ROUTE_TO_STORE_LOCATION, EN_ROUTE_TO_CUSTOMER, COMPLETED, CANCELED, the same values order.delivery.updated reports — and, once you have one, the courier.

fetchOrder

Send storeCode and platformOrderId. A 404 means the store is not on your channel or the order does not exist there yet — a just-queued order may take a moment to appear.

Errors

The standard error body, plus:

CodeWhenAction
400A required field is missing, an enum value is unknown, items is empty, scheduled has no future estimatedPickupAt, or restaurantDelivery has no deliveryAddress.Fix the call.
404storeCode is unknown, retired, or not on your channel.Fix the code.
422The store does not take orders through this API.Use the right store.
429Over your key's rate limit.Honour Retry-After.
5xxWe could not queue the call.Retry with backoff.

Every write is idempotent, so retrying on 5xx or a timeout never duplicates an order.