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:
| Operation | What it does |
|---|---|
createOrder | Places an order at one of your channel's stores. |
cancelOrder | Cancels an order you placed. |
updateOrderDeliveryStatus | Reports where a delivery stands and who the courier is. |
fetchOrder | Returns 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.
fulfillment | Meaning |
|---|---|
pickup | The guest collects the order. |
platformDelivery | A courier that your channel dispatches collects the order. |
restaurantDelivery | The 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.updatedwhen the order becomesreadyand thenfinished,order.cancelledif the restaurant or you cancel it, andorder.delivery.updated. fetchOrderreturns 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:
| Code | When | Action |
|---|---|---|
400 | A required field is missing or empty, or a value is not accepted (see createOrder). | Correct the request. |
404 | storeCode is unknown, retired or not on your channel. | Correct the code. |
422 | The store does not take orders through this API. | Use another store. |
429 | The key is over its rate limit. | Wait, then retry. |
5xx | The 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.