Ordini

List orders#

get/orders

Permesso:

orders:read

Piano:

tutti i piani

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.

Parametri

Risposta200

OK

• objectstringobbligatorio

  Always list.

  Valori:"list"

• dataOrder[]obbligatorio

  The items of this page.

  Campi interni (20)

  • objectstringobbligatorio

    Always order.

    Valori:"order"

  • idstring (uuid)obbligatorio

    The order.

  • codestringobbligatorio

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

  • external_idstringobbligatoriopuò essere null

    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.

  • typestringobbligatorio

    How the guest gets the order.

    Valori:"pickup""delivery""dine_in"

  • sourcestringobbligatorio

    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).

    Valori:"storefront""table""app"

  • statusstringobbligatorio

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

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

  • created_atstring (date-time)obbligatorio

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

  • updated_atstring (date-time)obbligatorio

    Last change. ISO 8601 in UTC (Z).

  • acknowledged_atstring (date-time)obbligatoriopuò essere null

    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)obbligatoriopuò essere null

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

  • currencystringobbligatorio

    ISO 4217, e.g. EUR.

  • amountsobjectobbligatorio

    The amounts of the order, in cents.

    Campi interni (6)

    • subtotalintegerobbligatorio

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

    • delivery_feeintegerobbligatorio

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

    • service_feeintegerobbligatorio

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

    • discountintegerobbligatorio

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

    • tipintegerobbligatorio

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

    • totalintegerobbligatorio

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

  • taxobjectobbligatorio

    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.

    Campi interni (2)

    • includedbooleanobbligatorio

      Always true: prices include VAT.

      Valori:true

    • linesTaxLine[]obbligatorio

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

      Campi interni (4)

      • rate_bpsintegerobbligatoriopuò essere null

        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.

      • grossintegerobbligatorio

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

      • netintegerobbligatoriopuò essere null

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

      • taxintegerobbligatoriopuò essere null

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

  • paymentobjectobbligatorio

    How and whether it is paid.

    Campi interni (3)

    • methodstringobbligatorio

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

      Valori:"online""on_site"

    • statusstringobbligatorio

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

      Valori:"paid""open"

    • paid_atstring (date-time)obbligatoriopuò essere null

      When it was paid; null while open.

  • customerobjectobbligatoriopuò essere null

    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.

    Campi interni (2)

    • namestringobbligatoriopuò essere null

      The guest's name.

    • phonestringobbligatoriopuò essere null

      Phone for questions; null for dine-in.

  • deliveryobjectobbligatoriopuò essere null

    The delivery address; null unless type is delivery.

    Campi interni (3)

    • addressstringobbligatoriopuò essere null

      Street and number.

    • postal_codestringobbligatoriopuò essere null

      Postal code.

    • citystringobbligatoriopuò essere null

      City.

  • tableobjectobbligatoriopuò essere null

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

    Campi interni (2)

    • idstring (uuid)obbligatorio

      The table (GET /tables).

    • labelstringobbligatoriopuò essere null

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

  • notestringobbligatoriopuò essere null

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

  • itemsOrderItem[]obbligatorio

    The lines.

    Campi interni (8)

    • idstring (uuid)obbligatorio

      The line.

    • product_idstring (uuid)obbligatoriopuò essere null

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

    • namestringobbligatorio

      Name at the time of ordering.

    • quantityintegerobbligatorio

      How many.

      min 1

    • unit_priceintegerobbligatorio

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

    • line_totalintegerobbligatorio

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

    • tax_rate_bpsintegerobbligatoriopuò essere null

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

    • optionsobject[]obbligatorio

      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.

      Campi interni (5)

      • idstring (uuid)obbligatoriopuò essere null

        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.

      • namestringobbligatorio

        Name of the option.

      • price_deltaintegerobbligatorio

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

      • group_idstring (uuid)obbligatoriopuò essere null

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

      • group_namestringobbligatoriopuò essere null

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

• has_morebooleanobbligatorio

  Whether another page follows.

• next_cursorstringobbligatoriopuò essere null

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

Errori

• 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.

Tutti i codici di errore

Retrieve an order#

get/orders/{id}

Permesso:

orders:read

Piano:

tutti i piani

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.

Parametri

Risposta200

OK

• objectstringobbligatorio

  Always order.

  Valori:"order"

• idstring (uuid)obbligatorio

  The order.

• codestringobbligatorio

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

• external_idstringobbligatoriopuò essere null

  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.

• typestringobbligatorio

  How the guest gets the order.

  Valori:"pickup""delivery""dine_in"

• sourcestringobbligatorio

  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).

  Valori:"storefront""table""app"

• statusstringobbligatorio

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

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

• created_atstring (date-time)obbligatorio

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

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)obbligatoriopuò essere null

  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)obbligatoriopuò essere null

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

• currencystringobbligatorio

  ISO 4217, e.g. EUR.

• amountsobjectobbligatorio

  The amounts of the order, in cents.

  Campi interni (6)

  • subtotalintegerobbligatorio

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

  • delivery_feeintegerobbligatorio

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

  • service_feeintegerobbligatorio

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

  • discountintegerobbligatorio

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

  • tipintegerobbligatorio

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

  • totalintegerobbligatorio

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

• taxobjectobbligatorio

  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.

  Campi interni (2)

  • includedbooleanobbligatorio

    Always true: prices include VAT.

    Valori:true

  • linesTaxLine[]obbligatorio

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

    Campi interni (4)

    • rate_bpsintegerobbligatoriopuò essere null

      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.

    • grossintegerobbligatorio

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

    • netintegerobbligatoriopuò essere null

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

    • taxintegerobbligatoriopuò essere null

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

• paymentobjectobbligatorio

  How and whether it is paid.

  Campi interni (3)

  • methodstringobbligatorio

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

    Valori:"online""on_site"

  • statusstringobbligatorio

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

    Valori:"paid""open"

  • paid_atstring (date-time)obbligatoriopuò essere null

    When it was paid; null while open.

• customerobjectobbligatoriopuò essere null

  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.

  Campi interni (2)

  • namestringobbligatoriopuò essere null

    The guest's name.

  • phonestringobbligatoriopuò essere null

    Phone for questions; null for dine-in.

• deliveryobjectobbligatoriopuò essere null

  The delivery address; null unless type is delivery.

  Campi interni (3)

  • addressstringobbligatoriopuò essere null

    Street and number.

  • postal_codestringobbligatoriopuò essere null

    Postal code.

  • citystringobbligatoriopuò essere null

    City.

• tableobjectobbligatoriopuò essere null

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

  Campi interni (2)

  • idstring (uuid)obbligatorio

    The table (GET /tables).

  • labelstringobbligatoriopuò essere null

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

• notestringobbligatoriopuò essere null

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

• itemsOrderItem[]obbligatorio

  The lines.

  Campi interni (8)

  • idstring (uuid)obbligatorio

    The line.

  • product_idstring (uuid)obbligatoriopuò essere null

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

  • namestringobbligatorio

    Name at the time of ordering.

  • quantityintegerobbligatorio

    How many.

    min 1

  • unit_priceintegerobbligatorio

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

  • line_totalintegerobbligatorio

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

  • tax_rate_bpsintegerobbligatoriopuò essere null

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

  • optionsobject[]obbligatorio

    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.

    Campi interni (5)

    • idstring (uuid)obbligatoriopuò essere null

      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.

    • namestringobbligatorio

      Name of the option.

    • price_deltaintegerobbligatorio

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

    • group_idstring (uuid)obbligatoriopuò essere null

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

    • group_namestringobbligatoriopuò essere null

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

Errori

• 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.

Tutti i codici di errore

Accept an order#

post/orders/{id}/accept

Permesso:

orders:write

Piano:

tutti i piani

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.

Parametri

Risposta200

The order after the change.

• objectstringobbligatorio

  Always order.

  Valori:"order"

• idstring (uuid)obbligatorio

  The order.

• codestringobbligatorio

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

• external_idstringobbligatoriopuò essere null

  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.

• typestringobbligatorio

  How the guest gets the order.

  Valori:"pickup""delivery""dine_in"

• sourcestringobbligatorio

  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).

  Valori:"storefront""table""app"

• statusstringobbligatorio

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

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

• created_atstring (date-time)obbligatorio

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

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)obbligatoriopuò essere null

  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)obbligatoriopuò essere null

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

• currencystringobbligatorio

  ISO 4217, e.g. EUR.

• amountsobjectobbligatorio

  The amounts of the order, in cents.

  Campi interni (6)

  • subtotalintegerobbligatorio

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

  • delivery_feeintegerobbligatorio

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

  • service_feeintegerobbligatorio

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

  • discountintegerobbligatorio

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

  • tipintegerobbligatorio

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

  • totalintegerobbligatorio

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

• taxobjectobbligatorio

  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.

  Campi interni (2)

  • includedbooleanobbligatorio

    Always true: prices include VAT.

    Valori:true

  • linesTaxLine[]obbligatorio

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

    Campi interni (4)

    • rate_bpsintegerobbligatoriopuò essere null

      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.

    • grossintegerobbligatorio

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

    • netintegerobbligatoriopuò essere null

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

    • taxintegerobbligatoriopuò essere null

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

• paymentobjectobbligatorio

  How and whether it is paid.

  Campi interni (3)

  • methodstringobbligatorio

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

    Valori:"online""on_site"

  • statusstringobbligatorio

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

    Valori:"paid""open"

  • paid_atstring (date-time)obbligatoriopuò essere null

    When it was paid; null while open.

• customerobjectobbligatoriopuò essere null

  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.

  Campi interni (2)

  • namestringobbligatoriopuò essere null

    The guest's name.

  • phonestringobbligatoriopuò essere null

    Phone for questions; null for dine-in.

• deliveryobjectobbligatoriopuò essere null

  The delivery address; null unless type is delivery.

  Campi interni (3)

  • addressstringobbligatoriopuò essere null

    Street and number.

  • postal_codestringobbligatoriopuò essere null

    Postal code.

  • citystringobbligatoriopuò essere null

    City.

• tableobjectobbligatoriopuò essere null

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

  Campi interni (2)

  • idstring (uuid)obbligatorio

    The table (GET /tables).

  • labelstringobbligatoriopuò essere null

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

• notestringobbligatoriopuò essere null

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

• itemsOrderItem[]obbligatorio

  The lines.

  Campi interni (8)

  • idstring (uuid)obbligatorio

    The line.

  • product_idstring (uuid)obbligatoriopuò essere null

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

  • namestringobbligatorio

    Name at the time of ordering.

  • quantityintegerobbligatorio

    How many.

    min 1

  • unit_priceintegerobbligatorio

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

  • line_totalintegerobbligatorio

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

  • tax_rate_bpsintegerobbligatoriopuò essere null

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

  • optionsobject[]obbligatorio

    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.

    Campi interni (5)

    • idstring (uuid)obbligatoriopuò essere null

      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.

    • namestringobbligatorio

      Name of the option.

    • price_deltaintegerobbligatorio

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

    • group_idstring (uuid)obbligatoriopuò essere null

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

    • group_namestringobbligatoriopuò essere null

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

Errori

• 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.

Tutti i codici di errore

Reject an order#

post/orders/{id}/reject

Permesso:

orders:write

Piano:

tutti i piani

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.

Parametri

Corpoapplication/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

Risposta200

The order after the change.

• objectstringobbligatorio

  Always order.

  Valori:"order"

• idstring (uuid)obbligatorio

  The order.

• codestringobbligatorio

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

• external_idstringobbligatoriopuò essere null

  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.

• typestringobbligatorio

  How the guest gets the order.

  Valori:"pickup""delivery""dine_in"

• sourcestringobbligatorio

  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).

  Valori:"storefront""table""app"

• statusstringobbligatorio

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

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

• created_atstring (date-time)obbligatorio

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

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)obbligatoriopuò essere null

  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)obbligatoriopuò essere null

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

• currencystringobbligatorio

  ISO 4217, e.g. EUR.

• amountsobjectobbligatorio

  The amounts of the order, in cents.

  Campi interni (6)

  • subtotalintegerobbligatorio

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

  • delivery_feeintegerobbligatorio

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

  • service_feeintegerobbligatorio

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

  • discountintegerobbligatorio

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

  • tipintegerobbligatorio

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

  • totalintegerobbligatorio

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

• taxobjectobbligatorio

  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.

  Campi interni (2)

  • includedbooleanobbligatorio

    Always true: prices include VAT.

    Valori:true

  • linesTaxLine[]obbligatorio

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

    Campi interni (4)

    • rate_bpsintegerobbligatoriopuò essere null

      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.

    • grossintegerobbligatorio

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

    • netintegerobbligatoriopuò essere null

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

    • taxintegerobbligatoriopuò essere null

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

• paymentobjectobbligatorio

  How and whether it is paid.

  Campi interni (3)

  • methodstringobbligatorio

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

    Valori:"online""on_site"

  • statusstringobbligatorio

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

    Valori:"paid""open"

  • paid_atstring (date-time)obbligatoriopuò essere null

    When it was paid; null while open.

• customerobjectobbligatoriopuò essere null

  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.

  Campi interni (2)

  • namestringobbligatoriopuò essere null

    The guest's name.

  • phonestringobbligatoriopuò essere null

    Phone for questions; null for dine-in.

• deliveryobjectobbligatoriopuò essere null

  The delivery address; null unless type is delivery.

  Campi interni (3)

  • addressstringobbligatoriopuò essere null

    Street and number.

  • postal_codestringobbligatoriopuò essere null

    Postal code.

  • citystringobbligatoriopuò essere null

    City.

• tableobjectobbligatoriopuò essere null

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

  Campi interni (2)

  • idstring (uuid)obbligatorio

    The table (GET /tables).

  • labelstringobbligatoriopuò essere null

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

• notestringobbligatoriopuò essere null

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

• itemsOrderItem[]obbligatorio

  The lines.

  Campi interni (8)

  • idstring (uuid)obbligatorio

    The line.

  • product_idstring (uuid)obbligatoriopuò essere null

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

  • namestringobbligatorio

    Name at the time of ordering.

  • quantityintegerobbligatorio

    How many.

    min 1

  • unit_priceintegerobbligatorio

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

  • line_totalintegerobbligatorio

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

  • tax_rate_bpsintegerobbligatoriopuò essere null

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

  • optionsobject[]obbligatorio

    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.

    Campi interni (5)

    • idstring (uuid)obbligatoriopuò essere null

      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.

    • namestringobbligatorio

      Name of the option.

    • price_deltaintegerobbligatorio

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

    • group_idstring (uuid)obbligatoriopuò essere null

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

    • group_namestringobbligatoriopuò essere null

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

Errori

• 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.

Tutti i codici di errore

Cancel an order#

post/orders/{id}/cancel

Permesso:

orders:write

Piano:

tutti i piani

Idempotency-Key

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

Parametri

Corpoapplication/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

Risposta200

The order after the change.

• objectstringobbligatorio

  Always order.

  Valori:"order"

• idstring (uuid)obbligatorio

  The order.

• codestringobbligatorio

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

• external_idstringobbligatoriopuò essere null

  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.

• typestringobbligatorio

  How the guest gets the order.

  Valori:"pickup""delivery""dine_in"

• sourcestringobbligatorio

  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).

  Valori:"storefront""table""app"

• statusstringobbligatorio

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

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

• created_atstring (date-time)obbligatorio

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

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)obbligatoriopuò essere null

  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)obbligatoriopuò essere null

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

• currencystringobbligatorio

  ISO 4217, e.g. EUR.

• amountsobjectobbligatorio

  The amounts of the order, in cents.

  Campi interni (6)

  • subtotalintegerobbligatorio

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

  • delivery_feeintegerobbligatorio

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

  • service_feeintegerobbligatorio

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

  • discountintegerobbligatorio

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

  • tipintegerobbligatorio

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

  • totalintegerobbligatorio

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

• taxobjectobbligatorio

  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.

  Campi interni (2)

  • includedbooleanobbligatorio

    Always true: prices include VAT.

    Valori:true

  • linesTaxLine[]obbligatorio

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

    Campi interni (4)

    • rate_bpsintegerobbligatoriopuò essere null

      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.

    • grossintegerobbligatorio

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

    • netintegerobbligatoriopuò essere null

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

    • taxintegerobbligatoriopuò essere null

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

• paymentobjectobbligatorio

  How and whether it is paid.

  Campi interni (3)

  • methodstringobbligatorio

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

    Valori:"online""on_site"

  • statusstringobbligatorio

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

    Valori:"paid""open"

  • paid_atstring (date-time)obbligatoriopuò essere null

    When it was paid; null while open.

• customerobjectobbligatoriopuò essere null

  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.

  Campi interni (2)

  • namestringobbligatoriopuò essere null

    The guest's name.

  • phonestringobbligatoriopuò essere null

    Phone for questions; null for dine-in.

• deliveryobjectobbligatoriopuò essere null

  The delivery address; null unless type is delivery.

  Campi interni (3)

  • addressstringobbligatoriopuò essere null

    Street and number.

  • postal_codestringobbligatoriopuò essere null

    Postal code.

  • citystringobbligatoriopuò essere null

    City.

• tableobjectobbligatoriopuò essere null

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

  Campi interni (2)

  • idstring (uuid)obbligatorio

    The table (GET /tables).

  • labelstringobbligatoriopuò essere null

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

• notestringobbligatoriopuò essere null

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

• itemsOrderItem[]obbligatorio

  The lines.

  Campi interni (8)

  • idstring (uuid)obbligatorio

    The line.

  • product_idstring (uuid)obbligatoriopuò essere null

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

  • namestringobbligatorio

    Name at the time of ordering.

  • quantityintegerobbligatorio

    How many.

    min 1

  • unit_priceintegerobbligatorio

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

  • line_totalintegerobbligatorio

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

  • tax_rate_bpsintegerobbligatoriopuò essere null

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

  • optionsobject[]obbligatorio

    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.

    Campi interni (5)

    • idstring (uuid)obbligatoriopuò essere null

      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.

    • namestringobbligatorio

      Name of the option.

    • price_deltaintegerobbligatorio

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

    • group_idstring (uuid)obbligatoriopuò essere null

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

    • group_namestringobbligatoriopuò essere null

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

Errori

• 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.

Tutti i codici di errore

Advance an order#

post/orders/{id}/status

Permesso:

orders:write

Piano:

tutti i piani

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.

Parametri

Corpoapplication/json

• statusstringobbligatorio

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

  Valori:"confirmed""preparing""ready""completed"

Risposta200

The order after the change.

• objectstringobbligatorio

  Always order.

  Valori:"order"

• idstring (uuid)obbligatorio

  The order.

• codestringobbligatorio

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

• external_idstringobbligatoriopuò essere null

  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.

• typestringobbligatorio

  How the guest gets the order.

  Valori:"pickup""delivery""dine_in"

• sourcestringobbligatorio

  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).

  Valori:"storefront""table""app"

• statusstringobbligatorio

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

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

• created_atstring (date-time)obbligatorio

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

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)obbligatoriopuò essere null

  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)obbligatoriopuò essere null

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

• currencystringobbligatorio

  ISO 4217, e.g. EUR.

• amountsobjectobbligatorio

  The amounts of the order, in cents.

  Campi interni (6)

  • subtotalintegerobbligatorio

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

  • delivery_feeintegerobbligatorio

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

  • service_feeintegerobbligatorio

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

  • discountintegerobbligatorio

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

  • tipintegerobbligatorio

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

  • totalintegerobbligatorio

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

• taxobjectobbligatorio

  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.

  Campi interni (2)

  • includedbooleanobbligatorio

    Always true: prices include VAT.

    Valori:true

  • linesTaxLine[]obbligatorio

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

    Campi interni (4)

    • rate_bpsintegerobbligatoriopuò essere null

      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.

    • grossintegerobbligatorio

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

    • netintegerobbligatoriopuò essere null

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

    • taxintegerobbligatoriopuò essere null

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

• paymentobjectobbligatorio

  How and whether it is paid.

  Campi interni (3)

  • methodstringobbligatorio

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

    Valori:"online""on_site"

  • statusstringobbligatorio

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

    Valori:"paid""open"

  • paid_atstring (date-time)obbligatoriopuò essere null

    When it was paid; null while open.

• customerobjectobbligatoriopuò essere null

  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.

  Campi interni (2)

  • namestringobbligatoriopuò essere null

    The guest's name.

  • phonestringobbligatoriopuò essere null

    Phone for questions; null for dine-in.

• deliveryobjectobbligatoriopuò essere null

  The delivery address; null unless type is delivery.

  Campi interni (3)

  • addressstringobbligatoriopuò essere null

    Street and number.

  • postal_codestringobbligatoriopuò essere null

    Postal code.

  • citystringobbligatoriopuò essere null

    City.

• tableobjectobbligatoriopuò essere null

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

  Campi interni (2)

  • idstring (uuid)obbligatorio

    The table (GET /tables).

  • labelstringobbligatoriopuò essere null

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

• notestringobbligatoriopuò essere null

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

• itemsOrderItem[]obbligatorio

  The lines.

  Campi interni (8)

  • idstring (uuid)obbligatorio

    The line.

  • product_idstring (uuid)obbligatoriopuò essere null

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

  • namestringobbligatorio

    Name at the time of ordering.

  • quantityintegerobbligatorio

    How many.

    min 1

  • unit_priceintegerobbligatorio

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

  • line_totalintegerobbligatorio

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

  • tax_rate_bpsintegerobbligatoriopuò essere null

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

  • optionsobject[]obbligatorio

    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.

    Campi interni (5)

    • idstring (uuid)obbligatoriopuò essere null

      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.

    • namestringobbligatorio

      Name of the option.

    • price_deltaintegerobbligatorio

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

    • group_idstring (uuid)obbligatoriopuò essere null

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

    • group_namestringobbligatoriopuò essere null

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

Errori

• 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.

Tutti i codici di errore

Acknowledge an order#

post/orders/{id}/acknowledge

Permesso:

orders:write

Piano:

tutti i piani

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.

Parametri

Corpoapplication/json

• external_idstringpuò essere null

  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

Risposta200

The order with your external_id and acknowledged_at.

• objectstringobbligatorio

  Always order.

  Valori:"order"

• idstring (uuid)obbligatorio

  The order.

• codestringobbligatorio

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

• external_idstringobbligatoriopuò essere null

  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.

• typestringobbligatorio

  How the guest gets the order.

  Valori:"pickup""delivery""dine_in"

• sourcestringobbligatorio

  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).

  Valori:"storefront""table""app"

• statusstringobbligatorio

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

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

• created_atstring (date-time)obbligatorio

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

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• acknowledged_atstring (date-time)obbligatoriopuò essere null

  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)obbligatoriopuò essere null

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

• currencystringobbligatorio

  ISO 4217, e.g. EUR.

• amountsobjectobbligatorio

  The amounts of the order, in cents.

  Campi interni (6)

  • subtotalintegerobbligatorio

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

  • delivery_feeintegerobbligatorio

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

  • service_feeintegerobbligatorio

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

  • discountintegerobbligatorio

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

  • tipintegerobbligatorio

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

  • totalintegerobbligatorio

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

• taxobjectobbligatorio

  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.

  Campi interni (2)

  • includedbooleanobbligatorio

    Always true: prices include VAT.

    Valori:true

  • linesTaxLine[]obbligatorio

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

    Campi interni (4)

    • rate_bpsintegerobbligatoriopuò essere null

      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.

    • grossintegerobbligatorio

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

    • netintegerobbligatoriopuò essere null

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

    • taxintegerobbligatoriopuò essere null

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

• paymentobjectobbligatorio

  How and whether it is paid.

  Campi interni (3)

  • methodstringobbligatorio

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

    Valori:"online""on_site"

  • statusstringobbligatorio

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

    Valori:"paid""open"

  • paid_atstring (date-time)obbligatoriopuò essere null

    When it was paid; null while open.

• customerobjectobbligatoriopuò essere null

  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.

  Campi interni (2)

  • namestringobbligatoriopuò essere null

    The guest's name.

  • phonestringobbligatoriopuò essere null

    Phone for questions; null for dine-in.

• deliveryobjectobbligatoriopuò essere null

  The delivery address; null unless type is delivery.

  Campi interni (3)

  • addressstringobbligatoriopuò essere null

    Street and number.

  • postal_codestringobbligatoriopuò essere null

    Postal code.

  • citystringobbligatoriopuò essere null

    City.

• tableobjectobbligatoriopuò essere null

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

  Campi interni (2)

  • idstring (uuid)obbligatorio

    The table (GET /tables).

  • labelstringobbligatoriopuò essere null

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

• notestringobbligatoriopuò essere null

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

• itemsOrderItem[]obbligatorio

  The lines.

  Campi interni (8)

  • idstring (uuid)obbligatorio

    The line.

  • product_idstring (uuid)obbligatoriopuò essere null

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

  • namestringobbligatorio

    Name at the time of ordering.

  • quantityintegerobbligatorio

    How many.

    min 1

  • unit_priceintegerobbligatorio

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

  • line_totalintegerobbligatorio

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

  • tax_rate_bpsintegerobbligatoriopuò essere null

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

  • optionsobject[]obbligatorio

    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.

    Campi interni (5)

    • idstring (uuid)obbligatoriopuò essere null

      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.

    • namestringobbligatorio

      Name of the option.

    • price_deltaintegerobbligatorio

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

    • group_idstring (uuid)obbligatoriopuò essere null

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

    • group_namestringobbligatoriopuò essere null

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

Errori

• 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.

Tutti i codici di errore