This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves appointment slots or class events that match specified filters.
Course events can't be retrieved with this method. Follow this sample flow* (SDK | REST) to check course availability.
You must include serviceId
in your query filter. For performance, also specify
both startDate
and endDate
. Refer to the
supported filters article* (SDK | REST)
for a complete list of supported filters.
To limit the maximum number of appointment slots returned for each date,
specify slotsPerDay
. For example, specifying {"slotsPerDay": 3}
returns
a maximum of 3 appointment slots/class events for each day that's within the
query filter's date range.
By default, both available and unavailable appointment slots/ class events
are returned. To retrieve only available slots/events, specify
{"bookable": true}
in the filter.
Slots/events can be sorted only by startDate
. Unavailable slots/events
always appear after available ones.
Wix Bookings calculates availability differently for appointment-based services and classes.
An appointment slot is bookable
if:
startDate
is later than or equal to query.filter.startDate
.endDate
is before or equal to query.filter.endDate
.onlineBooking.enabled
is true
.A class event is bookable
if:
startDate
is later than or equal to query.filter.startDate
.endDate
is before or equal to query.filter.endDate
.remainingCapacity
is greater than 0
.onlineBooking.enabled
is true
.If you want to restrict returned class events to those with a minimum number
of remaining spots, specify openSpots
in the filter. By default, all class
events, even those with no open spot, are returned.
Due to DST, some local times may not exist or may occur twice. For example, in Santiago, Chile, on September 7, 2025, 0:05 AM doesn't exist because the clock advances from 0:00 AM to 1:00 AM.
Query Availability* automatically adjusts for these gaps. Non-existent times
are moved forward by 1 hour, while existing times remain unchanged. For
instance, if you call Query Availability with a startDate
of
2025-09-07T00:00:01.000
and an endDate
of 2025-09-08T00:00:02.000
, the
adjusted query will use 2025-09-07T01:00:01.000
as the new start time.
Time zone override for the endDate
and startDate
filters, in
IANA tz database format, such as
America/New_York
or UTC
.
For example, if you specify ("startDate": "2025-11-25T17:00:00+01:00"}
(note
the +01:00 offset) in combination with {"timezone": "Europe/Bucharest"}
(+02:00 offset), Query Availability adjusts the effective start time to
reflect the specified time zone. In this case, the start time in UTC would
be 2025-11-25T15:00:00
(using the +02:00 offset).
Learn more about handling Daylight Savings Time (SDK | REST).
Default: No modification applied to the endDate
and startDate
filters.
Maximum number of appointment slots to return for each date. For example, if
you specify {"slotsPerDay": 3}
, a maximum of 3 appointment slots/class events is
returned for each day that's within the query filter's date range.
List of appointment slots or class events matching the filter.
curl -X POST 'https://www.wixapis.com/availability-calendar/v1/availability/query' \
-H 'Authorization: <AUTH>' \
-d '{
"query": {
"filter": {
"serviceId": ["832adc1f-d6cc-412d-894d-f04455baec68"],
"startDate": "2023-05-20T12:17:08.912Z",
"endDate": "2023-05-25T10:13:49.549Z"
}
}
}'
{
"availabilityEntries": [
{
"slot": {
"serviceId": "832adc1f-d6cc-412d-894d-f04455baec68",
"scheduleId": "bf39eded-4d22-4c36-b8ca-a3f995673feb",
"startDate": "2023-05-20T12:30:00.000Z",
"endDate": "2023-05-20T13:00:00.000Z",
"resource": {
"id": "66bf9f11-1253-4ea8-ba43-a303578be1fb",
"name": "John Smith",
"scheduleId": "a1c0ebbb-4446-430b-85e5-291682ef68d0"
},
"location": {
"id": "3dd710bd-3480-49b4-a549-0522b035a8d7",
"name": "Headquarters",
"locationType": "OWNER_BUSINESS"
}
},
"bookable": false,
"totalSpots": 1,
"openSpots": 1,
"waitingList": {},
"bookingPolicyViolations": {
"tooEarlyToBook": false,
"tooLateToBook": true,
"bookOnlineDisabled": false
}
}
]
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.