Reservas

List reservations#

get/reservations

Permiso:

reservations:read

Plan:

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

Parámetros

Respuesta200

OK

• objectstringobligatorio

  Always list.

  Valores:"list"

• dataReservation[]obligatorio

  The items of this page.

  Campos anidados (14)

  • objectstringobligatorio

    Always reservation.

    Valores:"reservation"

  • idstring (uuid)obligatorio

    The reservation.

  • codestringobligatorio

    Short code the guest sees.

  • statusstringobligatorio

    pending is a request the restaurant still has to confirm.

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

  • starts_atstring (date-time)obligatorio

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

  • duration_minutesintegerobligatorio

    How long the table is held.

  • party_sizeintegerobligatorio

    Number of guests.

  • table_idsstring (uuid)[]obligatorio

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

  • sourcestringobligatorio

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

    Valores:"guest""staff""api"

  • guest_namestringobligatoriopuede ser null

    The guest's name.

  • notestringobligatoriopuede ser null

    The guest's wish.

  • created_atstring (date-time)obligatorio

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

  • updated_atstring (date-time)obligatorio

    Last change. ISO 8601 in UTC (Z).

  • deleted_atstring (date-time)obligatoriopuede ser null

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

• has_morebooleanobligatorio

  Whether another page follows.

• next_cursorstringobligatoriopuede ser null

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

Errores

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

Todos los códigos de error

Create a reservation#

post/reservations

Permiso:

reservations:write

Plan:

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

Parámetros

Cuerpoapplication/json

• starts_atstring (date-time)obligatorio

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

• party_sizeintegerobligatorio

  Number of guests.

  1 to 200

• guest_namestringobligatorio

  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.

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

  Valores:"confirmed""pending"

  default "confirmed"

• notify_guestboolean

  E-mail the guest (needs guest_email).

  default true

Respuesta201

The reservation.

• objectstringobligatorio

  Always reservation.

  Valores:"reservation"

• idstring (uuid)obligatorio

  The reservation.

• codestringobligatorio

  Short code the guest sees.

• statusstringobligatorio

  pending is a request the restaurant still has to confirm.

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

• starts_atstring (date-time)obligatorio

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

• duration_minutesintegerobligatorio

  How long the table is held.

• party_sizeintegerobligatorio

  Number of guests.

• table_idsstring (uuid)[]obligatorio

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

• sourcestringobligatorio

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

  Valores:"guest""staff""api"

• guest_namestringobligatoriopuede ser null

  The guest's name.

• notestringobligatoriopuede ser null

  The guest's wish.

• created_atstring (date-time)obligatorio

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

• updated_atstring (date-time)obligatorio

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obligatoriopuede ser null

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

Errores

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

Todos los códigos de error

Free reservation times of a day#

get/reservations/availability

Permiso:

reservations:read

Plan:

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

Parámetros

Respuesta200

OK

• objectstringobligatorio

  Always availability.

  Valores:"availability"

• datestring (date)obligatorio

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

• party_sizeintegerobligatorio

  The party size asked for.

• duration_minutesintegerobligatorio

  How long a table is held for this party size.

• timezonestringobligatorio

  The restaurant's time zone.

• slotsobject[]obligatorio

  The times of that day, ascending.

  Campos anidados (2)

  • starts_atstring (date-time)obligatorio

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

  • availablebooleanobligatorio

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

Errores

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

Todos los códigos de error

Retrieve a reservation#

get/reservations/{id}

Permiso:

reservations:read

Plan:

a partir de Pro

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

Parámetros

Respuesta200

OK

• objectstringobligatorio

  Always reservation.

  Valores:"reservation"

• idstring (uuid)obligatorio

  The reservation.

• codestringobligatorio

  Short code the guest sees.

• statusstringobligatorio

  pending is a request the restaurant still has to confirm.

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

• starts_atstring (date-time)obligatorio

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

• duration_minutesintegerobligatorio

  How long the table is held.

• party_sizeintegerobligatorio

  Number of guests.

• table_idsstring (uuid)[]obligatorio

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

• sourcestringobligatorio

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

  Valores:"guest""staff""api"

• guest_namestringobligatoriopuede ser null

  The guest's name.

• notestringobligatoriopuede ser null

  The guest's wish.

• created_atstring (date-time)obligatorio

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

• updated_atstring (date-time)obligatorio

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obligatoriopuede ser null

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

Errores

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

Todos los códigos de error

Change a reservation#

patch/reservations/{id}

Permiso:

reservations:write

Plan:

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

Parámetros

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

• notestringpuede ser 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

Respuesta200

The reservation after the change.

• objectstringobligatorio

  Always reservation.

  Valores:"reservation"

• idstring (uuid)obligatorio

  The reservation.

• codestringobligatorio

  Short code the guest sees.

• statusstringobligatorio

  pending is a request the restaurant still has to confirm.

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

• starts_atstring (date-time)obligatorio

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

• duration_minutesintegerobligatorio

  How long the table is held.

• party_sizeintegerobligatorio

  Number of guests.

• table_idsstring (uuid)[]obligatorio

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

• sourcestringobligatorio

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

  Valores:"guest""staff""api"

• guest_namestringobligatoriopuede ser null

  The guest's name.

• notestringobligatoriopuede ser null

  The guest's wish.

• created_atstring (date-time)obligatorio

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

• updated_atstring (date-time)obligatorio

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obligatoriopuede ser null

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

Errores

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

Todos los códigos de error

Set a reservation's status#

post/reservations/{id}/status

Permiso:

reservations:write

Plan:

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

Parámetros

Cuerpoapplication/json

• statusstringobligatorio

  The status to move to.

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

Respuesta200

OK

• objectstringobligatorio

  Always reservation.

  Valores:"reservation"

• idstring (uuid)obligatorio

  The reservation.

• codestringobligatorio

  Short code the guest sees.

• statusstringobligatorio

  pending is a request the restaurant still has to confirm.

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

• starts_atstring (date-time)obligatorio

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

• duration_minutesintegerobligatorio

  How long the table is held.

• party_sizeintegerobligatorio

  Number of guests.

• table_idsstring (uuid)[]obligatorio

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

• sourcestringobligatorio

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

  Valores:"guest""staff""api"

• guest_namestringobligatoriopuede ser null

  The guest's name.

• notestringobligatoriopuede ser null

  The guest's wish.

• created_atstring (date-time)obligatorio

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

• updated_atstring (date-time)obligatorio

  Last change. ISO 8601 in UTC (Z).

• deleted_atstring (date-time)obligatoriopuede ser null

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

Errores

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

Todos los códigos de error