About the Wix Bookings API

With the Wix Bookings API you can manage bookings for a site's services. The booking object holds information about the customer and the session or schedule they have booked. You can then use the eCommerce APIs to handle the checkout and payment flow.

With Wix Bookings API you can:

  • Create new bookings
  • Retrieve existing bookings
  • Manage the booking's life cycle
Was this helpful?
Yes
No

Setup

To use the Bookings API, install the @wix/bookings package using npm or Yarn:

Copy
1
npm install @wix/bookings

or

Copy
1
yarn add @wix/bookings

Then import { bookings } from @wix/bookings:

Copy
1
import { bookings } from '@wix/bookings'
Was this helpful?
Yes
No

bulkConfirmOrDeclineBooking( )

Developer Preview

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

Confirm or decline multiple bookings. See [Confirm Or Decline Booking] (https://dev.wix.com/api/rest/wix-bookings/confirmation/confirm-or-decline-booking) documentation.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function bulkConfirmOrDeclineBooking(details: Array<BulkConfirmOrDeclineBookingRequestBookingDetails>, options: BulkConfirmOrDeclineBookingOptions): Promise<BulkConfirmOrDeclineBookingResponse>
Method Parameters
detailsArray<BulkConfirmOrDeclineBookingRequestBookingDetails>Required
The bookings to confirm or decline.

optionsBulkConfirmOrDeclineBookingOptions
Returns
Return Type:Promise<BulkConfirmOrDeclineBookingResponse>
Was this helpful?
Yes
No

bulkCreateBooking( )

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 multiple bookings.

See createBooking() documentation.

If for any of the bookings required fields were not passed on the request or if the caller doesn't have the required permissions to create such booking, the call will fail. If the request contains unavailable bookings, the call will be completed successfully, but the unavailable bookings will not be created and will be considered as a failure on the response.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function bulkCreateBooking(createBookingsInfo: Array<CreateBookingInfo>, options: BulkCreateBookingOptions): Promise<BulkCreateBookingResponse>
Method Parameters
createBookingsInfoArray<CreateBookingInfo>Required
Bookings to create. Max: 8 bookings.

optionsBulkCreateBookingOptions
Returns
Return Type:Promise<BulkCreateBookingResponse>
Was this helpful?
Yes
No

cancelBooking( )

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

The booking status changes to CANCELED.

If the booking was for an appointment, the corresponding session is deleted from the business calendar.

If the booking was for a class or course, the participants are removed from the class session or the course. But the course or class session remains on the business calendar.

You can pass a participantNotification.message to notify the customer of the cancelation. You also need to pass participantNotification.notifyParticipants as true to actually send the message.

In case you want to cancel a booking on behalf of a customer, we recommend to pass flowControlSettings.ignoreCancellationPolicy as false. This ensures that the cancelation is validated against the service's cancelation policy.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function cancelBooking(bookingId: string, options: CancelBookingOptions): Promise<CancelBookingResponse>
Method Parameters
bookingIdstringRequired
ID of the booking to cancel.

optionsCancelBookingOptions
An object representing the available options for canceling a booking.
Returns
Return Type:Promise<CancelBookingResponse>
Was this helpful?
Yes
No

confirmBooking( )

Developer Preview

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

Confirms a booking request and changes the booking status to CONFIRMED.

Calling this method doesn't check whether a slot or schedule is still available at this time.

You can only confirm bookings for services that require the owner's manual approval for bookings and that have a status of PENDING.

For appointment services the slot may become unavailable, depending on the service's policy.bookingApprovalPolicy.requestsAffectsAvailability.

Calling this method also changes the session's participants.approvalStatus to APPROVED.

You can pass a participantNotification.message to notify the customer of the confirmation. You also need to pass participantNotification.notifyParticipants as true to actually send the message.

Bookings are automatically confirmed when the service is configured to automatically confirm bookings and the eCommerce order has been approved. The slot's or schedule's availability is checked just before confirming the booking as part of the automatic flow.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function confirmBooking(bookingId: string, revision: string, options: ConfirmBookingOptions): Promise<ConfirmBookingResponse>
Method Parameters
bookingIdstringRequired
ID of the booking to confirm.

revisionstringRequired
Revision number, which increments by 1 each time the booking is updated. To prevent conflicting changes, the current revision must be passed when managing the booking.

optionsConfirmBookingOptions
An object representing the available options for canceling a booking.
Returns
Return Type:Promise<ConfirmBookingResponse>
Was this helpful?
Yes
No

confirmOrDeclineBooking( )

Developer Preview

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

Use confirmOrDeclineBooking() to determine if the booking is valid, payment is received, and the booking can be processed. Call confirmOrDeclineBooking() after checkout or after calling createBooking() to verify the booking.

  • If a session is valid and payment is received, the booking is visible on the calendar.
  • If a session is double booked, confirmOrDeclineBooking() can catch this and decline the duplicate booking, the booking is not visible on the calendar.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function confirmOrDeclineBooking(bookingId: string, options: ConfirmOrDeclineBookingOptions): Promise<ConfirmOrDeclineBookingResponse>
Method Parameters
bookingIdstringRequired
ID of the booking to confirm or decline.

optionsConfirmOrDeclineBookingOptions
Returns
Return Type:Promise<ConfirmOrDeclineBookingResponse>
Was this helpful?
Yes
No

createBooking( )

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

To create a booking for an appointment or a session of a class, pass a booking with the relevant slot.

To create a booking for the entire course, pass a booking with the relevant schedule. You can use the Query Availability endpoint to check the availability beforehand.

If you create a booking for an existing session, we recommend that you only pass slot.sessionId. Then, any specified slot details are calculated.

If you create a booking for a new session, we recommend to call Query Availability first. Then, pass the retrieved availability.slot object as the BookedEntity.Slot of the booking in the request.

Bookings are created with a status of CREATED. CREATED bookings don't appear on the business calendar and don't affect a related schedule's availability.

To create a booking with a given status, pass a booking with the wanted status. This is only permitted for site Owners.

You can pass a participantNotification.message to notify the customer of the booking with a message. It's also necessary to pass participantNotification.notifyParticipantsas true to send the message.

You can pass sendSmsReminder as true, if you want an SMS reminder to be sent to the phone number specified in the ContactDetails, 24 hours before the session starts.

When creating a booking you must pass either participantsChoices or totalParticipants. If you pass participantsChoices, all the provided choices must exist for the service, otherwise the call returns an INVALID_SERVICE_CHOICES error.

When creating a booking, you can pass selectedPaymentOption. This specifies which payment method the customer plans to use. But it's possible for them to later use another supported payment method.

You can skip the checkout and payment flow if you call Confirm Or Decline Booking otherwise, after you create the booking, you can use the Wix eCommerce APIs (coming soon) for the checkout and payment flow or use a different service for checkout.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function createBooking(booking: Booking, options: CreateBookingOptions): Promise<CreateBookingResponse>
Method Parameters
bookingBookingRequired
The booking to create.

optionsCreateBookingOptions
Returns
Return Type:Promise<CreateBookingResponse>
Was this helpful?
Yes
No

declineBooking( )

Developer Preview

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

Declines a PENDING booking request and changes the booking status to DECLINED.

Calling this method also changes the session's participants.approvalStatus to DECLINED.

You can only decline bookings for services that require the owner's manual approval for bookings and that have a status of PENDING.

You can pass a participantNotification.message to notify the customer of the decline. You also need to pass participantNotification.notifyParticipants as true to actually send the message.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function declineBooking(bookingId: string, revision: string, options: DeclineBookingOptions): Promise<DeclineBookingResponse>
Method Parameters
bookingIdstringRequired
ID of the booking to decline.

revisionstringRequired
Revision number, which increments by 1 each time the booking is updated. To prevent conflicting changes, the current revision must be passed when managing the booking.

optionsDeclineBookingOptions
An object representing the available options for declining a booking.
Returns
Return Type:Promise<DeclineBookingResponse>
Was this helpful?
Yes
No

rescheduleBooking( )

Developer Preview

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

Reschedules a booking to a different slot or session.

You can only reschedule bookings for appointments or classes, you can't reschedule course bookings.

The old session is removed from the calendar and the new session is added.

If you reschedule a booking for a class session the new session must be an existing session for the same class.

You can pass a participantNotification.message to notify the customer of the rescheduling. You also need to pass participantNotification.notifyParticipants as true to actually send the message.

In case the service has variants, you can call this endpoint to update the booking's totalParticipants or participantsChoices. If you provide participantsChoices, all of the provided choices must exist for the service. Otherwise, the call returns an INVALID_SERVICE_CHOICES error. If you omit participantsChoices in the request, the existing choices are kept and not replaced with an empty object.

In case you want to reschedule a booking on behalf of a customer, we recommend to pass flowControlSettings.ignoreReschedulePolicy as false. This ensures that the rescheduling is validated against the service's rescheduling policy.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function rescheduleBooking(bookingId: string, slot: V2Slot, options: RescheduleBookingOptions): Promise<RescheduleBookingResponse>
Method Parameters
bookingIdstringRequired
ID of the booking to reschedule.

slotV2SlotRequired
Information about the new slot.

optionsRescheduleBookingOptions
An object representing the available options for rescheduling a booking.
Returns
Return Type:Promise<RescheduleBookingResponse>
Was this helpful?
Yes
No

updateNumberOfParticipants( )

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 the number of participants for a booking.

You can only update the number of participants for class and course bookings, you can't update it for appointment bookings.

Calling this method also changes the session's totalNumberOfParticipants.

When updating the number of participants for a booking you must pass either participantsChoices or totalParticipants. If you pass participantsChoices for services that have variants, all of the provided choices must exist for the service. Otherwise, the call returns an INVALID_SERVICE_CHOICES error.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Bookings
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function updateNumberOfParticipants(bookingId: string, options: UpdateNumberOfParticipantsOptions): Promise<UpdateNumberOfParticipantsResponse>
Method Parameters
bookingIdstringRequired
ID of the booking to update the number of participants for.

optionsUpdateNumberOfParticipantsOptions
Returns
Return Type:Promise<UpdateNumberOfParticipantsResponse>
Was this helpful?
Yes
No