Reservations

Overview#

Reservations come with the Pro plan and up; in a restaurant on Starter the routes answer 403 plan_required. Reading needs reservations:read, creating, changing and setting the status reservations:write.

A reservation carries start, duration, party size, tables, source (guest, staff or api), status and, from the guest, only the name. A phone number and e-mail address sent when creating it stay in Flavoso.

{
  "object": "reservation",
  "id": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "code": "R7K2Q9",
  "status": "confirmed",
  "starts_at": "2026-10-10T17:30:00.000Z",
  "duration_minutes": 120,
  "party_size": 4,
  "table_ids": [
    "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
  ],
  "source": "staff",
  "guest_name": "Alex Example",
  "note": "Window seat if possible",
  "created_at": "2026-10-04T12:00:00.000Z",
  "updated_at": "2026-10-04T12:00:00.000Z"
}

The statuses#

Confirming, declining and cancelling send the guest an e-mail if they left an address; on a cancellation the team gets a notification. seated, done, no_show and every step back are silent. Any other change, or one outside its time, answers 409 invalid_transition and names the statuses possible right now. If the reservation is already at the target, it comes back unchanged.

Free times#

GET /reservations/availability?date=YYYY-MM-DD&party_size=N returns a day's times with available per time, plus the duration (duration_minutes) and the time zone. The grid follows the opening hours and special days as on the booking page; apart from that, the rules of a booking by the team apply: all tables count, including those not bookable online, there is no lead time and no horizon, and online reservations do not need to be switched on. Past times are in the list but never free.

curl "https://api.flavoso.com/v1/reservations/availability?date=2026-10-10&party_size=4" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Creating#

POST /reservations creates a reservation, by the same rules as above. starts_at must be exactly one of the times from GET /reservations/availability; another time, a past one or one at which no suitable table is free gets 409 slot_unavailable.

curl -X POST https://api.flavoso.com/v1/reservations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-48211" \
  -d '{
  "starts_at": "2026-10-10T17:30:00Z",
  "party_size": 4,
  "guest_name": "Alex Example",
  "guest_phone": "+49 151 00000000",
  "note": "Window seat if possible",
  "status": "confirmed",
  "notify_guest": false
}'

Changing and setting the status#

PATCH /reservations/{id} changes starts_at, party_size, duration_minutes, table_ids and note. The new time does not have to be on the grid, and without tables PATCH checks no seats; if the reservation then holds a table that is already taken at that time, Flavoso answers 409 slot_unavailable (table_ids: [] releases the tables). A cancelled or declined reservation cannot be changed any more, and one that is seated, left or a no-show can only be moved to a time that has already begun (otherwise 409 invalid_transition). Everything is checked first and saved in one step: a 409 means nothing was changed and no e-mail went out. With notify_guest (default true) the guest gets an e-mail when the time or party size of a pending or confirmed reservation changes. The status is set with POST /reservations/{id}/status.

# Two more people and half an hour later
curl -X PATCH https://api.flavoso.com/v1/reservations/RESERVATION_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"party_size": 6, "starts_at": "2026-10-10T18:00:00Z"}'

# The party has arrived
curl -X POST https://api.flavoso.com/v1/reservations/RESERVATION_ID/status \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "seated"}'

A day's reservation book#

With starts_from and starts_until, GET /reservations returns the reservations of a period, ascending by start. For an evening in the restaurant, take midnight to midnight in its time zone, converted to UTC. To sync with your system, use updated_since as for orders.

# Saturday's book in Berlin (UTC+2): local midnight to local midnight, sorted by start
curl "https://api.flavoso.com/v1/reservations?starts_from=2026-10-09T22:00:00Z&starts_until=2026-10-10T22:00:00Z&status=pending,confirmed" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Tables and areas#

GET /tables and GET /areas (with store:read or reservations:read) return the tables with seats, area, whether they can be booked online and the minimum party size, and the areas. That is how you map table_ids. The key in a table's QR code is never included.

curl https://api.flavoso.com/v1/tables -H "Authorization: Bearer $ACCESS_TOKEN"
curl https://api.flavoso.com/v1/areas -H "Authorization: Bearer $ACCESS_TOKEN"

Events#

reservation.created arrives for every new reservation, reservation.updated for every change of status, time, party size, duration, tables or note, with changed. When the restaurant deletes a reservation, a final reservation.updated arrives with changed: ["deleted"] and deleted_at; after that it answers 404.