Prenotazioni

List reservations#

get/reservations

Permesso:

reservations:read

Piano:

da Pro

Same paging and polling rules as GET /orders: newest change first, or ascending with updated_since (poll with a minute of overlap and deduplicate by id + updated_at).

With starts_from and/or starts_until (tonight, this week) the list is sorted by starts_at ascending instead. Deleted reservations are never listed. Pro plan and up (plan_required otherwise).

Parametri

Risposta200

OK

• objectstringobbligatorio

  Always list.

  Valori:"list"

• dataReservation[]obbligatorio

  The items of this page.

  Campi interni (14)

  • objectstringobbligatorio

    Always reservation.

    Valori:"reservation"

  • idstring (uuid)obbligatorio

    The reservation.

  • codestringobbligatorio

    Short code the guest sees.

  • statusstringobbligatorio

    pending is a request the restaurant still has to confirm.

    Valori:"pending""confirmed""declined""seated""done""cancelled""no_show"

  • starts_atstring (date-time)obbligatorio

    Start of the reservation. ISO 8601 in UTC (Z).

  • duration_minutesintegerobbligatorio

    How long the table is held.

  • party_sizeintegerobbligatorio

    Number of guests.

  • table_idsstring (uuid)[]obbligatorio

    Assigned tables (GET /tables); empty when none is assigned yet.

  • sourcestringobbligatorio

    Booked online by the guest, by the restaurant's staff, or through this API.

    Valori:"guest""staff""api"

  • guest_namestringobbligatoriopuò essere null

    The guest's name.

  • notestringobbligatoriopuò essere null

    The guest's wish.

  • created_atstring (date-time)obbligatorio

    When it was made. ISO 8601 in UTC (Z).

  • updated_atstring (date-time)obbligatorio

    Last change. ISO 8601 in UTC (Z).

  • deleted_atstring (date-time)obbligatoriopuò essere null

    Only set in the event that reports a deletion; deleted reservations are not returned otherwise.

• 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

Create a reservation#

post/reservations

Permesso:

reservations:write

Piano:

da Pro

Idempotency-Key

Books a table for the restaurant, like the restaurant's own staff would: all tables count (also those not bookable online), there is no lead time and no booking horizon, and online reservations need not be switched on. Unlike staff, your app cannot overbook: starts_at must be one of the times GET /reservations/availability offers for that day, and a table must be free for the party (or the table_ids you send). Otherwise 409 slot_unavailable.

status is confirmed (default) or pending (the restaurant confirms). With guest_email the guest receives the confirmation (or, for pending, the request) e-mail in guest_locale (default: the restaurant's language), unless notify_guest is false. The restaurant's staff is not notified, as with a booking they make themselves. Produces reservation.created; source is api.

Parametri

Corpoapplication/json

• starts_atstring (date-time)obbligatorio

  Start, ISO 8601 with time zone; one of the times GET /reservations/availability offers.

• party_sizeintegerobbligatorio

  Number of guests.

  1 to 200

• guest_namestringobbligatorio

  The guest's name.

  max 120 chars

• guest_phonestring

  Phone (at least six digits). Kept for the restaurant, never returned.

  max 40 chars

• guest_emailstring (email)

  E-mail for the confirmation. Kept for the restaurant, never returned.

  max 200 chars

• guest_localestring

  Language of the guest's e-mails. Default: the restaurant's language.

  Valori:"de""en""fr""es""it"

• notestring

  The guest's wish; part of the confirmation.

  max 500 chars

• duration_minutesinteger

  How long to hold the table. Default: the restaurant's duration for this party size.

  15 to 600

• table_idsstring (uuid)[]

  Assign these tables; they must be free and seat the party. Default: none (the restaurant assigns).

  max 10 items

• statusstring

  pending leaves the confirmation to the restaurant.

  Valori:"confirmed""pending"

  default "confirmed"

• notify_guestboolean

  E-mail the guest (needs guest_email).

  default true

Risposta201

The reservation.

• objectstringobbligatorio

  Always reservation.

  Valori:"reservation"

• idstring (uuid)obbligatorio

  The reservation.

• codestringobbligatorio

  Short code the guest sees.

• statusstringobbligatorio

  pending is a request the restaurant still has to confirm.

  Valori:"pending""confirmed""declined""seated""done""cancelled""no_show"

• starts_atstring (date-time)obbligatorio

  Start of the reservation. ISO 8601 in UTC (Z).

• duration_minutesintegerobbligatorio

  How long the table is held.

• party_sizeintegerobbligatorio

  Number of guests.

• table_idsstring (uuid)[]obbligatorio

  Assigned tables (GET /tables); empty when none is assigned yet.

• sourcestringobbligatorio

  Booked online by the guest, by the restaurant's staff, or through this API.

  Valori:"guest""staff""api"

• guest_namestringobbligatoriopuò essere null

  The guest's name.

• notestringobbligatoriopuò essere null

  The guest's wish.

• created_atstring (date-time)obbligatorio

  When it was made. ISO 8601 in UTC (Z).

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obbligatoriopuò essere null

  Only set in the event that reports a deletion; deleted reservations are not returned otherwise.

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

Free reservation times of a day#

get/reservations/availability

Permesso:

reservations:read

Piano:

da Pro

The times of one day for a party of this size, as the restaurant's staff sees them: from each opening in the configured interval up to the last seating, each available or not (a table is free for the party, past times never). Exactly these times are accepted by POST /reservations. Without a weekly schedule there are no times (special days with their own hours still have them).

Parametri

Risposta200

OK

• objectstringobbligatorio

  Always availability.

  Valori:"availability"

• datestring (date)obbligatorio

  The day. A date YYYY-MM-DD in the restaurant's time zone.

• party_sizeintegerobbligatorio

  The party size asked for.

• duration_minutesintegerobbligatorio

  How long a table is held for this party size.

• timezonestringobbligatorio

  The restaurant's time zone.

• slotsobject[]obbligatorio

  The times of that day, ascending.

  Campi interni (2)

  • starts_atstring (date-time)obbligatorio

    A bookable start time. ISO 8601 in UTC (Z).

  • availablebooleanobbligatorio

    A table is free for the party, and the time is not past.

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 a reservation#

get/reservations/{id}

Permesso:

reservations:read

Piano:

da Pro

One reservation. Deleted reservations answer 404. Pro plan and up.

Parametri

Risposta200

OK

• objectstringobbligatorio

  Always reservation.

  Valori:"reservation"

• idstring (uuid)obbligatorio

  The reservation.

• codestringobbligatorio

  Short code the guest sees.

• statusstringobbligatorio

  pending is a request the restaurant still has to confirm.

  Valori:"pending""confirmed""declined""seated""done""cancelled""no_show"

• starts_atstring (date-time)obbligatorio

  Start of the reservation. ISO 8601 in UTC (Z).

• duration_minutesintegerobbligatorio

  How long the table is held.

• party_sizeintegerobbligatorio

  Number of guests.

• table_idsstring (uuid)[]obbligatorio

  Assigned tables (GET /tables); empty when none is assigned yet.

• sourcestringobbligatorio

  Booked online by the guest, by the restaurant's staff, or through this API.

  Valori:"guest""staff""api"

• guest_namestringobbligatoriopuò essere null

  The guest's name.

• notestringobbligatoriopuò essere null

  The guest's wish.

• created_atstring (date-time)obbligatorio

  When it was made. ISO 8601 in UTC (Z).

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obbligatoriopuò essere null

  Only set in the event that reports a deletion; deleted reservations are not returned otherwise.

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

Change a reservation#

patch/reservations/{id}

Permesso:

reservations:write

Piano:

da Pro

Changes time, party size, duration, tables or the guest's note, with the rules of the restaurant's reservation board: cancelled and declined reservations cannot be changed, a seated, done or no-show reservation can only be corrected into the past (409 invalid_transition). Unlike a new booking there is no availability check, but a table must not end up taken twice: if the reservation's tables (kept or sent in table_ids) are held by another reservation at the new time, the answer is 409 slot_unavailable. Send table_ids: [] to release the tables.

All fields are checked first and then saved together in one step: a 4xx answer, including any 409, means nothing was changed and no e-mail was sent.

When time or party size change on a pending or confirmed reservation, the guest gets the change e-mail unless notify_guest is false. Produces reservation.updated. The status changes with POST /reservations/{id}/status.

Parametri

Corpoapplication/json

• starts_atstring (date-time)

  New start, ISO 8601 with time zone.

• party_sizeinteger

  New number of guests.

  1 to 200

• duration_minutesinteger

  New duration.

  15 to 600

• table_idsstring (uuid)[]

  Replace the assigned tables; [] releases them.

  max 10 items

• notestringpuò essere null

  The guest's wish; null removes it.

  max 500 chars

• notify_guestboolean

  E-mail the guest when time or party size change.

  default true

Risposta200

The reservation after the change.

• objectstringobbligatorio

  Always reservation.

  Valori:"reservation"

• idstring (uuid)obbligatorio

  The reservation.

• codestringobbligatorio

  Short code the guest sees.

• statusstringobbligatorio

  pending is a request the restaurant still has to confirm.

  Valori:"pending""confirmed""declined""seated""done""cancelled""no_show"

• starts_atstring (date-time)obbligatorio

  Start of the reservation. ISO 8601 in UTC (Z).

• duration_minutesintegerobbligatorio

  How long the table is held.

• party_sizeintegerobbligatorio

  Number of guests.

• table_idsstring (uuid)[]obbligatorio

  Assigned tables (GET /tables); empty when none is assigned yet.

• sourcestringobbligatorio

  Booked online by the guest, by the restaurant's staff, or through this API.

  Valori:"guest""staff""api"

• guest_namestringobbligatoriopuò essere null

  The guest's name.

• notestringobbligatoriopuò essere null

  The guest's wish.

• created_atstring (date-time)obbligatorio

  When it was made. ISO 8601 in UTC (Z).

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obbligatoriopuò essere null

  Only set in the event that reports a deletion; deleted reservations are not returned otherwise.

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

Set a reservation's status#

post/reservations/{id}/status

Permesso:

reservations:write

Piano:

da Pro

Idempotency-Key

The same transitions as in the dashboard, and only those: a request (pending) becomes confirmed or declined (cancelled on a request means declined); confirmed becomes seated (from an hour before the start), done or no_show (from the start) or cancelled; seated becomes done. declined and cancelled are final. Anything else answers 409 invalid_transition with the statuses that are possible now. confirmed, declined and cancelled e-mail the guest, cancelled also notifies the staff. seated, done and no_show are silent.

Parametri

Corpoapplication/json

• statusstringobbligatorio

  The status to move to.

  Valori:"confirmed""declined""seated""done""cancelled""no_show"

Risposta200

OK

• objectstringobbligatorio

  Always reservation.

  Valori:"reservation"

• idstring (uuid)obbligatorio

  The reservation.

• codestringobbligatorio

  Short code the guest sees.

• statusstringobbligatorio

  pending is a request the restaurant still has to confirm.

  Valori:"pending""confirmed""declined""seated""done""cancelled""no_show"

• starts_atstring (date-time)obbligatorio

  Start of the reservation. ISO 8601 in UTC (Z).

• duration_minutesintegerobbligatorio

  How long the table is held.

• party_sizeintegerobbligatorio

  Number of guests.

• table_idsstring (uuid)[]obbligatorio

  Assigned tables (GET /tables); empty when none is assigned yet.

• sourcestringobbligatorio

  Booked online by the guest, by the restaurant's staff, or through this API.

  Valori:"guest""staff""api"

• guest_namestringobbligatoriopuò essere null

  The guest's name.

• notestringobbligatoriopuò essere null

  The guest's wish.

• created_atstring (date-time)obbligatorio

  When it was made. ISO 8601 in UTC (Z).

• updated_atstring (date-time)obbligatorio

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obbligatoriopuò essere null

  Only set in the event that reports a deletion; deleted reservations are not returned otherwise.

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