Réservations

List reservations#

get/reservations

Droit:

reservations:read

Offre:

à partir de 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).

Paramètres

Réponse200

OK

• objectstringobligatoire

  Always list.

  Valeurs:"list"

• dataReservation[]obligatoire

  The items of this page.

  Champs contenus (14)

  • objectstringobligatoire

    Always reservation.

    Valeurs:"reservation"

  • idstring (uuid)obligatoire

    The reservation.

  • codestringobligatoire

    Short code the guest sees.

  • statusstringobligatoire

    pending is a request the restaurant still has to confirm.

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

  • starts_atstring (date-time)obligatoire

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

  • duration_minutesintegerobligatoire

    How long the table is held.

  • party_sizeintegerobligatoire

    Number of guests.

  • table_idsstring (uuid)[]obligatoire

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

  • sourcestringobligatoire

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

    Valeurs:"guest""staff""api"

  • guest_namestringobligatoirepeut être null

    The guest's name.

  • notestringobligatoirepeut être null

    The guest's wish.

  • created_atstring (date-time)obligatoire

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

  • updated_atstring (date-time)obligatoire

    Last change. ISO 8601 in UTC (Z).

  • deleted_atstring (date-time)obligatoirepeut être null

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

• has_morebooleanobligatoire

  Whether another page follows.

• next_cursorstringobligatoirepeut être null

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

Erreurs

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

Tous les codes d'erreur

Create a reservation#

post/reservations

Droit:

reservations:write

Offre:

à partir de 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.

Paramètres

Corpsapplication/json

• starts_atstring (date-time)obligatoire

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

• party_sizeintegerobligatoire

  Number of guests.

  1 to 200

• guest_namestringobligatoire

  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.

  Valeurs:"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.

  Valeurs:"confirmed""pending"

  default "confirmed"

• notify_guestboolean

  E-mail the guest (needs guest_email).

  default true

Réponse201

The reservation.

• objectstringobligatoire

  Always reservation.

  Valeurs:"reservation"

• idstring (uuid)obligatoire

  The reservation.

• codestringobligatoire

  Short code the guest sees.

• statusstringobligatoire

  pending is a request the restaurant still has to confirm.

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

• starts_atstring (date-time)obligatoire

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

• duration_minutesintegerobligatoire

  How long the table is held.

• party_sizeintegerobligatoire

  Number of guests.

• table_idsstring (uuid)[]obligatoire

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

• sourcestringobligatoire

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

  Valeurs:"guest""staff""api"

• guest_namestringobligatoirepeut être null

  The guest's name.

• notestringobligatoirepeut être null

  The guest's wish.

• created_atstring (date-time)obligatoire

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

• updated_atstring (date-time)obligatoire

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obligatoirepeut être null

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

Erreurs

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

Tous les codes d'erreur

Free reservation times of a day#

get/reservations/availability

Droit:

reservations:read

Offre:

à partir de 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).

Paramètres

Réponse200

OK

• objectstringobligatoire

  Always availability.

  Valeurs:"availability"

• datestring (date)obligatoire

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

• party_sizeintegerobligatoire

  The party size asked for.

• duration_minutesintegerobligatoire

  How long a table is held for this party size.

• timezonestringobligatoire

  The restaurant's time zone.

• slotsobject[]obligatoire

  The times of that day, ascending.

  Champs contenus (2)

  • starts_atstring (date-time)obligatoire

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

  • availablebooleanobligatoire

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

Erreurs

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

Tous les codes d'erreur

Retrieve a reservation#

get/reservations/{id}

Droit:

reservations:read

Offre:

à partir de Pro

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

Paramètres

Réponse200

OK

• objectstringobligatoire

  Always reservation.

  Valeurs:"reservation"

• idstring (uuid)obligatoire

  The reservation.

• codestringobligatoire

  Short code the guest sees.

• statusstringobligatoire

  pending is a request the restaurant still has to confirm.

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

• starts_atstring (date-time)obligatoire

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

• duration_minutesintegerobligatoire

  How long the table is held.

• party_sizeintegerobligatoire

  Number of guests.

• table_idsstring (uuid)[]obligatoire

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

• sourcestringobligatoire

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

  Valeurs:"guest""staff""api"

• guest_namestringobligatoirepeut être null

  The guest's name.

• notestringobligatoirepeut être null

  The guest's wish.

• created_atstring (date-time)obligatoire

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

• updated_atstring (date-time)obligatoire

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obligatoirepeut être null

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

Erreurs

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

Tous les codes d'erreur

Change a reservation#

patch/reservations/{id}

Droit:

reservations:write

Offre:

à partir de 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.

Paramètres

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

• notestringpeut être 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

Réponse200

The reservation after the change.

• objectstringobligatoire

  Always reservation.

  Valeurs:"reservation"

• idstring (uuid)obligatoire

  The reservation.

• codestringobligatoire

  Short code the guest sees.

• statusstringobligatoire

  pending is a request the restaurant still has to confirm.

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

• starts_atstring (date-time)obligatoire

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

• duration_minutesintegerobligatoire

  How long the table is held.

• party_sizeintegerobligatoire

  Number of guests.

• table_idsstring (uuid)[]obligatoire

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

• sourcestringobligatoire

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

  Valeurs:"guest""staff""api"

• guest_namestringobligatoirepeut être null

  The guest's name.

• notestringobligatoirepeut être null

  The guest's wish.

• created_atstring (date-time)obligatoire

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

• updated_atstring (date-time)obligatoire

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obligatoirepeut être null

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

Erreurs

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

Tous les codes d'erreur

Set a reservation's status#

post/reservations/{id}/status

Droit:

reservations:write

Offre:

à partir de 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.

Paramètres

Corpsapplication/json

• statusstringobligatoire

  The status to move to.

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

Réponse200

OK

• objectstringobligatoire

  Always reservation.

  Valeurs:"reservation"

• idstring (uuid)obligatoire

  The reservation.

• codestringobligatoire

  Short code the guest sees.

• statusstringobligatoire

  pending is a request the restaurant still has to confirm.

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

• starts_atstring (date-time)obligatoire

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

• duration_minutesintegerobligatoire

  How long the table is held.

• party_sizeintegerobligatoire

  Number of guests.

• table_idsstring (uuid)[]obligatoire

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

• sourcestringobligatoire

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

  Valeurs:"guest""staff""api"

• guest_namestringobligatoirepeut être null

  The guest's name.

• notestringobligatoirepeut être null

  The guest's wish.

• created_atstring (date-time)obligatoire

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

• updated_atstring (date-time)obligatoire

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obligatoirepeut être null

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

Erreurs

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

Tous les codes d'erreur