Introduction
The Reservations API allows you to create and manage reservations at restaurants.
This API provides all the necessary functionality to move a reservation through the phases of its lifecycle, such as from the reservation request until completion.
The Reservations API works together with the Reservation Locations API, which provides information about the physical location of a restaurant, as well as that restaurant’s availability and reservation conditions.
The Reservations API also works together with the Time Slots API, which allows you to retrieve availability information about time slots at a restaurant on a specific date and for a specific party size.
With the Reservations API, you can:
- Create and manage reservations at a restaurant.
- Get information about existing reservations at a restaurant.
Before you begin
It’s important to note the following points before starting to code:
- The site or project owner must install the Wix Table Reservations app.
- The site or project owner must have at least 1 location configured in their Dashboard under Business Info.
Permissions information
The following functions may require additional permissions to run depending on which fields are included, or the value of certain fields.
createReservation()
Calling createReservation()
with the following fields requires additional permissions:
status
source
reservation.details.tableIds
reservation.details.endDate
ignoreReservationLocationConflicts
ignoreTableCombinationConflicts
Permission requirements are as follows:
- In an app, providing these fields requires the
MANAGE RESERVATIONS (FULL)
permission scope. - On a headless site, providing these fields requires API key authorization with appropriate permissions.
If the user does not provide a source
, the value assigned to it will depend on the user's permissions:
- In an app, if the user calls
createReservation()
with theMANAGE RESERVATIONS (FULL)
permission scope,source
is set toUNDEFINED
. Otherwise,source
is set toONLINE
. - On a headless site with Visitor or Member authorization,
source
is set toONLINE
.
getReservation()
Calling getReservation()
with fieldsets
set to FULL
requires additional permissions:
- In an app, the
FULL
fieldset requires either theMANAGE RESERVATIONS (MEDIUM)
orMANAGE RESERVATIONS (FULL)
permission scope. - On a headless site, retrieving the
FULL
fieldset requires API key authorization with appropriate permissions.
Terminology
For a comprehensive glossary of Table Reservations terms, see Terminology.
Setup
To use the Reservations API, install the @wix/table-reservations
package using npm or Yarn:
1npm install @wix/table-reservations
or
1yarn add @wix/table-reservations
Then import { reservations }
from @wix/table-reservations
:
1import { reservations } from '@wix/table-reservations'
The Reservation Lifecycle
Reservations progress from creation to completion through a series of phases. Each phase is represented by a status, which is stored as an enum in the status
field of a reservation
object.
This article explains the available statuses, and how a reservation can progress using the Reservations API.
Note: Reservations can be created and progress through phases as a result of actions on a Wix site or dashboard. For more information see the Wix Restaurants Table Reservations articles.
Statuses
The following statuses are listed roughly in order of their position in the reservation lifecycle:
HELD
- The reservation is temporary and will expire in 10 minutes if its status isn’t changed. This phase temporarily reserves the required number of seats and tables for a given party size at a chosen time while a customer enters details and/or confirms their reservation request.REQUESTED
- A customer finished requesting this reservation, meaning they have added all necessary details and confirmed the request. Restaurant staff can now either approve or decline the reservation request.DECLINED
- The restaurant’s owner or staff declined the customer’s request to make the reservation.RESERVED
- The reservation is confirmed.SEATED
- The customer is currently occupying the table.CANCELED
- The reservation is canceled.NO_SHOW
- The customer didn't show up for their reservation.FINISHED
- The reservation completed successfully.
Managing the reservation lifecycle
This section explains how reservations can be created and progressed through their lifecycle.
Create a reservation
This API provides 2 endpoints for creating reservations.
createHeldReservation()
- This function creates a reservation with the HELD
status. Reservations with the HELD
status are only valid for 10 minutes. Trying to change a HELD
reservation’s status after 10 minutes returns an error.
The Reservations page created by the Restaurants app on a Wix site creates held reservations to temporarily reserve time slots selected by customers while they enter further details.
After a customer completes the reservation process, call reserveReservation()
to change the reservation’s status to RESERVED
or REQUESTED
, depending on whether your project requires manual approval for online reservations.
You cannot call updateReservation()
to change a reservation’s status from HELD
. Trying to do so returns an error.
createReservation()
- This endpoint creates a reservation with either the RESERVED
status or the REQUESTED
status if manual approval is required for confirmation (see manual approval below).
If you call createReservation()
with the MANAGE RESERVATIONS (FULL)
permission scope, you can set more properties of the reservation in the request. This allows you to create the reservation with a status of your choice, and gives you the option to override the restaurant’s rules regarding online availability and table management.
Requiring manual approval
To require manual approval for REQUESTED
reservations at a location before they’re confirmed (RESERVED
), set configuration.onlineReservations.manualApproval.enabled
to true
for that reservation location. Manual approval can also be set through a site’s Table Reservations app in the dashboard.
If manual approval is enabled for online reservations at a reservation location, reservations made using the reserveReservation()
endpoint or through the restaurant’s dashboard are automatically created with the REQUESTED
status. This setting does not affect offline reservations.
Reserving or declining reservations
To use the Reservations API to approve or decline a reservation, call updateReservation()
and change the reservation’s status to RESERVED
or DECLINED
respectively.
Seating customers
Once customers have been seated (or the equivalent if the restaurant doesn’t have seats), change the status of the reservation to SEATED
using updateReservation()
.
Ending a Reservation
A reservation can end as DECLINED
, CANCELED
, NO_SHOW
, or FINISHED
.
In each case, change the status using updateReservation()
. Once any of the above statuses are set, the reservation is considered complete.
Lifecycle flow examples
The following are examples of possible paths a reservation could take from creation to completion:
Finished
A customer selects a time slot for a reservation on the restaurant’s website. They proceed to enter their details and confirm their reservation request. The restaurant owner approves the reservation. The customer arrives and is seated. They finish their meal, pay, and leave.
This flow would be represented by:
HELD
> REQUESTED
> RESERVED
> SEATED
> FINISHED
Cancelation
A customer calls the restaurant and makes a reservation, but their car breaks down and they call again to cancel.
This flow would be represented by:
RESERVED
> CANCELED
No Show
A customer makes a reservation using the restaurant’s app. The restaurant owner approves the reservation, but the customer never shows up.
This flow would be represented by:
REQUESTED
> RESERVED
> NO_SHOW
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Cancels a reservation.
Sets the reservation status to CANCELED
.
Permission Scopes
For app development, you must have one of the following permission scopes:function cancelReservation(reservationId: string, revision: string, options: CancelReservationOptions): Promise<CancelReservationResponse>
Reservation ID.
Revision number.
Include the existing revision to prevent conflicting updates to reservations.
Options for canceling the reservation.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a new temporary reservation and holds it for the customer for 10 minutes.
Creates a new reservation with the HELD
status. HELD
reservations are intended to reserve seats and tables for a party in a selected time slot while they enter further reservation details, such as names and contact information. Reservations with the HELD
status are only valid for 10 minutes. Trying to change a HELD
reservation’s status after 10 minutes returns an error.
You cannot call updateReservation()
to change a reservation’s status from HELD
. Trying to do so returns an error. Instead, you should use reserveReservation()
.
If you do not wish to have HELD
reservations in your flow, you can create a reservation with all required details using createReservation()
.
Permission Scopes
For app development, you must have one of the following permission scopes:function createHeldReservation(reservationDetails: HeldReservationDetails): Promise<CreateHeldReservationResponse>
Held reservation information to update.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a new reservation.
createReservation()
accepts and requires different fields depending on the status
provided and your permissions.
Status and source
If a status
is not provided, it will be set to:
RESERVED
if manual approval is not required for confirmationREQUESTED
if manual approval is required for confirmation.
A reservation created with any source
other than WALK_IN
requires the reservation.reservee.phone
and reservation.reservee.firstName
fields.
Attempting to create a reservation without these fields will result in an error.
Permissions
Including the fields status
, source
, reservation.details.tableIds
, reservation.details.endDate
, ignoreReservationLocationConflicts
, or ignoreTableCombinationConflicts
in the request requires additional permissions. See this API's Introduction article for more information.
If source
is not provided, its value is set depending on the permissions of the user making the call. See this API's Introduction article for more information.
Note: createReservation()
requires all details of the reservation upfront. The process of creating a reservation can be broken up using createHeldReservation
. createHeldReservation
creates a temporary reservation that expires automatically unless it is completed with the addition of more details using reserveReservation()
.
Permission Scopes
For app development, you must have one of the following permission scopes:function createReservation(reservation: Reservation, options: CreateReservationOptions): Promise<Reservation>
Reservation details.
Options for creating the reservation.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a reservation.
Calling this method with fieldsets
set to FULL
requires additional permissions. See this API's Introduction article for more information.
Permission Scopes
For app development, you must have one of the following permission scopes:function getReservation(reservationId: string, options: GetReservationOptions): Promise<Reservation>
Reservation ID.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of up to 100 reservations.
Permission Scopes
For app development, you must have one of the following permission scopes:function listReservations(options: ListReservationsOptions): Promise<ListReservationsResponse>
Options for listing the reservations.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a query to retrieve a list of reservations.
The queryReservations()
function builds a query to retrieve a list of reservations and returns a ReservationsQueryBuilder
object.
The returned object contains the query definition, which is used to run the query using the find() function.
You can refine the query by chaining ReservationsQueryBuilder
functions onto the query. ReservationsQueryBuilder
functions enable you to filter, sort, and control the results that queryReservations()
returns.
queryReservations()
runs with the following ReservationsQueryBuilder
defaults, which you can override:
The following ReservationsQueryBuilder
functions are supported for queryReservations()
. For a full description of the reservation object, see the object returned for the items
property in ReservationsQueryResult
.
PROPERTY | SUPPORTED FILTERS & SORTING |
---|---|
_id | eq() ,ne() ,in() |
status | eq() ,ne() ,in() |
details.startDate | eq() ,ne() ,in() ,lt() ,gt() ,le() ,ge() ,ascending() ,descending() |
Permission Scopes
For app development, you must have one of the following permission scopes:function queryReservations(): ReservationsQueryBuilder
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Reserves or requests a held reservation.
Held reservations are temporary reservations with the HELD
status created by createHeldReservation()
.
They are intended to reserve seats and tables for a party in a selected time slot while they enter further reservation details, such as names and contact information. Reservations with the HELD
status are only valid for 10 minutes. Trying to call Reserve Reservation
with a held reservation older than 10 minutes returns an error.
Reserve Reservation
changes a reservation's HELD
status to:
RESERVED
if the reservation's reservation location does not require manual approval.REQUESTED
if the reservation's reservation location requires manual approval.
Permission Scopes
For app development, you must have one of the following permission scopes:function reserveReservation(reservationId: string, reservee: Reservee, revision: string): Promise<ReserveReservationResponse>
Reservation ID.
Reservee details.
Revision number.
Include the existing revision to prevent conflicting updates to reservations.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a reservation.
Including the fields status
, source
, reservation.details.tableIds
, reservation.details.endDate
, ignoreReservationLocationConflicts
, and ignoreTableCombinationConflicts
in the request requires additional permissions. See this API's Introduction article for more information.
Each time the reservation is updated, revision increments by 1. The existing revision must be included when updating the reservation. This ensures you're working with the latest reservation information, and it prevents unintended overwrites.
Permission Scopes
For app development, you must have one of the following permission scopes:function updateReservation(_id: string, reservation: UpdateReservation, options: UpdateReservationOptions): Promise<Reservation>
Reservation ID.
Reservation information to update.
Options for updating the reservation.