Sous Chef API
Sous Chef Management API
Documentation

Create an order

POST/management/order-intake/createOrder

Place an order at one of your stores.

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

Re-sending the same storeCode and platformOrderId answers 200 and creates nothing twice.

Statuses beyond the common ones: 403 the key has no order-intake grant; 404 the storeCode is unknown, retired or not yours; 422 the store's channel does not take orders through this API.

Safe to retry: this operation changes state but is idempotent.

Request

application/json
required
  • storeCodestring

    Required. The store's code from fetchStores.

  • platformOrderIdstring

    Required. Your own id for the order. Together with storeCode it is the idempotency key: sending the same pair again answers 200 and creates nothing twice. It comes back as platformOrderId on every order.* webhook and on fetchOrders.

  • displayIdstring

    A short reference the guest and courier see.

  • placedAtstring<date-time>

    When the guest placed the order. Absent means the time we received it.

  • fulfillmentstring

    Required. How the guest receives the order.

    Possible values: [pickup, platformDelivery, restaurantDelivery]
  • schedulingstring

    asap (the default) or scheduled.

    Possible values: [asap, scheduled]
  • estimatedPickupAtstring<date-time>

    When the order should be ready for pickup. Required when scheduling is scheduled, and must then be in the future.

  • customerOrderCustomer

    The guest. Personal data.

  • deliveryAddressOrderDeliveryAddress

    Where to deliver. Required when fulfillment is restaurantDelivery. Personal data.

  • notestring

    The guest's note for the kitchen. Personal data.

  • deliveryNotestring

    A note for the courier or the delivering restaurant. Personal data.

  • utensilsboolean

    Whether the guest wants utensils.

  • itemsOrderIntakeItem[]

    Required. At least one line.

  • promotionsOrderIntakePromotion[]

    Promotions applied to the order.

  • subtotalnumber

    Required. Items before discounts, tax, tip and fees, in the currency's minor unit.

  • taxnumber

    Tax, in the currency's minor unit.

  • tipnumber

    Tip, in the currency's minor unit.

  • deliveryFeenumber

    Delivery fee, in the currency's minor unit.

  • serviceFeenumber

    Service fee, in the currency's minor unit.

  • totalnumber

    Required. What the restaurant is owed, as you state it, in the currency's minor unit.

  • totalDiscountnumber

    Total discount, in the currency's minor unit.

  • restaurantFundedDiscountnumber

    The part of the discount the restaurant funds, in the currency's minor unit.

  • platformFundedDiscountnumber

    The part of the discount the platform funds, in the currency's minor unit.

  • isTaxRemittedByPlatformboolean

    Whether the platform remits the tax itself.

  • taxCollectednumber

    Tax the platform collected, in the currency's minor unit.

  • taxableBasenumber

    The amount tax applies to, in the currency's minor unit.

  • grandTotalnumber

    What the guest paid, in the currency's minor unit.

Responses

200 — The order as received. The restaurant's decision follows as a webhook.

Headers

  • x-mealco-tx-idstringoptional

    The correlation id for this call, echoed on every response — a 200 exactly as much as a 400, 401 or 500. Quote it when reporting a problem and we can find every log line for the request, in every service it touched. You may also send your own x-mealco-tx-id on the request and we adopt it, so your correlation id becomes ours. Not marked required for one reason: a request whose JSON body is malformed is rejected before it reaches an operation, so no id exists yet and that single response carries neither this header nor the txId field of the error body. Everything that reaches an operation carries it.

  • platformOrderIdstring

    Your platformOrderId, echoed.

  • storeCodestring

    Your storeCode, echoed.

  • receivedAtstring<date-time>

    When we received the order.

  • statusstring

    What happened to the order: queued or created. Absent only on a reply that predates this field. 200 never means the restaurant accepted — that arrives as order.created or order.rejected.

    Possible values: [created, queued]

About Order intake

Send Sous Chef the orders your platform takes for the stores you sell for.

Separate from Orders, which is the read side: this section places, cancels and moves orders along; Orders and the order.* webhooks tell you what became of them. Same api key and x-mealco-org-id header, but the key must also carry the order-intake grant — a key without it is refused with 403 even if it can manage your estate. A different job, and a different route prefix (/management/order-intake) so the url says which.

Stores are addressed by their code from fetchStores. A code that is unknown, retired or another organization's answers 404, indistinguishably. A store whose channel does not take orders through this API answers 422.

200 means we queued the call, not that the restaurant accepted the order. Every operation here is idempotent, so retry on 500 / 503 freely.