Setup

To use the AvailabilityTimeSlots 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 { availabilityTimeSlots } from @wix/bookings:

Copy
1
import { availabilityTimeSlots } from '@wix/bookings'
Was this helpful?
Yes
No
getAvailabilityTimeSlot( )
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 an available TimeSlot that match the provided filters.

Throws SlotNotFound if there is no such available time slot.

Important:
Currently supported only for services of type APPOINTMENT.

By default, if you don't provide includeResourceTypeIds or resourceIds in request, we return all AvailableResources with all AvailableResources.resources which are available to provide the service within the time slot.

If you specify includeResourceTypeIds or resourceIds in request, the returned TimeSlot will contain only AvailableResources with at least one available resource which match the given resources filters, each contains all available resources out of those requested.

Tip:
Use this API in order to get the availability of a specific TimeSlot out of those returned from ListAvailabilityTimeSlots API.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Bookings - Public Data
Manage Bookings Services and Settings
Read Bookings - Including Participants
Read Bookings - all read permissions
Read Bookings Calendar Availability
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function getAvailabilityTimeSlot(serviceId: string, localStartDate: string, localEndDate: string, timeZone: string, location: Location, options: GetAvailabilityTimeSlotOptions): Promise<GetAvailabilityTimeSlotResponse>
Method Parameters
serviceIdstringRequired
Service ID of the time slot. Currently supported only for services of type APPOINTMENT.
localStartDatestringRequired
Local start date of the time slot, in ISO-8601 format. For example, "2024-01-30T13:30:00".
localEndDatestringRequired
Local end date of the time slot, in ISO-8601 format. For example, "2024-01-30T14:30:00".
timeZonestringRequired
Time zone, in IANA time zone format.
locationLocationRequired
The location of the time slot. You must provide a specific locationType. If locationType is BUSINESS, you must also provide a locationId.
Supports filtering by location type, or by location ID. Other fields like name are ignored.
optionsGetAvailabilityTimeSlotOptions
Returns
Return Type:Promise<GetAvailabilityTimeSlotResponse>
Was this helpful?
Yes
No
listAvailabilityTimeSlots( )
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 TimeSlots that match the provided filters.

Important: Currently supported only for services of type APPOINTMENT.

The request body must include either:

  • All of the following filters: serviceId, fromLocalDate, toLocalDate, and timeZone. You may add additional filters as you wish.
  • A cursorPaging with a valid cursor from previous response.

Each TimeSlot in response represents the availability of the service in a specific location, and has a localStartDate within the range of the provided fromLocalDate and toLocalDate exclusive. The localEndDate of a TimeSlot is calculated as the sum of the TimeSlot's localStartDate and the duration of the service.

By default, the response contains at most 1000 results. If there are more than 1000 results, we return a cursorPagingMetadata with a cursor for the next page of results, regardless of whether a cursorPaging was provided in request.

AvailableResources in response

The TimeSlot's AvailableResources contains information about the resources that are available to provide the service within the time slot. Each AvailableResources contains information about available resources of the same type.

Important:
By default, if you don't specify includeResourceTypeIds or resourceIds filters in request, we return TimeSlots with an empty AvailableResources.
Note:
Not specifying resources filters can be handy in case you want to avoid large response in flows that only interested of whether the time slots are available. [Finding the next available slot within the next 3 months](https://bo.wix.com/wix-docs/rest/all-apis/service-availability/availability-time-slots/sample-flows?localViewerId=inbari#all-apis_service-availability_availability-time-slots_sample-flows_find-the-first-date-within-the-next-3-months-that-the-selected-service-is-available-for) is an example for such flow.

If you wish to get a list of available resources for each TimeSlot you should either:

  • provide resourceIds in request.
  • provide includeResourceTypeIds in request.

Notes:

  • In both cases the returned TimeSlots contains up to 10 AvailableResources that match the provided filters. Each AvailableResources contains up to 10 available resources of the same type that match the provided filters.
  • If an AvailableResources has more available resources which are not listed within it, we return AvailableResources.hasMoreAvailableResources as true.

Note: If you wish to get the full available resources list for a specific TimeSlot, you should call GetAvailabilityTimeSlot.

Availability VS Bookability

An available time slot is not necessarily bookable. The bookable field of a TimeSlot indicates whether a customer can book the service within the given time slot, at a specific period of time. Read more about Availability VS Bookability.

By default,

  • The response does not contains unavailable TimeSlots. For example, if there are no available resources to provide the service from 2024-01-30T14:30:00 to 2024-01-30T15:30:00, we don't return TimeSlots with localStartDate within this range.
  • The response contains both bookable and un-bookable TimeSlots. For example, if the service has a booking policy which enforces booking the service up to 10 minutes before the session starts, we return TimeSlots with the violating localStartDate with bookable as false. If you wish to list only available bookable TimeSlots you should pass bookable filter as true.

Important: Because of DST, there are edge cases where certain times either do not exist or exist twice for a local time zone. Read more about DST Handling

ListAvailabilityTimeSlots runs with the following defaults

  • localStartDate is sorted in ASC order
  • cursorPaging.limit is 1000

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Bookings - Public Data
Manage Bookings Services and Settings
Read Bookings - Including Participants
Read Bookings - all read permissions
Read Bookings Calendar Availability
Manage Bookings - all permissions
Learn more about permission scopes.
Copy
function listAvailabilityTimeSlots(options: ListAvailabilityTimeSlotsOptions): Promise<ListAvailabilityTimeSlotsResponse>
Method Parameters
optionsListAvailabilityTimeSlotsOptions
Returns
Return Type:Promise<ListAvailabilityTimeSlotsResponse>
Was this helpful?
Yes
No