Setup

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

Copy

1npm install @wix/bookings

Copy

1yarn add @wix/bookings

Then import { availabilityCalendar } from @wix/bookings:

Copy

1import { availabilityCalendar } from '@wix/bookings'

Was this helpful?

Yes

Availability Calendar: Supported Fields, Filters, and Sorting

Query endpoints allow you to filter and sort results based on slot availability properties. This article covers field sup port for filtering and sorting.

Filtering

Specify the filter object in the following format:

Copy

1"filter" : {  
2  "fieldName": "value"  
3 }

filter does not support the API Query Language comparison operators.

Note: Only the implied equal operator is supported. This means you can use the format above, but you cannot use the format below, even if $operator is $eq:

Copy

1"filter" : {  
2  "fieldName":{"$operator":"value"}  
3 }

The following table shows field support for filtering with the slotAvailability object:

Field	Required	Filterable	Sortable	Notes
`slot`		Not filterable
`slot.startDate`	Required	Not filterable	Sortable	Returns slots that start at, or after, this date. If `timezone` is specified, the `slot.startDate` for the query is according to the local date and time, which means that the timezone offset in the format is ignored.
`slot.endDate`	Required			Returns slots that end at, or before, this date. If the `timezone` is specified, the `slot.endDate` for the query is according to the local date and time, which means that the timezone offset in the format is ignored.
`slot.serviceId`				Supports multiple values, returned if slot is provided.
`slot.resourceId`
`slot.scheduleId`		Not filterable		Returned if `slot` is provided.
`slot.sessionId`		Not filterable
`slot.timezone`		Not filterable
`slot.resource`		Not filterable
`slot.location`		Not filterable
`bookable`				When filtered by `true`, returns only available slots. Otherwise, returns both available and non-available slots. This field is always returned.
`bookingPolicyViolations.tooEarlyToBook`
`bookingPolicyViolations.tooLateToBook`
`location.businessLocation.id`			Supports multiple values.
`openSpots`			Returns slots with at least this number of open spots.
`totalSpots`		Not filterable
`waitingList`		Not filterable
`bookingPolicyViolations`		Not filterable

Sorting

Currently, only sorting by startDate is supported.

Specify the sort object in the following format:

Copy

1"sort" : { 
2    "fieldName":"sortField1",
3    "order":"ASC"
4  }

Related content: API Query Language, queryAvailability( )

Was this helpful?

Yes

queryAvailability( )

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 the availability for sessions that match the provided query criteria (paging, filtering, and sorting).

The Availability Calendar APIs calculate the availability of sessions for appointments and classes, but not for courses.

The entire list of slots is returned in case you want to display both available and non-available slots in the calendar for your customers. Using the bookable property, you can limit the display to available slots only.

When querying, you must enter a start date and an end date. This avoids very large results that can impact performance.

Calculating availability

The availability is determined by checking:

The sessions' open slots. A slot is considered open if the session's capacity is greater than number of participants.
Booking policies. Policies that affect whether a slot is considered available include tooEarlyToBook, tooLateToBook, and bookOnlineDisabled.

Locked sessions do not impact session availability and bookable can be true even if locked is true. For example, if a session has a waitlist and a place frees up, the slot is offered to the customers on the waitlist, one by one. The session remains locked because there is still a waitlist, but for a period of time there is availability, until a customer on the waitlist takes the slot. Locking prevents customers who are not yet on the waitlist from grabbing the slot.

Handling Daylight Savings Time (DST) for local time zones

Because of DST, there are cases where certain times either do not exist or exist twice for a local time zone. For example, the tine 00:05 on September 5th 2021 might not exist in Santiago, Chile, because at 00:00 the clock moved 1 hour forward to 01:00.

In this case, the Availability Calendar APIs take this into account and mediate the time gaps automatically. The non-existent local time is automatically moved forward 1 hour to match local DST. Local times that exist do not change. So if the queryAvailability() function is called with a startDate of 2021-09-05T00:00:01.000 and an endDate of 2021-09-06T00:00:02.000, 2021-09-05T01:00:01.000 is used in the query instead. The start time shifts one hour forward and the end time remains the same.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Copy

function queryAvailability(query: QueryV2, options: QueryAvailabilityOptions): Promise<QueryAvailabilityResponse>

Method Parameters

queryQueryV2Required

Query options.

optionsQueryAvailabilityOptions

Additional options for performing the query.

Returns

Return Type:Promise<QueryAvailabilityResponse>

Was this helpful?

Yes