POST

Query Availability

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 appointment slots or class events that match specified filters.

Course limitations

Course events can't be retrieved with this method. Follow this sample flow* (SDK | REST) to check course availability.

Query filter

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.

Limit the number of slots returned per day

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.

Unavailable slots

By default, both available and unavailable appointment slots/ class events are returned. To retrieve only available slots/events, specify {"bookable": true} in the filter.

Sorting

Slots/events can be sorted only by startDate. Unavailable slots/events always appear after available ones.

Availability calculation

Wix Bookings calculates availability differently for appointment-based services and classes.

Appointment availability

An appointment slot is bookable if:

  • The slot's startDate is later than or equal to query.filter.startDate.
  • The slot's endDate is before or equal to query.filter.endDate.
  • The service's onlineBooking.enabled is true.
  • The service's early/late booking policies are either not enabled or the current time is within the defined limits.

Class event availability

A class event is bookable if:

  • The event's startDate is later than or equal to query.filter.startDate.
  • The event's endDate is before or equal to query.filter.endDate.
  • The event's remainingCapacity is greater than 0.
  • The service's onlineBooking.enabled is true.
  • The service's early/late booking policies are either not enabled or the current time is within the defined limits.

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.

Daylight Savings Time (DST)

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.

Permissions
Manage Bookings Services and Settings
Manage Bookings - all permissions
Read Bookings - all read permissions
Manage Bookings
Read Bookings - Public Data
Read Bookings - Including Participants
Read Bookings Calendar Availability
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/availability-calendar/v1/availability/query
Body Params
queryQueryRequired

Query options. Refer to the supported filters article* (SDK | REST) for a complete list of supported filters.

timezonestring

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.

slotsPerDayintegerformat int32

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.

Response Object
availabilityEntriesArray <SlotAvailability>

List of appointment slots or class events matching the filter.

Request
cURL
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"
        }
      }
    }'
Response
JSON
{
  "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
      }
    }
  ]
}
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?