API docs
Sous Chef Management API
Request access

List orders

POST/management/orders/fetchOrders

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

application/json
required
  • orderIdsstring[]

    Fetch specific orders. Every other filter is ignored when this is present: the window, the statuses, the kitchen and the storefront. sort and page still 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 code on the Location that fetchStores and fetchStore report. 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.id as fetchStores reports it. Omit for every storefront.

    Mutually exclusive with locationCode: sending both is a 400. 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. recentlyCancelled is a stored-status filter value that renders as cancelled in 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 createdAt break on the order's id. 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 a createdAtStartDate window needs only the cursor. Repeating the same filters is accepted, and a filter with a different value is a 400. Only page.limit may 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.

Responses

200: One page of orders, and the cursor for the next page.

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 sort asked for (newest first by default).

    Iteration is not snapshot-stable: an order created while you are paging lands wherever its createdAt puts 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 order id. 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.

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.