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 owner must install the Wix Table Reservations app.
  • The site owner must have at least 1 location configured in their Dashboard under Business Info.

Use Cases

Reservation app for restaurants on a Wix site

Terminology

For a comprehensive glossary of Reservations terms, see Terminology.

Was this helpful?
Yes
No

Reservations: Supported Filters and Sorting

The following table shows field support for filters and sorting for the Reservation object:

FieldSupported FiltersSortable
id$eq, $ne, $in
status$eq, $ne, $in
details.startDate$eq, $ne, $lt, $lte, $gt, $gte, $inSortable

Related content: API Query Language, Query Reservations

Was this helpful?
Yes
No

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

Create Held Reservation - This endpoint 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 pages created by the Table Reservations app on Wix sites use this endpoint to temporarily reserve time slots selected by customers while they enter further details.

After a customer completes the reservation process, call Reserve Reservation to change the reservation’s status to RESERVED or REQUESTED, depending on whether the site requires manual approval for online reservations.

You cannot call Update Reservation to change a reservation’s status from HELD. Trying to do so returns an error.

Create Reservation - 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).

With the MANAGE RESERVATIONS (FULL) permission scope, you can set more properties of the reservation in the Create Reservation 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 Reserve Reservation 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 Update Reservation and change the reservation’s status to RESERVED or DECLINED respectively.

Seating customers

Once customers have been seated (or the equivalent if your restaurant doesn’t have seats), change the status of the reservation to SEATED using Update Reservation.

Ending a Reservation

A reservation can end as DECLINED, CANCELED, NO_SHOW, or FINISHED. In each case, change the status using Update Reservation. 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

Was this helpful?
Yes
No

Reservation Object

The reservation domain object.

Properties
idstringRead-onlyformat GUID
Reservation ID. Read-only.

statusstring
9 enum supported values:
UNKNOWNHELDRESERVEDCANCELEDFINISHEDNO_SHOWSEATEDREQUESTEDDECLINED
Status of the reservation.
  • 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.
See the Reservation Lifecycle article for an explanation of the role of statuses in the reservation lifecycle.

sourcestring
4 enum supported values:
UNKNOWNOFFLINEONLINEWALK_IN
Reservation source. This indicates how the reservation was made.
  • ONLINE indicates that the customer made the reservation through a website or app.
  • OFFLINE indicates that the reservation was made by a restaurant employee, for example when a customer calls to make a reservation.
  • WALK-IN indicates that the customer did not make a reservation beforehand, and the reservation was entered into the system by a restaurant employee when the customer arrived at the restaurant.

detailsobject
Reservation details.

reserveeobject
Information about the person the reservation is being made for.

reservedByobject
Information about the person making the reservation. This field is required if the reservation's status is anything other than WALK_IN.

teamMessagestringmaxLength 10000
Team message. A message for the restaurant staff containing any additional information regarding the reservation, such as special requirements for the guests.

createdDatestringRead-onlyformat date-time
Date and time when the reservation was created.

updatedDatestringRead-onlyformat date-time
Date and time when the reservation was changed.

revisionobjectRead-only
Revision number, which increments by 1 each time the reservation is updated. To prevent conflicting changes, the current revision must be passed when updating the reservation. Ignored when creating a reservation.

declineReasonstringmaxLength 1000
The reason the reservation was declined.
Was this helpful?
Yes
No

GetList Reservations

Developer Preview

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:
Manage Reservations (Medium)
Manage Reservations (Full)
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/table-reservations/reservations/v1/reservations

Was this helpful?
Yes
No

PostCreate Reservation

Developer Preview

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.

Create Reservation accepts and requires different fields depending on the status and source provided, and the permissions of the user calling the endpoint.

Status and source

If a status is not provided, it will be set to:

  • RESERVED if manual approval is not required for confirmation
  • REQUESTED 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 results in an error.

Permissions

The fields status, source, reservation.details.tableIds, reservation.details.endDate, ignoreReservationLocationConflicts, and ignoreTableCombinationConflicts should only be included in the request if the call is made by a user with the MANAGE RESERVATIONS (FULL) permission scope. Including these fields in the request without the required permissions results in an application error.

If source is not provided, its value is set depending on the permissions of the user making the call. If the user has the MANAGE RESERVATIONS (FULL) permission scope the source is set to UNDEFINED. Otherwise, the source is set to ONLINE.

Note: Create Reservation requires all details of the reservation upfront. The process of creating a reservation can be broken up using Create Held Reservation. Create Held Reservation creates a temporary reservation that expires automatically unless it is completed with the addition of more details using Reserve Reservation.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reservations (Medium)
Manage Reservations (Full)
Manage Reservations (Basic)
Manage Reservations (Full)
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/table-reservations/reservations/v1/reservations

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetGet Reservation

Developer Preview

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.

The FULL fieldset can only be retrieved by users with the MANAGE RESERVATIONS (MEDIUM) or MANAGE RESERVATIONS (FULL) permission scopes.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reservations (Medium)
Manage Reservations (Full)
Manage Reservations (Basic)
Manage Reservations (Medium)
Manage Reservations (Full)
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/table-reservations/reservations/v1/reservations/{reservationId}

Was this helpful?
Yes
No

PatchUpdate Reservation

Developer Preview

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.

The fields status, source, reservation.details.tableIds, reservation.details.endDate, ignoreReservationLocationConflicts, and ignoreTableCombinationConflicts should only be included in the request if the call is made by a user with the MANAGE RESERVATIONS (FULL) permission scope. Including these fields in the request without the required permissions results in an application error.

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:
Manage Reservations (Medium)
Manage Reservations (Full)
Manage Reservations (Full)
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/table-reservations/reservations/v1/reservations/{reservation.id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostCreate Held Reservation

Developer Preview

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 Update Reservation to change a reservation’s status from HELD. Trying to do so returns an error. Instead, you should use Reserve Reservation.

If you do not wish to have HELD reservations in your flow, you can create a reservation with all required details using Create Reservation.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reservations (Medium)
Manage Reservations (Full)
Manage Reservations (Basic)
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/table-reservations/reservations/v1/reservations/hold

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostReserve Reservation

Developer Preview

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 the Create Held Reservation endpoint. 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:
Manage Reservations (Medium)
Manage Reservations (Full)
Manage Reservations (Basic)
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/table-reservations/reservations/v1/reservations/{reservationId}/reserve

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostCancel Reservation

Developer Preview

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:
Manage Reservations (Medium)
Manage Reservations (Full)
Manage Reservations (Basic)
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/table-reservations/reservations/v1/reservations/{reservationId}/cancel

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery Reservations

Developer Preview

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 reservations given the provided paging, filtering, and sorting. Up to 100 reservations can be returned per request.

For a detailed list of supported operations, see the Supported Filters and Sorting article. To learn how to query reservations, see API Query Language.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reservations (Medium)
Manage Reservations (Full)
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/table-reservations/reservations/v1/reservations/query

Was this helpful?
Yes
No

Reservation Created

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a held reservation is created.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reservations (Medium)
Manage Reservations (Full)
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.table_reservations.v1.reservation.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.

Was this helpful?
Yes
No

Reservation Updated

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a reservation is canceled.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reservations (Medium)
Manage Reservations (Full)
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.table_reservations.v1.reservation.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.

Was this helpful?
Yes
No