Orders

List orders#

get/orders

Scope:

orders:read

Plan:

every plan

Without updated_since, the most recently changed orders come first. With updated_since, orders come in ascending updated_at order, which is the way to poll: remember the updated_at of the last order you processed and pass it as the next updated_since, minus a minute of overlap, deduplicating by id + updated_at. Without the overlap, a change committed at the same moment as your previous poll can be missed.

A system that takes over orders can instead ask for acknowledged=false (the orders your app has not acknowledged yet with POST /orders/{id}/acknowledge) and acknowledge each one after booking it.

Unpaid online orders are never listed: they do not exist until the payment is confirmed.

Parameters

Response200

OK

• objectstringrequired

  Always list.

  Values:"list"

• dataOrder[]required

  The items of this page.

  Child fields (20)

  • objectstringrequired

    Always order.

    Values:"order"

  • idstring (uuid)required

    The order.

  • codestringrequired

    Short code the guest sees and says at the counter, e.g. K7Q2M9.

  • external_idstringrequirednullable

    Your app's reference set with POST /orders/{id}/acknowledge; null when none. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

  • typestringrequired

    How the guest gets the order.

    Values:"pickup""delivery""dine_in"

  • sourcestringrequired

    Where it was placed: table via a table's QR code, app in the Flavoso app by a signed-in guest, storefront everything else (the restaurant's ordering page, the app without sign-in).

    Values:"storefront""table""app"

  • statusstringrequired

    Where the order is now. Restaurants may skip statuses, see GET /store.

    Values:"pending""confirmed""preparing""ready""completed""cancelled"

  • created_atstring (date-time)required

    When the order was placed. ISO 8601 in UTC (Z).

  • updated_atstring (date-time)required

    Last change. ISO 8601 in UTC (Z).

  • acknowledged_atstring (date-time)requirednullable

    When your app first acknowledged the order (POST /orders/{id}/acknowledge); null when not yet. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

  • requested_forstring (date-time)requirednullable

    Pickup or delivery time chosen by the guest (pre-order); null means as soon as possible.

  • currencystringrequired

    ISO 4217, e.g. EUR.

  • amountsobjectrequired

    The amounts of the order, in cents.

    Child fields (6)

    • subtotalintegerrequired

      Sum of the items. Integer amount in the smallest currency unit (cents).

    • delivery_feeintegerrequired

      Delivery fee. Integer amount in the smallest currency unit (cents).

    • service_feeintegerrequired

      Service fee. Integer amount in the smallest currency unit (cents).

    • discountintegerrequired

      Discount (stamp card), already subtracted. Integer amount in the smallest currency unit (cents).

    • tipintegerrequired

      Tip. Pass-through, not revenue. Integer amount in the smallest currency unit (cents).

    • totalintegerrequired

      subtotal + delivery_fee + service_fee − discount + tip. Integer amount in the smallest currency unit (cents).

  • taxobjectrequired

    VAT per rate of total − tip (items, fees, minus discount), computed like the restaurant's accounting export: discounts and delivery fees spread over the rates as the restaurant set it.

    Child fields (2)

    • includedbooleanrequired

      Always true: prices include VAT.

      Values:true

    • linesTaxLine[]required

      One line per rate, ascending, lines without rate last. The gross amounts add up to total − tip.

      Child fields (4)

      • rate_bpsintegerrequirednullable

        The rate in basis points (700 = 7 %). null: no rate was stored for this part (not the same as 0 %); then net and tax are null.

      • grossintegerrequired

        Gross amount at this rate. Integer amount in the smallest currency unit (cents).

      • netintegerrequirednullable

        gross − tax, in cents. null when rate_bps is null.

      • taxintegerrequirednullable

        VAT contained in gross: round(gross × rate / (10000 + rate)), in cents. null when rate_bps is null.

  • paymentobjectrequired

    How and whether it is paid.

    Child fields (3)

    • methodstringrequired

      online: paid at checkout. on_site: paid at pickup, delivery or the table.

      Values:"online""on_site"

    • statusstringrequired

      paid once the online payment is confirmed. open: to be paid on site; it stays open, because Flavoso does not record payments on site.

      Values:"paid""open"

    • paid_atstring (date-time)requirednullable

      When it was paid; null while open.

  • customerobjectrequirednullable

    Only what is needed to hand the order over (data minimisation): no e-mail, and no phone for dine-in. null when neither is known.

    Child fields (2)

    • namestringrequirednullable

      The guest's name.

    • phonestringrequirednullable

      Phone for questions; null for dine-in.

  • deliveryobjectrequirednullable

    The delivery address; null unless type is delivery.

    Child fields (3)

    • addressstringrequirednullable

      Street and number.

    • postal_codestringrequirednullable

      Postal code.

    • citystringrequirednullable

      City.

  • tableobjectrequirednullable

    The table of a dine-in order; null otherwise.

    Child fields (2)

    • idstring (uuid)required

      The table (GET /tables).

    • labelstringrequirednullable

      The table's name, e.g. 4.

  • notestringrequirednullable

    Guest's note for the kitchen (allergies!).

  • itemsOrderItem[]required

    The lines.

    Child fields (8)

    • idstring (uuid)required

      The line.

    • product_idstring (uuid)requirednullable

      The dish (GET /menu/products/{id}); null when it was deleted since.

    • namestringrequired

      Name at the time of ordering.

    • quantityintegerrequired

      How many.

      min 1

    • unit_priceintegerrequired

      Price of one unit including options. Integer amount in the smallest currency unit (cents).

    • line_totalintegerrequired

      unit_price × quantity. Integer amount in the smallest currency unit (cents).

    • tax_rate_bpsintegerrequirednullable

      VAT rate frozen at order time, in basis points (700 = 7 %). null when the restaurant has not set rates.

    • optionsobject[]required

      The chosen options (extras, sizes), as ordered. Name, surcharge and group name are frozen at order time; the ids point to the menu (GET /menu/options/{id}) as long as the option exists.

      Child fields (5)

      • idstring (uuid)requirednullable

        The option (GET /menu/options/{id}); with it you find your own modifier through its external_id. null for orders placed before 8 October 2026.

      • namestringrequired

        Name of the option.

      • price_deltaintegerrequired

        Surcharge of this option, per unit. Integer amount in the smallest currency unit (cents).

      • group_idstring (uuid)requirednullable

        The option group the option was chosen in (GET /menu/option-groups/{id}). null for orders placed before 8 October 2026.

      • group_namestringrequirednullable

        Name of that group at order time, e.g. Extras or Size. null for orders placed before 8 October 2026.

• has_morebooleanrequired

  Whether another page follows.

• next_cursorstringrequirednullable

  Pass as cursor (with the same filters) to get the next page; null on the last page.

Errors

• 400invalid_request: a parameter or the body is wrong, or it contains a query parameter or field the operation does not know. param names the field.
• 401unauthorized: missing, malformed, expired or revoked access token, or the app was disconnected or suspended.
• 403insufficient_scope, plan_required (with param when an order type is not in the plan) or account_inactive.
• 429rate_limited: more than 120 requests per minute on this connection. Wait Retry-After seconds.
• 500server_error. Safe to retry with the same Idempotency-Key.

All error codes

Retrieve an order#

get/orders/{id}

Scope:

orders:read

Plan:

every plan

The order with everything a POS needs for the receipt: items with options, amounts, VAT per rate, payment, the guest's name (and phone for pickup and delivery) and, for delivery, the address. external_id and acknowledged_at are your app's own values.

Parameters

Response200

OK

• objectstringrequired

  Always order.

  Values:"order"

• idstring (uuid)required

  The order.

• codestringrequired

  Short code the guest sees and says at the counter, e.g. K7Q2M9.

• external_idstringrequirednullable

  Your app's reference set with POST /orders/{id}/acknowledge; null when none. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• typestringrequired

  How the guest gets the order.

  Values:"pickup""delivery""dine_in"

• sourcestringrequired

  Where it was placed: table via a table's QR code, app in the Flavoso app by a signed-in guest, storefront everything else (the restaurant's ordering page, the app without sign-in).

  Values:"storefront""table""app"

• statusstringrequired

  Where the order is now. Restaurants may skip statuses, see GET /store.

  Values:"pending""confirmed""preparing""ready""completed""cancelled"

• created_atstring (date-time)required

  When the order was placed. ISO 8601 in UTC (Z).

• updated_atstring (date-time)required

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)requirednullable

  When your app first acknowledged the order (POST /orders/{id}/acknowledge); null when not yet. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• requested_forstring (date-time)requirednullable

  Pickup or delivery time chosen by the guest (pre-order); null means as soon as possible.

• currencystringrequired

  ISO 4217, e.g. EUR.

• amountsobjectrequired

  The amounts of the order, in cents.

  Child fields (6)

  • subtotalintegerrequired

    Sum of the items. Integer amount in the smallest currency unit (cents).

  • delivery_feeintegerrequired

    Delivery fee. Integer amount in the smallest currency unit (cents).

  • service_feeintegerrequired

    Service fee. Integer amount in the smallest currency unit (cents).

  • discountintegerrequired

    Discount (stamp card), already subtracted. Integer amount in the smallest currency unit (cents).

  • tipintegerrequired

    Tip. Pass-through, not revenue. Integer amount in the smallest currency unit (cents).

  • totalintegerrequired

    subtotal + delivery_fee + service_fee − discount + tip. Integer amount in the smallest currency unit (cents).

• taxobjectrequired

  VAT per rate of total − tip (items, fees, minus discount), computed like the restaurant's accounting export: discounts and delivery fees spread over the rates as the restaurant set it.

  Child fields (2)

  • includedbooleanrequired

    Always true: prices include VAT.

    Values:true

  • linesTaxLine[]required

    One line per rate, ascending, lines without rate last. The gross amounts add up to total − tip.

    Child fields (4)

    • rate_bpsintegerrequirednullable

      The rate in basis points (700 = 7 %). null: no rate was stored for this part (not the same as 0 %); then net and tax are null.

    • grossintegerrequired

      Gross amount at this rate. Integer amount in the smallest currency unit (cents).

    • netintegerrequirednullable

      gross − tax, in cents. null when rate_bps is null.

    • taxintegerrequirednullable

      VAT contained in gross: round(gross × rate / (10000 + rate)), in cents. null when rate_bps is null.

• paymentobjectrequired

  How and whether it is paid.

  Child fields (3)

  • methodstringrequired

    online: paid at checkout. on_site: paid at pickup, delivery or the table.

    Values:"online""on_site"

  • statusstringrequired

    paid once the online payment is confirmed. open: to be paid on site; it stays open, because Flavoso does not record payments on site.

    Values:"paid""open"

  • paid_atstring (date-time)requirednullable

    When it was paid; null while open.

• customerobjectrequirednullable

  Only what is needed to hand the order over (data minimisation): no e-mail, and no phone for dine-in. null when neither is known.

  Child fields (2)

  • namestringrequirednullable

    The guest's name.

  • phonestringrequirednullable

    Phone for questions; null for dine-in.

• deliveryobjectrequirednullable

  The delivery address; null unless type is delivery.

  Child fields (3)

  • addressstringrequirednullable

    Street and number.

  • postal_codestringrequirednullable

    Postal code.

  • citystringrequirednullable

    City.

• tableobjectrequirednullable

  The table of a dine-in order; null otherwise.

  Child fields (2)

  • idstring (uuid)required

    The table (GET /tables).

  • labelstringrequirednullable

    The table's name, e.g. 4.

• notestringrequirednullable

  Guest's note for the kitchen (allergies!).

• itemsOrderItem[]required

  The lines.

  Child fields (8)

  • idstring (uuid)required

    The line.

  • product_idstring (uuid)requirednullable

    The dish (GET /menu/products/{id}); null when it was deleted since.

  • namestringrequired

    Name at the time of ordering.

  • quantityintegerrequired

    How many.

    min 1

  • unit_priceintegerrequired

    Price of one unit including options. Integer amount in the smallest currency unit (cents).

  • line_totalintegerrequired

    unit_price × quantity. Integer amount in the smallest currency unit (cents).

  • tax_rate_bpsintegerrequirednullable

    VAT rate frozen at order time, in basis points (700 = 7 %). null when the restaurant has not set rates.

  • optionsobject[]required

    The chosen options (extras, sizes), as ordered. Name, surcharge and group name are frozen at order time; the ids point to the menu (GET /menu/options/{id}) as long as the option exists.

    Child fields (5)

    • idstring (uuid)requirednullable

      The option (GET /menu/options/{id}); with it you find your own modifier through its external_id. null for orders placed before 8 October 2026.

    • namestringrequired

      Name of the option.

    • price_deltaintegerrequired

      Surcharge of this option, per unit. Integer amount in the smallest currency unit (cents).

    • group_idstring (uuid)requirednullable

      The option group the option was chosen in (GET /menu/option-groups/{id}). null for orders placed before 8 October 2026.

    • group_namestringrequirednullable

      Name of that group at order time, e.g. Extras or Size. null for orders placed before 8 October 2026.

Errors

• 400invalid_request: a parameter or the body is wrong, or it contains a query parameter or field the operation does not know. param names the field.
• 401unauthorized: missing, malformed, expired or revoked access token, or the app was disconnected or suspended.
• 403insufficient_scope, plan_required (with param when an order type is not in the plan) or account_inactive.
• 404not_found: no such object in this restaurant (objects of other restaurants are never found).
• 429rate_limited: more than 120 requests per minute on this connection. Wait Retry-After seconds.
• 500server_error. Safe to retry with the same Idempotency-Key.

All error codes

Accept an order#

post/orders/{id}/accept

Scope:

orders:write

Plan:

every plan

Idempotency-Key

Moves a pending order to the first status this restaurant uses after pending: usually confirmed, preparing or ready when the restaurant switched confirmed off (GET /store lists order_statuses). The guest is notified exactly as if the restaurant had accepted in the dashboard.

An order that is already past pending (accepted elsewhere, or advanced) comes back unchanged with 200, so accepting twice is safe. A completed or cancelled order answers 409 invalid_transition.

Parameters

Response200

The order after the change.

• objectstringrequired

  Always order.

  Values:"order"

• idstring (uuid)required

  The order.

• codestringrequired

  Short code the guest sees and says at the counter, e.g. K7Q2M9.

• external_idstringrequirednullable

  Your app's reference set with POST /orders/{id}/acknowledge; null when none. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• typestringrequired

  How the guest gets the order.

  Values:"pickup""delivery""dine_in"

• sourcestringrequired

  Where it was placed: table via a table's QR code, app in the Flavoso app by a signed-in guest, storefront everything else (the restaurant's ordering page, the app without sign-in).

  Values:"storefront""table""app"

• statusstringrequired

  Where the order is now. Restaurants may skip statuses, see GET /store.

  Values:"pending""confirmed""preparing""ready""completed""cancelled"

• created_atstring (date-time)required

  When the order was placed. ISO 8601 in UTC (Z).

• updated_atstring (date-time)required

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)requirednullable

  When your app first acknowledged the order (POST /orders/{id}/acknowledge); null when not yet. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• requested_forstring (date-time)requirednullable

  Pickup or delivery time chosen by the guest (pre-order); null means as soon as possible.

• currencystringrequired

  ISO 4217, e.g. EUR.

• amountsobjectrequired

  The amounts of the order, in cents.

  Child fields (6)

  • subtotalintegerrequired

    Sum of the items. Integer amount in the smallest currency unit (cents).

  • delivery_feeintegerrequired

    Delivery fee. Integer amount in the smallest currency unit (cents).

  • service_feeintegerrequired

    Service fee. Integer amount in the smallest currency unit (cents).

  • discountintegerrequired

    Discount (stamp card), already subtracted. Integer amount in the smallest currency unit (cents).

  • tipintegerrequired

    Tip. Pass-through, not revenue. Integer amount in the smallest currency unit (cents).

  • totalintegerrequired

    subtotal + delivery_fee + service_fee − discount + tip. Integer amount in the smallest currency unit (cents).

• taxobjectrequired

  VAT per rate of total − tip (items, fees, minus discount), computed like the restaurant's accounting export: discounts and delivery fees spread over the rates as the restaurant set it.

  Child fields (2)

  • includedbooleanrequired

    Always true: prices include VAT.

    Values:true

  • linesTaxLine[]required

    One line per rate, ascending, lines without rate last. The gross amounts add up to total − tip.

    Child fields (4)

    • rate_bpsintegerrequirednullable

      The rate in basis points (700 = 7 %). null: no rate was stored for this part (not the same as 0 %); then net and tax are null.

    • grossintegerrequired

      Gross amount at this rate. Integer amount in the smallest currency unit (cents).

    • netintegerrequirednullable

      gross − tax, in cents. null when rate_bps is null.

    • taxintegerrequirednullable

      VAT contained in gross: round(gross × rate / (10000 + rate)), in cents. null when rate_bps is null.

• paymentobjectrequired

  How and whether it is paid.

  Child fields (3)

  • methodstringrequired

    online: paid at checkout. on_site: paid at pickup, delivery or the table.

    Values:"online""on_site"

  • statusstringrequired

    paid once the online payment is confirmed. open: to be paid on site; it stays open, because Flavoso does not record payments on site.

    Values:"paid""open"

  • paid_atstring (date-time)requirednullable

    When it was paid; null while open.

• customerobjectrequirednullable

  Only what is needed to hand the order over (data minimisation): no e-mail, and no phone for dine-in. null when neither is known.

  Child fields (2)

  • namestringrequirednullable

    The guest's name.

  • phonestringrequirednullable

    Phone for questions; null for dine-in.

• deliveryobjectrequirednullable

  The delivery address; null unless type is delivery.

  Child fields (3)

  • addressstringrequirednullable

    Street and number.

  • postal_codestringrequirednullable

    Postal code.

  • citystringrequirednullable

    City.

• tableobjectrequirednullable

  The table of a dine-in order; null otherwise.

  Child fields (2)

  • idstring (uuid)required

    The table (GET /tables).

  • labelstringrequirednullable

    The table's name, e.g. 4.

• notestringrequirednullable

  Guest's note for the kitchen (allergies!).

• itemsOrderItem[]required

  The lines.

  Child fields (8)

  • idstring (uuid)required

    The line.

  • product_idstring (uuid)requirednullable

    The dish (GET /menu/products/{id}); null when it was deleted since.

  • namestringrequired

    Name at the time of ordering.

  • quantityintegerrequired

    How many.

    min 1

  • unit_priceintegerrequired

    Price of one unit including options. Integer amount in the smallest currency unit (cents).

  • line_totalintegerrequired

    unit_price × quantity. Integer amount in the smallest currency unit (cents).

  • tax_rate_bpsintegerrequirednullable

    VAT rate frozen at order time, in basis points (700 = 7 %). null when the restaurant has not set rates.

  • optionsobject[]required

    The chosen options (extras, sizes), as ordered. Name, surcharge and group name are frozen at order time; the ids point to the menu (GET /menu/options/{id}) as long as the option exists.

    Child fields (5)

    • idstring (uuid)requirednullable

      The option (GET /menu/options/{id}); with it you find your own modifier through its external_id. null for orders placed before 8 October 2026.

    • namestringrequired

      Name of the option.

    • price_deltaintegerrequired

      Surcharge of this option, per unit. Integer amount in the smallest currency unit (cents).

    • group_idstring (uuid)requirednullable

      The option group the option was chosen in (GET /menu/option-groups/{id}). null for orders placed before 8 October 2026.

    • group_namestringrequirednullable

      Name of that group at order time, e.g. Extras or Size. null for orders placed before 8 October 2026.

Errors

• 400invalid_request: a parameter or the body is wrong, or it contains a query parameter or field the operation does not know. param names the field.
• 401unauthorized: missing, malformed, expired or revoked access token, or the app was disconnected or suspended.
• 403insufficient_scope, plan_required (with param when an order type is not in the plan) or account_inactive.
• 404not_found: no such object in this restaurant (objects of other restaurants are never found).
• 409invalid_transition (the status of the object does not allow this), stage_not_used (the restaurant does not use this status), external_id_taken (your app already uses this external_id for another object of the same kind in this restaurant), slot_unavailable (the time or the table is taken), idempotency_in_progress (a request with this Idempotency-Key is still running) or conflict (the same data was changed elsewhere at the same moment, three times in a row; retry unchanged after Retry-After seconds).
• 413payload_too_large: the body is larger than the operation takes, counted in bytes: 64 KB, 2 MB for PUT /menu. Split the request.
• 422idempotency_key_reused (the key was used with a different request) or limit_exceeded (too many entries in one request, such as products in PUT /menu, or a limit of the restaurant is reached, such as 60 special days).
• 429rate_limited: more than 120 requests per minute on this connection. Wait Retry-After seconds.
• 500server_error. Safe to retry with the same Idempotency-Key.

All error codes

Reject an order#

post/orders/{id}/reject

Scope:

orders:write

Plan:

every plan

Idempotency-Key

Cancels an order that has not been accepted yet (pending only). The guest receives the cancellation notice; reason goes into the restaurant's audit log.

Parameters

Bodyapplication/json

• reasonstring

  Free text for the restaurant's audit log, e.g. 'out of dough', at most 200 characters (longer answers 400 with param). Not shown to the guest.

  max 200 chars

Response200

The order after the change.

• objectstringrequired

  Always order.

  Values:"order"

• idstring (uuid)required

  The order.

• codestringrequired

  Short code the guest sees and says at the counter, e.g. K7Q2M9.

• external_idstringrequirednullable

  Your app's reference set with POST /orders/{id}/acknowledge; null when none. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• typestringrequired

  How the guest gets the order.

  Values:"pickup""delivery""dine_in"

• sourcestringrequired

  Where it was placed: table via a table's QR code, app in the Flavoso app by a signed-in guest, storefront everything else (the restaurant's ordering page, the app without sign-in).

  Values:"storefront""table""app"

• statusstringrequired

  Where the order is now. Restaurants may skip statuses, see GET /store.

  Values:"pending""confirmed""preparing""ready""completed""cancelled"

• created_atstring (date-time)required

  When the order was placed. ISO 8601 in UTC (Z).

• updated_atstring (date-time)required

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)requirednullable

  When your app first acknowledged the order (POST /orders/{id}/acknowledge); null when not yet. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• requested_forstring (date-time)requirednullable

  Pickup or delivery time chosen by the guest (pre-order); null means as soon as possible.

• currencystringrequired

  ISO 4217, e.g. EUR.

• amountsobjectrequired

  The amounts of the order, in cents.

  Child fields (6)

  • subtotalintegerrequired

    Sum of the items. Integer amount in the smallest currency unit (cents).

  • delivery_feeintegerrequired

    Delivery fee. Integer amount in the smallest currency unit (cents).

  • service_feeintegerrequired

    Service fee. Integer amount in the smallest currency unit (cents).

  • discountintegerrequired

    Discount (stamp card), already subtracted. Integer amount in the smallest currency unit (cents).

  • tipintegerrequired

    Tip. Pass-through, not revenue. Integer amount in the smallest currency unit (cents).

  • totalintegerrequired

    subtotal + delivery_fee + service_fee − discount + tip. Integer amount in the smallest currency unit (cents).

• taxobjectrequired

  VAT per rate of total − tip (items, fees, minus discount), computed like the restaurant's accounting export: discounts and delivery fees spread over the rates as the restaurant set it.

  Child fields (2)

  • includedbooleanrequired

    Always true: prices include VAT.

    Values:true

  • linesTaxLine[]required

    One line per rate, ascending, lines without rate last. The gross amounts add up to total − tip.

    Child fields (4)

    • rate_bpsintegerrequirednullable

      The rate in basis points (700 = 7 %). null: no rate was stored for this part (not the same as 0 %); then net and tax are null.

    • grossintegerrequired

      Gross amount at this rate. Integer amount in the smallest currency unit (cents).

    • netintegerrequirednullable

      gross − tax, in cents. null when rate_bps is null.

    • taxintegerrequirednullable

      VAT contained in gross: round(gross × rate / (10000 + rate)), in cents. null when rate_bps is null.

• paymentobjectrequired

  How and whether it is paid.

  Child fields (3)

  • methodstringrequired

    online: paid at checkout. on_site: paid at pickup, delivery or the table.

    Values:"online""on_site"

  • statusstringrequired

    paid once the online payment is confirmed. open: to be paid on site; it stays open, because Flavoso does not record payments on site.

    Values:"paid""open"

  • paid_atstring (date-time)requirednullable

    When it was paid; null while open.

• customerobjectrequirednullable

  Only what is needed to hand the order over (data minimisation): no e-mail, and no phone for dine-in. null when neither is known.

  Child fields (2)

  • namestringrequirednullable

    The guest's name.

  • phonestringrequirednullable

    Phone for questions; null for dine-in.

• deliveryobjectrequirednullable

  The delivery address; null unless type is delivery.

  Child fields (3)

  • addressstringrequirednullable

    Street and number.

  • postal_codestringrequirednullable

    Postal code.

  • citystringrequirednullable

    City.

• tableobjectrequirednullable

  The table of a dine-in order; null otherwise.

  Child fields (2)

  • idstring (uuid)required

    The table (GET /tables).

  • labelstringrequirednullable

    The table's name, e.g. 4.

• notestringrequirednullable

  Guest's note for the kitchen (allergies!).

• itemsOrderItem[]required

  The lines.

  Child fields (8)

  • idstring (uuid)required

    The line.

  • product_idstring (uuid)requirednullable

    The dish (GET /menu/products/{id}); null when it was deleted since.

  • namestringrequired

    Name at the time of ordering.

  • quantityintegerrequired

    How many.

    min 1

  • unit_priceintegerrequired

    Price of one unit including options. Integer amount in the smallest currency unit (cents).

  • line_totalintegerrequired

    unit_price × quantity. Integer amount in the smallest currency unit (cents).

  • tax_rate_bpsintegerrequirednullable

    VAT rate frozen at order time, in basis points (700 = 7 %). null when the restaurant has not set rates.

  • optionsobject[]required

    The chosen options (extras, sizes), as ordered. Name, surcharge and group name are frozen at order time; the ids point to the menu (GET /menu/options/{id}) as long as the option exists.

    Child fields (5)

    • idstring (uuid)requirednullable

      The option (GET /menu/options/{id}); with it you find your own modifier through its external_id. null for orders placed before 8 October 2026.

    • namestringrequired

      Name of the option.

    • price_deltaintegerrequired

      Surcharge of this option, per unit. Integer amount in the smallest currency unit (cents).

    • group_idstring (uuid)requirednullable

      The option group the option was chosen in (GET /menu/option-groups/{id}). null for orders placed before 8 October 2026.

    • group_namestringrequirednullable

      Name of that group at order time, e.g. Extras or Size. null for orders placed before 8 October 2026.

Errors

• 400invalid_request: a parameter or the body is wrong, or it contains a query parameter or field the operation does not know. param names the field.
• 401unauthorized: missing, malformed, expired or revoked access token, or the app was disconnected or suspended.
• 403insufficient_scope, plan_required (with param when an order type is not in the plan) or account_inactive.
• 404not_found: no such object in this restaurant (objects of other restaurants are never found).
• 409invalid_transition (the status of the object does not allow this), stage_not_used (the restaurant does not use this status), external_id_taken (your app already uses this external_id for another object of the same kind in this restaurant), slot_unavailable (the time or the table is taken), idempotency_in_progress (a request with this Idempotency-Key is still running) or conflict (the same data was changed elsewhere at the same moment, three times in a row; retry unchanged after Retry-After seconds).
• 413payload_too_large: the body is larger than the operation takes, counted in bytes: 64 KB, 2 MB for PUT /menu. Split the request.
• 422idempotency_key_reused (the key was used with a different request) or limit_exceeded (too many entries in one request, such as products in PUT /menu, or a limit of the restaurant is reached, such as 60 special days).
• 429rate_limited: more than 120 requests per minute on this connection. Wait Retry-After seconds.
• 500server_error. Safe to retry with the same Idempotency-Key.

All error codes

Cancel an order#

post/orders/{id}/cancel

Scope:

orders:write

Plan:

every plan

Idempotency-Key

Cancels an order from any open status. Guest and staff are notified, the order leaves the kitchen display.

Parameters

Bodyapplication/json

• reasonstring

  Free text for the restaurant's audit log, e.g. 'out of dough', at most 200 characters (longer answers 400 with param). Not shown to the guest.

  max 200 chars

Response200

The order after the change.

• objectstringrequired

  Always order.

  Values:"order"

• idstring (uuid)required

  The order.

• codestringrequired

  Short code the guest sees and says at the counter, e.g. K7Q2M9.

• external_idstringrequirednullable

  Your app's reference set with POST /orders/{id}/acknowledge; null when none. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• typestringrequired

  How the guest gets the order.

  Values:"pickup""delivery""dine_in"

• sourcestringrequired

  Where it was placed: table via a table's QR code, app in the Flavoso app by a signed-in guest, storefront everything else (the restaurant's ordering page, the app without sign-in).

  Values:"storefront""table""app"

• statusstringrequired

  Where the order is now. Restaurants may skip statuses, see GET /store.

  Values:"pending""confirmed""preparing""ready""completed""cancelled"

• created_atstring (date-time)required

  When the order was placed. ISO 8601 in UTC (Z).

• updated_atstring (date-time)required

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)requirednullable

  When your app first acknowledged the order (POST /orders/{id}/acknowledge); null when not yet. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• requested_forstring (date-time)requirednullable

  Pickup or delivery time chosen by the guest (pre-order); null means as soon as possible.

• currencystringrequired

  ISO 4217, e.g. EUR.

• amountsobjectrequired

  The amounts of the order, in cents.

  Child fields (6)

  • subtotalintegerrequired

    Sum of the items. Integer amount in the smallest currency unit (cents).

  • delivery_feeintegerrequired

    Delivery fee. Integer amount in the smallest currency unit (cents).

  • service_feeintegerrequired

    Service fee. Integer amount in the smallest currency unit (cents).

  • discountintegerrequired

    Discount (stamp card), already subtracted. Integer amount in the smallest currency unit (cents).

  • tipintegerrequired

    Tip. Pass-through, not revenue. Integer amount in the smallest currency unit (cents).

  • totalintegerrequired

    subtotal + delivery_fee + service_fee − discount + tip. Integer amount in the smallest currency unit (cents).

• taxobjectrequired

  VAT per rate of total − tip (items, fees, minus discount), computed like the restaurant's accounting export: discounts and delivery fees spread over the rates as the restaurant set it.

  Child fields (2)

  • includedbooleanrequired

    Always true: prices include VAT.

    Values:true

  • linesTaxLine[]required

    One line per rate, ascending, lines without rate last. The gross amounts add up to total − tip.

    Child fields (4)

    • rate_bpsintegerrequirednullable

      The rate in basis points (700 = 7 %). null: no rate was stored for this part (not the same as 0 %); then net and tax are null.

    • grossintegerrequired

      Gross amount at this rate. Integer amount in the smallest currency unit (cents).

    • netintegerrequirednullable

      gross − tax, in cents. null when rate_bps is null.

    • taxintegerrequirednullable

      VAT contained in gross: round(gross × rate / (10000 + rate)), in cents. null when rate_bps is null.

• paymentobjectrequired

  How and whether it is paid.

  Child fields (3)

  • methodstringrequired

    online: paid at checkout. on_site: paid at pickup, delivery or the table.

    Values:"online""on_site"

  • statusstringrequired

    paid once the online payment is confirmed. open: to be paid on site; it stays open, because Flavoso does not record payments on site.

    Values:"paid""open"

  • paid_atstring (date-time)requirednullable

    When it was paid; null while open.

• customerobjectrequirednullable

  Only what is needed to hand the order over (data minimisation): no e-mail, and no phone for dine-in. null when neither is known.

  Child fields (2)

  • namestringrequirednullable

    The guest's name.

  • phonestringrequirednullable

    Phone for questions; null for dine-in.

• deliveryobjectrequirednullable

  The delivery address; null unless type is delivery.

  Child fields (3)

  • addressstringrequirednullable

    Street and number.

  • postal_codestringrequirednullable

    Postal code.

  • citystringrequirednullable

    City.

• tableobjectrequirednullable

  The table of a dine-in order; null otherwise.

  Child fields (2)

  • idstring (uuid)required

    The table (GET /tables).

  • labelstringrequirednullable

    The table's name, e.g. 4.

• notestringrequirednullable

  Guest's note for the kitchen (allergies!).

• itemsOrderItem[]required

  The lines.

  Child fields (8)

  • idstring (uuid)required

    The line.

  • product_idstring (uuid)requirednullable

    The dish (GET /menu/products/{id}); null when it was deleted since.

  • namestringrequired

    Name at the time of ordering.

  • quantityintegerrequired

    How many.

    min 1

  • unit_priceintegerrequired

    Price of one unit including options. Integer amount in the smallest currency unit (cents).

  • line_totalintegerrequired

    unit_price × quantity. Integer amount in the smallest currency unit (cents).

  • tax_rate_bpsintegerrequirednullable

    VAT rate frozen at order time, in basis points (700 = 7 %). null when the restaurant has not set rates.

  • optionsobject[]required

    The chosen options (extras, sizes), as ordered. Name, surcharge and group name are frozen at order time; the ids point to the menu (GET /menu/options/{id}) as long as the option exists.

    Child fields (5)

    • idstring (uuid)requirednullable

      The option (GET /menu/options/{id}); with it you find your own modifier through its external_id. null for orders placed before 8 October 2026.

    • namestringrequired

      Name of the option.

    • price_deltaintegerrequired

      Surcharge of this option, per unit. Integer amount in the smallest currency unit (cents).

    • group_idstring (uuid)requirednullable

      The option group the option was chosen in (GET /menu/option-groups/{id}). null for orders placed before 8 October 2026.

    • group_namestringrequirednullable

      Name of that group at order time, e.g. Extras or Size. null for orders placed before 8 October 2026.

Errors

• 400invalid_request: a parameter or the body is wrong, or it contains a query parameter or field the operation does not know. param names the field.
• 401unauthorized: missing, malformed, expired or revoked access token, or the app was disconnected or suspended.
• 403insufficient_scope, plan_required (with param when an order type is not in the plan) or account_inactive.
• 404not_found: no such object in this restaurant (objects of other restaurants are never found).
• 409invalid_transition (the status of the object does not allow this), stage_not_used (the restaurant does not use this status), external_id_taken (your app already uses this external_id for another object of the same kind in this restaurant), slot_unavailable (the time or the table is taken), idempotency_in_progress (a request with this Idempotency-Key is still running) or conflict (the same data was changed elsewhere at the same moment, three times in a row; retry unchanged after Retry-After seconds).
• 413payload_too_large: the body is larger than the operation takes, counted in bytes: 64 KB, 2 MB for PUT /menu. Split the request.
• 422idempotency_key_reused (the key was used with a different request) or limit_exceeded (too many entries in one request, such as products in PUT /menu, or a limit of the restaurant is reached, such as 60 special days).
• 429rate_limited: more than 120 requests per minute on this connection. Wait Retry-After seconds.
• 500server_error. Safe to retry with the same Idempotency-Key.

All error codes

Advance an order#

post/orders/{id}/status

Scope:

orders:write

Plan:

every plan

Idempotency-Key

Moves an order forward to confirmed, preparing, ready or completed. Skipping ahead is allowed (confirmed → ready), moving back is not (invalid_transition). Setting the current status again returns the order unchanged.

Restaurants can switch statuses off. A status this restaurant does not use returns stage_not_used; GET /store lists order_statuses.

For delivery orders, ready means ready for the driver and completed means delivered.

Parameters

Bodyapplication/json

• statusstringrequired

  The status to move to. Use /cancel to cancel.

  Values:"confirmed""preparing""ready""completed"

Response200

The order after the change.

• objectstringrequired

  Always order.

  Values:"order"

• idstring (uuid)required

  The order.

• codestringrequired

  Short code the guest sees and says at the counter, e.g. K7Q2M9.

• external_idstringrequirednullable

  Your app's reference set with POST /orders/{id}/acknowledge; null when none. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• typestringrequired

  How the guest gets the order.

  Values:"pickup""delivery""dine_in"

• sourcestringrequired

  Where it was placed: table via a table's QR code, app in the Flavoso app by a signed-in guest, storefront everything else (the restaurant's ordering page, the app without sign-in).

  Values:"storefront""table""app"

• statusstringrequired

  Where the order is now. Restaurants may skip statuses, see GET /store.

  Values:"pending""confirmed""preparing""ready""completed""cancelled"

• created_atstring (date-time)required

  When the order was placed. ISO 8601 in UTC (Z).

• updated_atstring (date-time)required

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)requirednullable

  When your app first acknowledged the order (POST /orders/{id}/acknowledge); null when not yet. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• requested_forstring (date-time)requirednullable

  Pickup or delivery time chosen by the guest (pre-order); null means as soon as possible.

• currencystringrequired

  ISO 4217, e.g. EUR.

• amountsobjectrequired

  The amounts of the order, in cents.

  Child fields (6)

  • subtotalintegerrequired

    Sum of the items. Integer amount in the smallest currency unit (cents).

  • delivery_feeintegerrequired

    Delivery fee. Integer amount in the smallest currency unit (cents).

  • service_feeintegerrequired

    Service fee. Integer amount in the smallest currency unit (cents).

  • discountintegerrequired

    Discount (stamp card), already subtracted. Integer amount in the smallest currency unit (cents).

  • tipintegerrequired

    Tip. Pass-through, not revenue. Integer amount in the smallest currency unit (cents).

  • totalintegerrequired

    subtotal + delivery_fee + service_fee − discount + tip. Integer amount in the smallest currency unit (cents).

• taxobjectrequired

  VAT per rate of total − tip (items, fees, minus discount), computed like the restaurant's accounting export: discounts and delivery fees spread over the rates as the restaurant set it.

  Child fields (2)

  • includedbooleanrequired

    Always true: prices include VAT.

    Values:true

  • linesTaxLine[]required

    One line per rate, ascending, lines without rate last. The gross amounts add up to total − tip.

    Child fields (4)

    • rate_bpsintegerrequirednullable

      The rate in basis points (700 = 7 %). null: no rate was stored for this part (not the same as 0 %); then net and tax are null.

    • grossintegerrequired

      Gross amount at this rate. Integer amount in the smallest currency unit (cents).

    • netintegerrequirednullable

      gross − tax, in cents. null when rate_bps is null.

    • taxintegerrequirednullable

      VAT contained in gross: round(gross × rate / (10000 + rate)), in cents. null when rate_bps is null.

• paymentobjectrequired

  How and whether it is paid.

  Child fields (3)

  • methodstringrequired

    online: paid at checkout. on_site: paid at pickup, delivery or the table.

    Values:"online""on_site"

  • statusstringrequired

    paid once the online payment is confirmed. open: to be paid on site; it stays open, because Flavoso does not record payments on site.

    Values:"paid""open"

  • paid_atstring (date-time)requirednullable

    When it was paid; null while open.

• customerobjectrequirednullable

  Only what is needed to hand the order over (data minimisation): no e-mail, and no phone for dine-in. null when neither is known.

  Child fields (2)

  • namestringrequirednullable

    The guest's name.

  • phonestringrequirednullable

    Phone for questions; null for dine-in.

• deliveryobjectrequirednullable

  The delivery address; null unless type is delivery.

  Child fields (3)

  • addressstringrequirednullable

    Street and number.

  • postal_codestringrequirednullable

    Postal code.

  • citystringrequirednullable

    City.

• tableobjectrequirednullable

  The table of a dine-in order; null otherwise.

  Child fields (2)

  • idstring (uuid)required

    The table (GET /tables).

  • labelstringrequirednullable

    The table's name, e.g. 4.

• notestringrequirednullable

  Guest's note for the kitchen (allergies!).

• itemsOrderItem[]required

  The lines.

  Child fields (8)

  • idstring (uuid)required

    The line.

  • product_idstring (uuid)requirednullable

    The dish (GET /menu/products/{id}); null when it was deleted since.

  • namestringrequired

    Name at the time of ordering.

  • quantityintegerrequired

    How many.

    min 1

  • unit_priceintegerrequired

    Price of one unit including options. Integer amount in the smallest currency unit (cents).

  • line_totalintegerrequired

    unit_price × quantity. Integer amount in the smallest currency unit (cents).

  • tax_rate_bpsintegerrequirednullable

    VAT rate frozen at order time, in basis points (700 = 7 %). null when the restaurant has not set rates.

  • optionsobject[]required

    The chosen options (extras, sizes), as ordered. Name, surcharge and group name are frozen at order time; the ids point to the menu (GET /menu/options/{id}) as long as the option exists.

    Child fields (5)

    • idstring (uuid)requirednullable

      The option (GET /menu/options/{id}); with it you find your own modifier through its external_id. null for orders placed before 8 October 2026.

    • namestringrequired

      Name of the option.

    • price_deltaintegerrequired

      Surcharge of this option, per unit. Integer amount in the smallest currency unit (cents).

    • group_idstring (uuid)requirednullable

      The option group the option was chosen in (GET /menu/option-groups/{id}). null for orders placed before 8 October 2026.

    • group_namestringrequirednullable

      Name of that group at order time, e.g. Extras or Size. null for orders placed before 8 October 2026.

Errors

• 400invalid_request: a parameter or the body is wrong, or it contains a query parameter or field the operation does not know. param names the field.
• 401unauthorized: missing, malformed, expired or revoked access token, or the app was disconnected or suspended.
• 403insufficient_scope, plan_required (with param when an order type is not in the plan) or account_inactive.
• 404not_found: no such object in this restaurant (objects of other restaurants are never found).
• 409invalid_transition (the status of the object does not allow this), stage_not_used (the restaurant does not use this status), external_id_taken (your app already uses this external_id for another object of the same kind in this restaurant), slot_unavailable (the time or the table is taken), idempotency_in_progress (a request with this Idempotency-Key is still running) or conflict (the same data was changed elsewhere at the same moment, three times in a row; retry unchanged after Retry-After seconds).
• 413payload_too_large: the body is larger than the operation takes, counted in bytes: 64 KB, 2 MB for PUT /menu. Split the request.
• 422idempotency_key_reused (the key was used with a different request) or limit_exceeded (too many entries in one request, such as products in PUT /menu, or a limit of the restaurant is reached, such as 60 special days).
• 429rate_limited: more than 120 requests per minute on this connection. Wait Retry-After seconds.
• 500server_error. Safe to retry with the same Idempotency-Key.

All error codes

Acknowledge an order#

post/orders/{id}/acknowledge

Scope:

orders:write

Plan:

every plan

Idempotency-Key

Tells Flavoso your app has taken over the order (booked it into the POS, printed it), optionally with your own reference (external_id, e.g. the receipt number). The first call sets acknowledged_at; later calls keep it and only change external_id (send null to remove it). Safe to repeat.

Both values belong to your app: another app connected to the same restaurant sees its own. Find orders you have not taken over yet with GET /orders?acknowledged=false.

Does not change the order's status; use /accept for that. An external_id your app already uses for another order of this restaurant answers 409 external_id_taken.

Parameters

Bodyapplication/json

• external_idstringnullable

  Your reference for this order, 1 to 100 printable characters, unique per app and restaurant. null removes it; omit it to keep the current one.

  1 to 100 chars

Response200

The order with your external_id and acknowledged_at.

• objectstringrequired

  Always order.

  Values:"order"

• idstring (uuid)required

  The order.

• codestringrequired

  Short code the guest sees and says at the counter, e.g. K7Q2M9.

• external_idstringrequirednullable

  Your app's reference set with POST /orders/{id}/acknowledge; null when none. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• typestringrequired

  How the guest gets the order.

  Values:"pickup""delivery""dine_in"

• sourcestringrequired

  Where it was placed: table via a table's QR code, app in the Flavoso app by a signed-in guest, storefront everything else (the restaurant's ordering page, the app without sign-in).

  Values:"storefront""table""app"

• statusstringrequired

  Where the order is now. Restaurants may skip statuses, see GET /store.

  Values:"pending""confirmed""preparing""ready""completed""cancelled"

• created_atstring (date-time)required

  When the order was placed. ISO 8601 in UTC (Z).

• updated_atstring (date-time)required

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)requirednullable

  When your app first acknowledged the order (POST /orders/{id}/acknowledge); null when not yet. Always null in webhook events and in GET /events: the envelope is built once and sent the same to every receiver, but this value belongs to a single app. Retrieve the object to see yours.

• requested_forstring (date-time)requirednullable

  Pickup or delivery time chosen by the guest (pre-order); null means as soon as possible.

• currencystringrequired

  ISO 4217, e.g. EUR.

• amountsobjectrequired

  The amounts of the order, in cents.

  Child fields (6)

  • subtotalintegerrequired

    Sum of the items. Integer amount in the smallest currency unit (cents).

  • delivery_feeintegerrequired

    Delivery fee. Integer amount in the smallest currency unit (cents).

  • service_feeintegerrequired

    Service fee. Integer amount in the smallest currency unit (cents).

  • discountintegerrequired

    Discount (stamp card), already subtracted. Integer amount in the smallest currency unit (cents).

  • tipintegerrequired

    Tip. Pass-through, not revenue. Integer amount in the smallest currency unit (cents).

  • totalintegerrequired

    subtotal + delivery_fee + service_fee − discount + tip. Integer amount in the smallest currency unit (cents).

• taxobjectrequired

  VAT per rate of total − tip (items, fees, minus discount), computed like the restaurant's accounting export: discounts and delivery fees spread over the rates as the restaurant set it.

  Child fields (2)

  • includedbooleanrequired

    Always true: prices include VAT.

    Values:true

  • linesTaxLine[]required

    One line per rate, ascending, lines without rate last. The gross amounts add up to total − tip.

    Child fields (4)

    • rate_bpsintegerrequirednullable

      The rate in basis points (700 = 7 %). null: no rate was stored for this part (not the same as 0 %); then net and tax are null.

    • grossintegerrequired

      Gross amount at this rate. Integer amount in the smallest currency unit (cents).

    • netintegerrequirednullable

      gross − tax, in cents. null when rate_bps is null.

    • taxintegerrequirednullable

      VAT contained in gross: round(gross × rate / (10000 + rate)), in cents. null when rate_bps is null.

• paymentobjectrequired

  How and whether it is paid.

  Child fields (3)

  • methodstringrequired

    online: paid at checkout. on_site: paid at pickup, delivery or the table.

    Values:"online""on_site"

  • statusstringrequired

    paid once the online payment is confirmed. open: to be paid on site; it stays open, because Flavoso does not record payments on site.

    Values:"paid""open"

  • paid_atstring (date-time)requirednullable

    When it was paid; null while open.

• customerobjectrequirednullable

  Only what is needed to hand the order over (data minimisation): no e-mail, and no phone for dine-in. null when neither is known.

  Child fields (2)

  • namestringrequirednullable

    The guest's name.

  • phonestringrequirednullable

    Phone for questions; null for dine-in.

• deliveryobjectrequirednullable

  The delivery address; null unless type is delivery.

  Child fields (3)

  • addressstringrequirednullable

    Street and number.

  • postal_codestringrequirednullable

    Postal code.

  • citystringrequirednullable

    City.

• tableobjectrequirednullable

  The table of a dine-in order; null otherwise.

  Child fields (2)

  • idstring (uuid)required

    The table (GET /tables).

  • labelstringrequirednullable

    The table's name, e.g. 4.

• notestringrequirednullable

  Guest's note for the kitchen (allergies!).

• itemsOrderItem[]required

  The lines.

  Child fields (8)

  • idstring (uuid)required

    The line.

  • product_idstring (uuid)requirednullable

    The dish (GET /menu/products/{id}); null when it was deleted since.

  • namestringrequired

    Name at the time of ordering.

  • quantityintegerrequired

    How many.

    min 1

  • unit_priceintegerrequired

    Price of one unit including options. Integer amount in the smallest currency unit (cents).

  • line_totalintegerrequired

    unit_price × quantity. Integer amount in the smallest currency unit (cents).

  • tax_rate_bpsintegerrequirednullable

    VAT rate frozen at order time, in basis points (700 = 7 %). null when the restaurant has not set rates.

  • optionsobject[]required

    The chosen options (extras, sizes), as ordered. Name, surcharge and group name are frozen at order time; the ids point to the menu (GET /menu/options/{id}) as long as the option exists.

    Child fields (5)

    • idstring (uuid)requirednullable

      The option (GET /menu/options/{id}); with it you find your own modifier through its external_id. null for orders placed before 8 October 2026.

    • namestringrequired

      Name of the option.

    • price_deltaintegerrequired

      Surcharge of this option, per unit. Integer amount in the smallest currency unit (cents).

    • group_idstring (uuid)requirednullable

      The option group the option was chosen in (GET /menu/option-groups/{id}). null for orders placed before 8 October 2026.

    • group_namestringrequirednullable

      Name of that group at order time, e.g. Extras or Size. null for orders placed before 8 October 2026.

Errors

• 400invalid_request: a parameter or the body is wrong, or it contains a query parameter or field the operation does not know. param names the field.
• 401unauthorized: missing, malformed, expired or revoked access token, or the app was disconnected or suspended.
• 403insufficient_scope, plan_required (with param when an order type is not in the plan) or account_inactive.
• 404not_found: no such object in this restaurant (objects of other restaurants are never found).
• 409invalid_transition (the status of the object does not allow this), stage_not_used (the restaurant does not use this status), external_id_taken (your app already uses this external_id for another object of the same kind in this restaurant), slot_unavailable (the time or the table is taken), idempotency_in_progress (a request with this Idempotency-Key is still running) or conflict (the same data was changed elsewhere at the same moment, three times in a row; retry unchanged after Retry-After seconds).
• 413payload_too_large: the body is larger than the operation takes, counted in bytes: 64 KB, 2 MB for PUT /menu. Split the request.
• 422idempotency_key_reused (the key was used with a different request) or limit_exceeded (too many entries in one request, such as products in PUT /menu, or a limit of the restaurant is reached, such as 60 special days).
• 429rate_limited: more than 120 requests per minute on this connection. Wait Retry-After seconds.
• 500server_error. Safe to retry with the same Idempotency-Key.

All error codes