Orders
Place an order
Send the order straight to the venue's kitchen. There is no approval step; the kitchen ticket prints at once.
/public/v1/venues/{venueId}/ordersWarning: There is no sandbox. An order placed with a real key is a real order at a real venue, and its kitchen prints a ticket. Develop against a venue you run, tell its staff, and price the basket for everything that does not need to be an order.
Send the order and the Idempotency-Key header. The answer is 201 Created with a Location header pointing at GET /orders/{orderId}. If the request times out or the connection drops, send it again with the same key: you get the order the first call made, as the venue has it now, with status 200 OK, and nothing is ordered twice. Make up a new key for a new order. More in Placing orders.
Keep the addedLineIds of the 201 answer. It says exactly which of order.lines this call wrote, which matters on a dine-in order that joined a table's bill with lines other people ordered on it. In a retry's 200 answer it is a best-effort reconstruction.
The server prices the order: the lines at menu price with their extras, the venue's automatic campaigns, and its service fee. Price the basket to show the total beforehand.
- Dine-in (
DineIn) needstableIdand no customer: the round is added to the table's open bill, or opens one. - Takeaway (
Takeaway) needscustomer.nameandcustomer.phone; delivery (Delivery) also needscustomer.address. Neither takes atableId. - 1 to 30 lines, 1 to 20 of each, at most 20 extras and 20 removed ingredients on a line, an order note of at most 300 characters and line notes of at most 200.
The venue must be taking orders right now: an active subscription (PUBLIC_API_ORDERING_UNAVAILABLE), no kitchen rush (PLACE_IS_BUSY) and inside its working hours (OUTSIDE_WORKING_HOURS). Every product must be one the menu lists and orderable; a product that is out of stock is refused too.
Parameters
venueIdstring · uuidPath parameterrequiredThe venue, one of the ids GET /venues lists.
Idempotency-KeystringHeaderrequiredA value you make up once per order, 8 to 64 letters, digits, - or _ (a UUID works), and send again, unchanged, on every retry of that order. Required.
8 to 64 characters
Accept-LanguagestringHeaderThe language of userMessage in an error: tr (the default), en, de, fr, it, es, ar or ru. The first language in the header decides, without its region (en-US reads as en) and without weighing q values; a language Cibusy does not offer is answered in Turkish. It does not choose the language of a menu: that is lang on the menu call.
Request body
An order a venue's site sends in, or a basket it wants priced first. It carries no prices: the server prices every line from the venue's menu, applies the venue's campaigns and service fee, and answers with the total.
typestringrequiredHow the order reaches the diner. Required.
DineIn- At a table: the round is added to the table's open bill, or opens one.
Takeaway- Takeaway: the customer collects it at the venue.
Delivery- Delivery: the venue brings it to the customer.
tableIdstring · uuidnullableThe table a dine-in order is for, one of the ids GET /venues/{venueId}/tables lists. Required for DineIn and not allowed for Takeaway or Delivery. An id that is not one of the venue's tables answers 404.
customerobjectnullableWho the order is for. Required for Takeaway (name and phone) and Delivery (name, phone and address) and not allowed for DineIn: a party at a table is served where it sits.
Fields of Customer
namestringrequirednullableThe customer's name, at most 100 characters. Required.
phonestringrequirednullableThe number to ring about the order, in international form or the way it is written locally (+905321112233, 0532 111 22 33). At most 30 characters. Required.
addressstringnullableWhere a delivery goes, in the customer's own words, at most 300 characters. Required for Delivery and not allowed for Takeaway.
paymentMethodstringnullableHow the customer says they will pay, for a takeaway or a delivery. Optional, and not allowed for DineIn, which is settled at the table. A hint for whoever hands the order over: nothing is charged through the API.
Cash- Cash.
Card- Card.
MealCard- Meal card.
notestringnullableA note for the kitchen about the whole order, at most 300 characters.
linesobject[]requiredThe products ordered: 1 to 30 lines.
Fields of Order line request
productIdstring · uuidrequiredThe product, one of the ids GET /venues/{venueId}/menu lists. Required.
portionIdstring · uuidrequiredThe portion of that product. Required. A portion the venue sells by weight (orderable: false in the menu) cannot be ordered.
quantityintegerrequiredHow many of it, 1 to 20.
notestringnullableA note for the kitchen about this line, at most 200 characters.
extraIdsstring[]The extras chosen for each unit of this line: ids from the product's extras in the menu, at most 20, each at most once. An extra that is not the product's own, or a choice that breaks the product's option groups (two sugar levels on one coffee, none where one is required), is refused.
removedIngredientIdsstring[]The ingredients left out of each unit of this line: ids from the product's removableIngredients in the menu, at most 20, each at most once.
Responses
An idempotent retry: the order the same Idempotency-Key already made. Its addedLineIds is a best-effort reconstruction, so keep the ones from the 201.
The order was placed. Location points at it; addedLineIds are exactly the lines this call put on it, so keep them.
LocationWhere the order can be read: /public/v1/orders/{orderId}.
PUBLIC_API_IDEMPOTENCY_KEY_INVALID, PUBLIC_API_ORDER_INVALID or PUBLIC_API_PRODUCT_OPTION_INVALID.
The X-Api-Key header is missing (PUBLIC_API_KEY_MISSING), or the key is invalid or has been revoked (PUBLIC_API_KEY_INVALID).
PUBLIC_API_SCOPE_MISSING: the key was not made with the "Can send orders" permission.
PUBLIC_API_VENUE_NOT_FOUND, PUBLIC_API_TABLE_NOT_FOUND or PUBLIC_API_PRODUCT_NOT_FOUND.
PUBLIC_API_ORDERING_UNAVAILABLE, PLACE_IS_BUSY, OUTSIDE_WORKING_HOURS, PUBLIC_API_PRODUCT_UNAVAILABLE or ORDER_CREATION_IN_PROGRESS.
The key's budget of about 30 orders, reservations and tests a minute is spent; wait Retry-After seconds.
Retry-AfterSeconds to wait. The next one-minute window opens within it.
The data of a successful answer
The answer to placing an order: the order as the venue has it, and which of its lines this call wrote (exactly in the first answer, approximately in a retry's; see addedLineIds). Sent with 201 the first time an Idempotency-Key is used and with 200 when the key is repeated.
orderobjectThe order. A dine-in round that joined a bill that was already open comes back as that whole bill, with the lines other people ordered on it.
Fields of Order
idstring · uuidThe order's id. Use it with GET /orders/{orderId}.
numberintegerThe number the venue calls the order by, counted from 1 within the venue. Show it to the customer; it is the one printed on the kitchen ticket. Unique within one venue only.
venueIdstring · uuidThe venue the order was placed at.
typestringHow the order reaches the diner.
DineIn- At a table: the round is added to the table's open bill, or opens one.
Takeaway- Takeaway: the customer collects it at the venue.
Delivery- Delivery: the venue brings it to the customer.
statusstringWhere the order has got to, worked out from the order's lines and its bill on every read.
Received- The venue has the order and the kitchen has not started.
Preparing- The kitchen has started on at least one line.
Ready- Every line is ready or already served.
Served- Every line on it is served.
OnTheWay- A delivery has left the venue.
Completed- The venue closed the bill.
Cancelled- The order was voided, or every line on it was struck off.
paymentStatusstringHow much of the bill has been paid at the venue.
Unpaid- Nothing has been paid at the venue.
PartiallyPaid- Part of the bill has been paid.
Paid- The bill is settled.
tableobjectnullableThe table, for a dine-in order. null for a takeaway or a delivery.
Fields of Order table
idstring · uuidThe table's id, as GET /venues/{venueId}/tables lists it.
namestringThe table's name.
customerobjectnullableWho the order is for, for a takeaway or a delivery. null for a dine-in order, and for an order nobody took the customer's details for.
Fields of Customer details
namestringnullableThe customer's name.
phonestringnullableThe customer's phone number, in international form.
addressstringnullableWhere a delivery goes.
paymentMethodstringnullableHow the customer said they would pay, if they said. null otherwise.
Cash- Cash.
Card- Card.
MealCard- Meal card.
notestringnullableThe note for the kitchen the order was placed with. null when there was none.
linesobject[]Every line on the order, including lines other people put on a table's bill and lines since cancelled. For a dine-in order that joined a bill that was already open, the lines of the whole bill are here: the addedLineIds of the placement answer say which of them that call wrote.
Fields of Order line
idstring · uuidThe line's id. Stays the same for as long as the line is on the order.
productIdstring · uuidThe product, as the menu lists it.
productNamestringThe product's name in the venue's own words.
portionIdstring · uuidnullableThe portion ordered, as the menu lists it.
portionNamestringnullableThe portion's name as it read when the order was placed.
quantityintegerHow many of it.
unitPricenumberThe price of one unit, extras included, as it was when the order was placed.
totalnumberWhat the line comes to: unitPrice × quantity, before campaigns. 0 for a cancelled line and for one the venue gave away.
statusstringWhere the line has got to in the kitchen.
Pending- Waiting in the kitchen.
Preparing- Being prepared.
Ready- Ready.
Served- Served.
Cancelled- Cancelled. The lines of a cancelled order read this way too.
extrasobject[]The extras on each unit.
Fields of Line extra
idstring · uuidThe extra, as the menu lists it.
namestringThe extra's name.
pricenumberWhat it cost per unit when the order was placed.
removedIngredientsobject[]The ingredients left out of each unit.
Fields of Removed ingredient
idstring · uuidThe ingredient, as the menu lists it.
namestringThe ingredient's name.
notestringnullableThe note for the kitchen about this line. null when there was none.
orderedAtstring · date-timeWhen the line was put on the order, in UTC.
totalsobjectWhat the order comes to, and how much of it is paid.
Fields of Totals
subtotalnumberThe lines at menu price with their extras, before campaigns. Cancelled lines are not counted.
discountnumberWhat the venue's campaigns and discounts take off.
serviceFeenumberThe venue's service fee, charged on the food after campaigns. 0 when the venue charges none.
totalnumberWhat the order comes to.
paidnumberHow much of it has been paid at the venue.
remainingnumberHow much is still owed. 0 once the bill is paid.
currencystringThe currency of every amount, an ISO 4217 code. Always TRY.
createdAtstring · date-timeWhen the order was placed, in UTC.
closedAtstring · date-timenullableWhen the venue closed the order, in UTC. null while it is open, and for a cancelled order.
addedLineIdsstring[]The ids of the lines this call put on the order, among order.lines. In the 201 answer they are exactly the lines this call wrote, so keep them. When the key is repeated (200), the order does not say which request wrote which line, so they are a best-effort reconstruction: the lines put on the order within 15 seconds before the first call was recorded. On a dine-in bill other people were adding to, that can include a line somebody else added in that window.