Sous Chef API
Sous Chef Ordering API
Documentation

Create an order

POST/ordering/orders/createOrder

Place an order at one of your channel's 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: 404 the storeCode is unknown, retired or not on your channel; 422 the store 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 fetchOrder.

  • 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. Quote it when reporting a problem and we can find every log line for the request. You may also send your own x-mealco-tx-id on the request and we adopt it. Not marked required because a request whose JSON body is malformed is rejected before an id exists.

  • 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 (order.created is not sent yet, coming before sandbox access).

    Possible values: [created, queued]

About Orders

Send orders to the restaurants on your channel, move them along, and read them back.

Stores are addressed by their code from fetchStores. A code that is unknown, retired or not on your channel answers 404, indistinguishably. Orders are addressed by YOUR id, platformOrderId: together with storeCode it is the idempotency key. Sous Chef's own id for the order arrives as id on every order.* webhook and on fetchOrder.

200 on a write means we accepted the call for processing, not that the restaurant accepted the order: that arrives as an order.created or order.rejected webhook (order.created is not sent yet, coming before sandbox access). Every write is idempotent, so retry on 500 / 503 freely.