Create an order
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
- storeCodestring
Required. The store's
codefromfetchStores. - platformOrderIdstring
Required. Your own id for the order. Together with
storeCodeit is the idempotency key: sending the same pair again answers200and creates nothing twice. It comes back asplatformOrderIdon everyorder.*webhook and onfetchOrders. - 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) orscheduled.Possible values: [asap, scheduled] - estimatedPickupAtstring<date-time>
When the order should be ready for pickup. Required when
schedulingisscheduled, and must then be in the future. - customerOrderCustomer
The guest. Personal data.
- deliveryAddressOrderDeliveryAddress
Where to deliver. Required when
fulfillmentisrestaurantDelivery. 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.
{
"storeCode": "<storeCode>",
"platformOrderId": "00000000-0000-0000-0000-000000000000",
"displayId": "00000000-0000-0000-0000-000000000000",
"placedAt": "2026-01-01T00:00:00Z",
"fulfillment": "pickup",
"scheduling": "asap",
"estimatedPickupAt": "2026-01-01T00:00:00Z",
"customer": {
"name": "<name>",
"phone": "<phone>",
"email": "<email>"
},
"deliveryAddress": {
"label": "<label>",
"street": "<street>",
"unit": "<unit>",
"city": "<city>",
"state": "<state>",
"zipCode": "<zipCode>",
"country": "<country>",
"lat": 50,
"lng": 50
},
"note": "<note>",
"deliveryNote": "<deliveryNote>",
"utensils": true,
"items": [
{
"itemId": "00000000-0000-0000-0000-000000000000",
"name": "<name>",
"quantity": 50,
"basePrice": 50,
"unitPrice": 50,
"totalPrice": 50,
"note": "<note>",
"modifiers": [
{
"itemId": "00000000-0000-0000-0000-000000000000",
"modifierGroupId": "00000000-0000-0000-0000-000000000000",
"modifierGroupName": "<modifierGroupName>",
"name": "<name>",
"quantity": 50,
"unitPrice": 50,
"totalPrice": 50,
"modifiers": [
{}
]
}
]
}
],
"promotions": [
{
"name": "<name>",
"discount": 50,
"platformPromotionId": "00000000-0000-0000-0000-000000000000",
"externalCampaignId": "00000000-0000-0000-0000-000000000000",
"promoCode": "<promoCode>"
}
],
"subtotal": 50,
"tax": 50,
"tip": 50,
"deliveryFee": 50,
"serviceFee": 50,
"total": 50,
"totalDiscount": 50,
"restaurantFundedDiscount": 50,
"platformFundedDiscount": 50,
"isTaxRemittedByPlatform": true,
"taxCollected": 50,
"taxableBase": 50,
"grandTotal": 50
}Responses
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:
queuedorcreated. Absent only on a reply that predates this field.200never means the restaurant accepted — that arrives asorder.createdororder.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.