About the Wix Bookings Availability Calendar API

With the Wix Bookings Availability Calendar API, you can retrieve the availability of a calendar's sessions.

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

Terminology

  • Booking: Information about the service that the customer has booked. Includes details about the time, location, participants, and price.
  • Service: Online or in-person business offerings, such as courses and private sessions. For example, a fitness studio may offer a 1-hour yoga class, a 45 minute HIIT training session, and a 30 minute 1-on-1 personal training. Bookings offers 3 types of services:
    • Appointments: Appointments take place whenever a customer books a specific time slot. For example, your hair salon may be open for business from 9:00 AM to 7:00 PM and a customer can book a session at any available time during the day.
    • Classes: Classes can be scheduled on different days, at different times, with different resources, such as staff members. Customers can sign up for single sessions or a class's recurring sessions. For example, a language school offers a beginner's Spanish class every Monday at 8:00 PM. Clients can join the session they want and don't have to commit to attending all sessions.
    • Courses: A limited number of sessions for the same service that starts and ends on a particular day. Customers sign up for the entire course and not one session. For example, a 12-session introductory course to Pilates, starting on February 1st and ending on March 17th.
  • Schedule: A collection of all sessions that belong to the same class, course, appointment, or resource. Schedules also comprise available slots that can still be booked.
    • Session: An occupied period of time in a schedule. Sessions are the building blocks of appointments, classes, and courses. Each of these types of services comprise sessions. The collection of related sessions for a service represent the service's schedule.
    • Slot: An available period of time in a schedule that can be booked by a customer. While this includes existing sessions that are available for booking, it can also represent a period of time that can be booked based on the availability of a resource, such as a barber with appointments of 30 minutes each that are open for booking every weekday between 8:00 - 17:00. These slots are calculated according to the constraints of the schedule.
  • Calendar: General overview about the availability and bookings of the business, including its services and resources. Manage your appointments, classes and courses on the calendar.
  • Resource: Business asset like a staff member, room, or equipment that's needed to provide a service.
  • Bookings Policy: Terms the business wants to enforce when customers try to book a service. For example, how far in advance customers may book a service or until what point before the start of a session customers can cancel.
  • Locked Sessions: Sessions that customers cannot book due to business reasons, such as the session being full and having a waitlist, or because an administrator wants to manually screen each customer before adding a customer to a session.
Was this helpful?
Yes
No

Calendar Availability: Supported Fields, Filters, and Sorting

Query endpoints allow you to filter and sort results based on slot availability properties. This article covers field support 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:

FieldRequiredFilterableSortableNotes
startDateRequiredNot filterableSortableReturns slots that start at, or after, this date. If timezone is specified, the startDate for the query is according to the local date and time, which means that the timezone offset in the format is ignored.
endDateRequiredReturns slots that end at, or before, this date. If the timezone is specified, the endDate for the query is according to the local date and time, which means that the timezone offset in the format is ignored.
serviceIdRequiredSupports multiple values, returned if slot is provided.
resourceId
scheduleIdNot filterableReturned if slot is provided.
sessionIdNot filterable
timezoneNot filterable
resourceNot filterable
bookableWhen 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.idSupports multiple values.
openSpotsReturns slots with at least this number of open spots.
totalSpotsNot filterable
waitingListNot filterable
bookingPolicyViolationsNot 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: Query Availability

Was this helpful?
Yes
No

Slot Availability Object

Properties
slotobject
The slot for the corresponding session, when the session is either a single session or a specific session generated from a recurring session.

bookableboolean
Whether the slot is bookable. Bookability is determined by checking a session's open slots and booking policies. Locks are not taken into account.

totalSpotsintegerformat int32
Total number of spots for this slot. For example, if a session has a total of 10 spots and 3 spots are booked, spotsTotal is 10 and openSpots is 7.

openSpotsintegerformat int32
Number of open spots for this slot.

waitingListobject
An object describing the slot's waitlist and its occupancy.

bookingPolicyViolationsobject
Booking policy violations for the slot.

lockedboolean
Indicates whether the slot is locked because a waitlist exists. When a slot frees up, the slot is offered to the next customer on the waitlist. Read-only.

isFromV2boolean
Was this helpful?
Yes
No

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

The Calendar Availability 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 wait-list, 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 wait-list 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 time 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 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 Query Availability endpoint 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:
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.
Endpoint
POST
https://www.wixapis.com/bookings/availability-calendar/v1/availability/query

Was this helpful?
Yes
No