List orders
The order feed and single-order read in one operation: filter by time window, statuses, kitchen or storefront, or pass orderIds to fetch specific orders.
createdAtStartDate and createdAtEndDate bound the order's creation time: the moment Sous Chef recorded the order, which is the createdAt every order carries. createdAtStartDate is inclusive and createdAtEndDate is exclusive. There is no maximum window width and no rolling retention limit, so a full backfill is a loop over contiguous [createdAtStartDate, createdAtEndDate) windows of whatever size suits your loader. Both bounds are optional; omit both for all-time.
These bounds filter on createdAt and on nothing else. An order's pickup time is a different timestamp, minutes to days away from its creation, and there is no pickup-time window on this operation. Size your windows against creation time: an order created just before createdAtStartDate belongs to the previous window even when it is picked up inside this one. A backfill assembled from contiguous creation-time windows is complete, because every order is created exactly once.
The page is sorted by createdAt, newest first unless sort says otherwise, with ties broken on the order's id so the ordering is total. With sort: "createdAtAsc" and no cursor, the first row is your earliest order. Paging a closed window returns each order in it exactly once.
locationCode narrows to one kitchen and storeId to one storefront. They are mutually exclusive; sending both is a 400.
Cursor-paginated, to a depth of 10,000 orders (see page). Paging deeper is a 400; use a narrower window instead. The response is an object, so fields can be added without a breaking change.
Iteration is not snapshot-stable. The sort is total, so ties never reorder between pages. An order created mid-sweep lands wherever its createdAt puts it, which on the default newest-first sweep is a page you have already read, and the next page can then repeat a row. Close the window (an upper bound in the past cannot gain rows) and reconcile on order id for anything that must be exact.
Safe to retry: this operation is read-only and idempotent.
Request
- orderIdsstring[]
Fetch specific orders. Every other filter is ignored when this is present: the window, the statuses, the kitchen and the storefront.
sortandpagestill apply: they shape the answer rather than narrowing it.If you want the filters to narrow the result, send them without
orderIds. - locationCodestring
One kitchen per call, addressed by its short site code: the
codeon theLocationthatfetchStoresandfetchStorereport. Omit for every kitchen.This operation filters kitchens by code, not by
locationId. The code is returned on every store, so it is a value you already hold.Mutually exclusive with
storeId. See that field. - storeIdstring
One storefront per call, by
Store.idasfetchStoresreports it. Omit for every storefront.Mutually exclusive with
locationCode: sending both is a400. A store belongs to exactly one kitchen, so the two filters together are either redundant or contradictory. Send one of them. - statusesstring[]
Filter by stored status.
recentlyCancelledis a stored-status filter value that renders ascancelledin responses. Pass both to retrieve all cancelled orders.Possible values: [new, future, ready, finished, rejected, cancelled, recentlyCancelled] - createdAtStartDatestring<date-time>
Inclusive lower bound on the order's creation time (
Order.createdAt), ISO-8601 UTC. - createdAtEndDatestring<date-time>
Exclusive upper bound on the order's creation time (
Order.createdAt), ISO-8601 UTC.There is no maximum window width, and omitting both bounds is valid and means all-time.
- sortstring
How to order the page, on the order's creation time. Defaults to
createdAtDesc.createdAtDesc: newest first. Use it to read what has arrived since you last polled. It is also the order in which Sous Chef shows orders to a kitchen.createdAtAsc: oldest first. With no cursor, the first row is your earliest order.The order is total: ties on
createdAtbreak on the order'sid. While nothing is written, a given page of a sweep returns the same rows every time you request it.Possible values: [createdAtAsc, createdAtDesc] - pagePageRequest
Cursor pagination.
The cursor remembers your filters and
sort. Page two of acreatedAtStartDatewindow needs only the cursor. Repeating the same filters is accepted, and a filter with a different value is a400. Onlypage.limitmay change.The cursor has a depth limit on this feed: 10,000 orders. Past that you get a
400. To read deeper, for example in a backfill, use a narrower[createdAtStartDate, createdAtEndDate)window. There is no limit on how wide a window may be, so contiguous windows give you every order we hold.
{
"orderIds": [
"<orderIds>"
],
"locationCode": "<locationCode>",
"storeId": "00000000-0000-0000-0000-000000000000",
"statuses": [
"new"
],
"createdAtStartDate": "2026-01-01T00:00:00Z",
"createdAtEndDate": "2026-01-01T00:00:00Z",
"sort": "createdAtAsc",
"page": {
"limit": 50,
"cursor": "<cursor>"
}
}Responses
Headers
- x-mealco-tx-idstringoptional
The correlation id for this call, returned on every response that an operation produces, successful or not. Quote it when you report a problem so that we can trace the request. You may send your own x-mealco-tx-id on the request and it is used as the id. It is optional in the schema because a request with a malformed JSON body is rejected before an id is assigned, so that one response carries neither this header nor the txId field of the error body.
- ordersOrder[]
The page of orders, ordered by creation time in the direction
sortasked for (newest first by default).Iteration is not snapshot-stable: an order created while you are paging lands wherever its
createdAtputs it, which for the default newest-first sweep is a page you have already read. For an exact backfill, close the window and reconcile on orderid. Contiguous[createdAtStartDate, createdAtEndDate)ranges whose upper bound is in the past cannot gain rows while you page them. - nextCursorstring
Opaque cursor for the next page. Absent means the last page.
{
"orders": [
{
"id": "00000000-0000-0000-0000-000000000000",
"platformOrderId": "00000000-0000-0000-0000-000000000000",
"status": "new",
"deliveryStatus": "ASSIGNED",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z",
"estimatedReadyAt": "2026-01-01T00:00:00Z",
"rejectReason": "<rejectReason>",
"rejectReasonCode": "itemOutOfStock",
"store": {
"id": "00000000-0000-0000-0000-000000000000",
"externalId": "00000000-0000-0000-0000-000000000000",
"location": "<location>",
"brand": "<brand>",
"platform": "<platform>"
},
"cancellation": {
"by": "<by>",
"reason": "<reason>",
"reasonCode": "itemOutOfStock",
"at": "2026-01-01T00:00:00Z"
},
"details": {
"externalId": "00000000-0000-0000-0000-000000000000",
"externalReadableOrderNum": "<externalReadableOrderNum>",
"placedAt": "2026-01-01T00:00:00Z",
"estimatedPickupAt": "2026-01-01T00:00:00Z",
"isPickup": true,
"isMerchantDelivery": true,
"subtotal": 50,
"tax": 50,
"tip": 50,
"deliveryFee": 50,
"total": 50,
"items": [
{}
],
"promotions": [
{}
]
}
}
],
"nextCursor": "<nextCursor>"
}About Orders
Read the orders placed with your restaurants.
Start an integration here. Poll fetchOrders for the orders Sous Chef has accepted on your behalf across every delivery platform you are connected to. Orders are normalized into one shape, whether they arrived from DoorDash, Uber Eats, Grubhub or a direct channel.
Two conventions hold everywhere on this API. Money is always an integer in the currency's minor unit: 1250 is $12.50. Times are always ISO-8601 in UTC. The API does not convert them to a store's local time.
All endpoints are POST with a single JSON body, and the path carries no version segment. Changes to this API are additive (new fields and new endpoints, never removals or narrowing), so there is no versioned cutover.