Create an order
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
- 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 onfetchOrder. - 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. 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:
queuedorcreated. Absent only on a reply that predates this field.200never means the restaurant accepted — that arrives asorder.createdororder.rejected(order.createdis 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.