API docs
Sous Chef Ordering API
Request access

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. Each item needs itemId, name, quantity and unitPrice; each modifier needs itemId, name and quantity. A scheduled order also needs a future estimatedPickupAt; a restaurantDelivery order needs deliveryAddress. A required field that is missing or empty, or a value that is not one of those listed for its field, is a 400.

Re-sending the same storeCode and platformOrderId answers 200 and creates nothing twice. A platformOrderId that was already used for another order is not created a second time.

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, and the idempotency key: sending the same storeCode and platformOrderId again answers 200 and creates nothing twice. It must be unique across every order you send, not only within one store. 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. What happens to it next follows as a webhook.

Headers

  • x-mealco-tx-idstringoptional

    The correlation id for this call, returned on a response from an operation. 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.

  • platformOrderIdstring

    Your platformOrderId, echoed.

  • storeCodestring

    Your storeCode, echoed.

  • receivedAtstring<date-time>

    When we received the order.

  • statusstring

    What happened to the order: queued. 200 does not mean that the order has reached the kitchen: an order for a store that is paused or outside its hours comes back as an order.rejected webhook.

    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: it is the idempotency key, and it must be unique across every order you send. 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 order has reached the kitchen. An order for a store that is paused or outside its hours comes back as an order.rejected webhook. Every other order goes to the kitchen: fetchOrder returns it, and its progress arrives as order.status.updated when it becomes ready and then finished. Every write is idempotent, so retry on 500 / 503 freely.