API docs
Sous Chef Ordering API
Request access

Order intake

Order intake is how your channel sends Sous Chef the orders it takes for the stores on your channel. It has four operations, all under /ordering/orders:

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

What happens to an order afterwards reaches you 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. The three cases return the same response. 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. Each item needs itemId, name, quantity and unitPrice, and each modifier needs itemId, name and quantity. A scheduled order also needs a future estimatedPickupAt, and a restaurantDelivery order needs a deliveryAddress. Everything else is optional. A required field that is missing or empty, or a value that is not one of those listed for its field, answers 400.

fulfillmentMeaning
pickupThe guest collects the order.
platformDeliveryA courier that your channel dispatches collects the order.
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 in UTC. Send placedAt as the moment the guest placed the order: an order for now is checked against the store's opening hours at that time.

Item and modifier ids are the ones fetchMenu returns: MenuItem.id for an item and MenuModifierOption.itemId for a modifier option. When an option has no itemId, use the option's id. Send only ids from the store's current menu.

What 200 means

200 means the order was queued, not that it has reached the kitchen. The response status is queued.

  • If the store is paused or outside its opening hours, the order is rejected automatically and you receive order.rejected.
  • An order that is not rejected goes straight to the kitchen. The next events are order.status.updated when the order becomes ready and then finished, order.cancelled if the restaurant or you cancel it, and order.delivery.updated.
  • fetchOrder returns the order's current status at any time. A queued order appears there within moments, so use it to confirm an order. One that has not appeared after five minutes was not created: contact support with the call's transaction id.

Idempotency

platformOrderId identifies the order. Sending the same storeCode and platformOrderId again answers 200 and does not create a second order, so a retry after a timeout is safe. Use a platformOrderId that is unique across every order you send, not only within one store. An id that was already used for another order is not created a second time.

The platformOrderId is returned on every order.* webhook and on fetchOrder, beside the Sous Chef id, so that you can match events to your own orders.

cancelOrder

Send storeCode, platformOrderId, and optionally a reason (itemOutOfStock, storeClosed, kitchenBusy or other, the default) and free-text details. A cancelled order is followed by an order.cancelled webhook. Cancelling an order that is already cancelled, finished or rejected changes nothing, sends no webhook and still answers 200. A cancellation that arrives just before its order has been created is held and applied once the order exists, for up to five minutes.

updateOrderDeliveryStatus

Send storeCode, platformOrderId and deliveryStatus. The values are ASSIGNED, EN_ROUTE_TO_STORE_LOCATION, EN_ROUTE_TO_CUSTOMER, COMPLETED and CANCELED, the same values that order.delivery.updated reports. Send the courier once you have one. Reporting COMPLETED also finishes the order: you receive order.delivery.updated for it, with no separate order.status.updated.

fetchOrder

Send storeCode and platformOrderId. A 404 means that the store is not on your channel or that the order does not exist there. An order that was just queued can take a moment to appear.

Errors

The standard error body applies. The codes specific to order intake:

CodeWhenAction
400A required field is missing or empty, or a value is not accepted (see createOrder).Correct the request.
404storeCode is unknown, retired or not on your channel.Correct the code.
422The store does not take orders through this API.Use another store.
429The key is over its rate limit.Wait, then retry.
5xxThe call could not be queued.Retry with backoff.

Validate a request against the reference before you send it: it lists every required field and accepted value. Every write is idempotent, so a retry after a 5xx or a timeout never duplicates an order.