> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # ListAvailabilityTimeSlots # Package: timeSlots # Namespace: AvailabilityTimeSlots # Method link: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md ## Permission Scopes: Read Bookings Calendar Availability: SCOPE.DC-BOOKINGS.READ-CALENDAR ## Introduction Retrieves a list of appointment time slots that match the provided filters. --- ## REST API ### Schema ``` Method: listAvailabilityTimeSlots Description: Retrieves a list of appointment time slots that match the provided filters. ### Defaults List Availability Time Slots uses the following defaults: - Sorts time slots by `localStartDate` in ascending order. - `cursorPaging.limit` set to `1000`. - Returns both bookable and un-bookable time slots. - If `bookable` filter isn't specified, bookable slots are returned first. - `fromLocalDate` is set to the current time. ### Filtering behavior The method automatically filters time slots: - **Past time slots**: Only time slots starting from the specified `fromLocalDate` are included. When you omit `fromLocalDate`, Wix Bookings uses the current time as the default. - **Resource availability**: Only time slots with at least some available resources are returned. ### Service type limitations Only appointment-based services are supported when calling List Availability Time Slots. To retrieve class availability, you can call [List Event Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-event-time-slots.md). To retrieve course availability, you can follow the [End-to-End Booking Flow for course](https://dev.wix.com/docs/api-reference/business-solutions/bookings/end-to-end-booking-flows.md#book-a-course). ### Booking policy filtering Use `bookingPolicyViolations` to filter slots based on booking restrictions defined in your [booking policies](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction.md). *Default behavior**: When you don't specify any `bookingPolicyViolations` filters, all slots are returned regardless of their booking policy status. - Set `tooEarlyToBook` to `true` to retrieve slots that can't be booked yet due to minimum advance booking time restrictions. Currently, you can't specify `earliestBookingDate` to further filter by when the slot becomes bookable. - Set `tooLateToBook` to `true` to retrieve slots that can no longer be booked due to maximum advance booking time restrictions. - Set `bookOnlineDisabled` to `true` or `false` to filter by online booking availability settings. ### Available resources Time slots aren't returned when they have no available resources. Each time slot includes details for up to 10 available resources. If there are more than 10 resources, you can call [Get Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/get-availability-time-slot.md) and filter by the resource Type GUID to get details for the remaining resources. ### Customer choices Use `customerChoices` to calculate availability based on the customer's selected service duration or add-ons. When using [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md), we recommend passing only `addOnIds` in `customerChoices` and omitting `durationInMinutes`. Wix Bookings then calculates the total duration automatically. If you specify both `addOnIds` and `durationInMinutes`, `durationInMinutes` must equal the service duration plus all selected add-on durations. ### Business hours exception Wix Bookings disregards business opening hours when all of the following conditions are met: 1. 1 or more [staff members](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/introduction.md) are needed to provide the service. 2. No other [resource type](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/introduction.md) is needed to provide the service. 3. The service doesn't have duration-based [variants](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/service-options-and-variants/introduction.md). 4. The service doesn't support [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md). In these cases, the working hours of the relevant staff member are used for availability calculation. URL: https://www.wixapis.com/_api/service-availability/v2/time-slots Method: POST Method parameters: param name: bookable | type: bookable | description: Whether the time slot is bookable according to the service's booking policies. If not specified, returns both bookable and un-bookable time slots. param name: bookingPolicyViolations | type: BookingPolicyViolations - name: tooEarlyToBook | type: boolean | description: Whether it's too early for customers to book the slot. By default, all slots are returned. Specifying `{"tooEarlyToBook": false}` returns only those that customers can already book, while specifying `{"tooEarlyToBook": true}` returns only those that can't be booked yet. - name: earliestBookingDate | type: string | description: Earliest time for booking the slot in `YYYY-MM-DDThh:mm:ss.sssZ` format. *In responses**: Contains a value when `tooEarlyToBook` is `true`, indicating the earliest time customers can book the slot. *In requests**: Don't specify a value for this field. Use `tooEarlyToBook` to filter slots that can't be booked yet due to minimum advance booking time restrictions. - name: tooLateToBook | type: boolean | description: Whether it's too late for customers to book the slot. By default, all slots are returned. Specifying `{"tooLateToBook": false}` returns only those that customers can still book, while specifying `{"tooLateToBook": true}` returns only those that can no longer be booked. - name: bookOnlineDisabled | type: boolean | description: Whether customers can book the service online. By default, both services with online booking enabled and disabled are returned. Providing the boolean set to `true` or `false` returns only matching slots. param name: cursorPaging | type: CursorPaging - name: limit | type: integer | description: Number of results to load. Default: `1000`. Max: `1000`. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. param name: customerChoices | type: CustomerChoices | description: Customer's selected choices during the booking flow. Use these values to calculate service configuration properties such as duration. - name: durationInMinutes | type: integer | description: Duration selected by the customer in minutes. Based on the customer's selection from [service options and variants](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/service-options-and-variants/introduction.md). When using [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md), we recommend passing only `addOnIds` instead of `durationInMinutes`. Wix Bookings then calculates the total duration automatically. If you specify both `addOnIds` and `durationInMinutes`, `durationInMinutes` must equal the service duration plus all selected add-on durations. - name: addOnIds | type: array | description: IDs of [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md) selected by the customer. When specifying this field, we recommend omitting `durationInMinutes`. Wix Bookings then calculates the total duration based on the service duration plus all selected add-on durations. param name: fromLocalDate | type: fromLocalDate | description: Lower boundary for `localStartDate` to include in response. Each returned time slot has a `localStartDate` within the provided `fromLocalDate` and `toLocalDate` exclusive. Required, unless you specify `cursorPaging.cursor`. Local start date in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. param name: includeResourceTypeIds | type: array | description: Resource type GUIDs to include in the response. If specified, returns up to 10 `availableResources` with matching `resourceTypeId`. This controls which resource details are included in the response but doesn't filter the time slots themselves. param name: locations | type: array | description: Locations to include in response. If not specified, returns time slots for all locations where the service is available. - name: id | type: string | description: [Location GUID](https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md). Available only for business locations. - name: name | type: string | description: Location name. - name: formattedAddress | type: string | description: Formatted location address. - name: locationType | type: LocationType | description: Location type. - enum: - BUSINESS: A business location, either the default business address, or locations defined for the business by the Business Info. - CUSTOM: The location is unique to this service and isn't defined as 1 of the business locations. - CUSTOMER: The location can be determined by the customer and isn't set up beforehand. param name: resourceTypes | type: array | description: Resource types to filter time slots. Only returns time slots that have these specific resource types available. This filters the time slots themselves, unlike `includeResourceTypeIds` which only controls response details. - name: resourceTypeId | type: string | description: [Resource type GUID](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/introduction.md). - name: resourceIds | type: array | description: Resource GUIDs. Available only if there is at least 1 resource available for the slot. param name: serviceId | type: serviceId | description: Service GUID for which to retrieve time slots. You must specify the GUID of an appointment-based service. Required, unless you specify `cursorPaging.cursor`. param name: timeSlotsPerDay | type: timeSlotsPerDay | description: Maximum number of slots to return for each day in the specified time range. If `bookable` filter isn't specified, bookable slots are returned first. param name: timeZone | type: timeZone | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database) for adjusting `fromLocalDate` and `toLocalDate`. For example, `America/New_York` or `UTC`. Default: `timeZone` specified in the business [site properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties.md). param name: toLocalDate | type: toLocalDate | description: Upper boundary for `localStartDate` to include in response. Each returned time slot has a `localStartDate` within the provided `fromLocalDate` and `toLocalDate` exclusive. Required, unless you specify `cursorPaging.cursor`. Local end date in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. Return type: ListAvailabilityTimeSlotsResponse - name: timeSlots | type: array | description: Retrieved time slots. Sorted by `localStartDate` in ascending order. When multiple slots have the same start time, no specific secondary sorting is guaranteed. - name: serviceId | type: string | description: [Service GUID] (https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction.md). Available only for single-service bookings. For multi-service bookings, this field is empty and individual service GUIDs are provided in `nestedTimeSlots`. - name: localStartDate | type: string | description: Local start date of the time slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. For multi-service bookings, this represents the start time of the first service in the sequence. In `ListAvailabilityTimeSlotEndOptions`, this is identical on every entry and equals the request's `localStartDate`. - name: localEndDate | type: string | description: Local end date of the time slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T14:00:00`. For multi-service bookings, this represents the end time of the last service in the sequence. - name: bookable | type: boolean | description: Whether customers can book the slot according to the service's [booking policies](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction.md). For multi-service bookings, this is `true` only when all services in the sequence comply with their respective booking policies. - name: location | type: Location | description: Information about where the business provides the service to the customer. In `ListAvailabilityTimeSlotEndOptions`, this is the requested location, identical on every entry. - name: id | type: string | description: [Location GUID](https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md). Available only for business locations. - name: name | type: string | description: Location name. - name: formattedAddress | type: string | description: Formatted location address. - name: locationType | type: LocationType | description: Location type. - enum: - BUSINESS: A business location, either the default business address, or locations defined for the business by the Business Info. - CUSTOM: The location is unique to this service and isn't defined as 1 of the business locations. - CUSTOMER: The location can be determined by the customer and isn't set up beforehand. - name: eventInfo | type: EventInfo | description: Information about the [event](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/introduction.md) related to the slot. Available only for classes. Not available for appointment-based services and courses. - name: eventId | type: string | description: Event GUID. - name: waitingList | type: WaitingList | description: Information about the event's waitlist. Available only if the service has a waitlist. - name: totalCapacity | type: integer | description: Total number of spots in the waitlist. - name: remainingCapacity | type: integer | description: Number of remaining spots in the waitlist. For example, an event with a waitlist for 10 people and 3 registrants, results in a remaining capacity of `7`. - name: eventTitle | type: string | description: Event title. - name: totalCapacity | type: integer | description: Total number of spots for the slot. For multi-service bookings, this is always `1` because customers book the entire service sequence as a single unit. In `ListAvailabilityTimeSlotEndOptions`, capacity reflects whether at least one resource can cover `[localStartDate, localEndDate]`; the specific resource is selected later via `GetAvailabilityTimeSlot`. - name: remainingCapacity | type: integer | description: Remaining number of spots for the slot. - For appointment bookings: Either `1` (available) or `0` (unavailable). - For classes: Total capacity minus booked spots. Doesn't account for waitlist reservations. For classes with waitlists, use `bookableCapacity` to get the actual number of spots customers can book. - For courses: Total capacity minus booked spots. Courses don't currently support waitlists. In `ListAvailabilityTimeSlotEndOptions`, capacity reflects whether at least one resource can cover `[localStartDate, localEndDate]`; the specific resource is selected later via `GetAvailabilityTimeSlot`. - name: bookableCapacity | type: integer | description: Number of spots that customers can book for the slot. Calculated as the remaining capacity minus the spots reserved for the waitlist. If the service has no waitlist, identical to `remainingCapacity`. For multi-service bookings, this is either `1` (sequence can be booked) or `0` (sequence can't be booked). In `ListAvailabilityTimeSlotEndOptions`, capacity reflects whether at least one resource can cover `[localStartDate, localEndDate]`; the specific resource is selected later via `GetAvailabilityTimeSlot`. - name: bookingPolicyViolations | type: BookingPolicyViolations | description: Information about booking policy violations for the slot. For multi-service bookings, this aggregates violations from all services in the sequence. - name: tooEarlyToBook | type: boolean | description: Whether it's too early for customers to book the slot. By default, all slots are returned. Specifying `{"tooEarlyToBook": false}` returns only those that customers can already book, while specifying `{"tooEarlyToBook": true}` returns only those that can't be booked yet. - name: earliestBookingDate | type: string | description: Earliest time for booking the slot in `YYYY-MM-DDThh:mm:ss.sssZ` format. *In responses**: Contains a value when `tooEarlyToBook` is `true`, indicating the earliest time customers can book the slot. *In requests**: Don't specify a value for this field. Use `tooEarlyToBook` to filter slots that can't be booked yet due to minimum advance booking time restrictions. - name: tooLateToBook | type: boolean | description: Whether it's too late for customers to book the slot. By default, all slots are returned. Specifying `{"tooLateToBook": false}` returns only those that customers can still book, while specifying `{"tooLateToBook": true}` returns only those that can no longer be booked. - name: bookOnlineDisabled | type: boolean | description: Whether customers can book the service online. By default, both services with online booking enabled and disabled are returned. Providing the boolean set to `true` or `false` returns only matching slots. - name: availableResources | type: array | description: List of [resources](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/introduction.md) available during the time slot. Available only for single-service bookings. For multi-service bookings, resource information is provided in `nestedTimeSlots`. __Note__: Behavior varies by method: - For [List Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md), this list is empty by default. To include resource details, specify `includeResourceTypeIds` or `resourceIds` in the request. - For [Get Availability Time Slot](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/get-availability-time-slot.md), all resources are returned by default. - **End options** (`ListAvailabilityTimeSlotEndOptions`): Always empty. The response does not surface resource lists for end options. If the customer hasn't already picked a resource earlier in the flow, call `GetAvailabilityTimeSlot` with the picked `localEndDate` to retrieve candidate resources before booking; if a resource is already chosen, pass it through to booking directly. - name: resourceTypeId | type: string | description: [Resource type GUID](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/introduction.md). - name: resources | type: array | description: Details about resources available during the time slot. Behavior varies by method: List methods (List Availability Time Slots and List Multi Service Availability Time Slots): - Empty by default. - Up to 10 resources when specifying `includeResourceTypeIds` or `resourceIds` in the request. Get methods (Get Availability Time Slots and Get Multi Service Availability Time Slots): - All resources by default. - Filtered resources when specifying `includeResourceTypeIds` or `resourceIds` in the request. - name: id | type: string | description: Resource GUID. - name: name | type: string | description: Resource name. - name: hasMoreAvailableResources | type: boolean | description: Whether there are more available resources for the slot than those listed in `resources`. - name: nestedTimeSlots | type: array | description: Nested time slots for multi-service bookings. Each nested slot represents 1 service in the sequence, ordered according to the service sequence specified in the request. Available only for multi-service bookings. Empty for single-service bookings. - name: serviceId | type: string | description: Service GUID of the nested time slot. - name: localStartDate | type: string | description: Local start date of the nested time slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. - name: localEndDate | type: string | description: Local end date of the nested time slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. - name: availableResources | type: array | description: List of [resources](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/introduction.md) available during the nested time slot. - name: scheduleId | type: string | description: The schedule GUID associated with this nested time slot. Same as the service's schedule GUID. - name: nonBookableReasons | type: NonBookableReasons | description: Information about why customers can't book the time slot. - name: noRemainingCapacity | type: boolean | description: Whether the slot is fully booked with no remaining capacity. - name: violatesBookingPolicy | type: boolean | description: Whether booking the slot violates any of the service's booking policies. - name: reservedForWaitingList | type: boolean | description: Whether the slot is reserved for the waitlist. A new customer can't book the reserved slot. - name: eventCancelled | type: boolean | description: Whether the related event is cancelled. - name: scheduleId | type: string | description: Schedule GUID associated with this time slot. Same as the service's schedule GUID. - name: allDay | type: boolean | description: Whether this time slot spans one or more full days. Populated only for class- and course-based services. Not populated for appointment-based services. When `true`, `localStartDate` is `00:00:00` of the first day and `localEndDate` is `00:00:00` of the day after the last day (exclusive). Midnight boundaries are interpreted in the event's `timeZone`. The time component should be ignored for display purposes. Default: `false` - name: timeZone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database) for adjusting `fromLocalDate` and `toLocalDate`. For example, `America/New_York` or `UTC`. Default: `timeZone` specified in the business [site properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties.md). - name: cursorPagingMetadata | type: CursorPagingMetadata | description: Paging metadata for the next page of results. Contains a cursor if there are more than 1000 results. - name: cursors | type: Cursors | description: Offset that was requested. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: prev | type: string | description: Cursor pointing to previous page in the list of results. - name: hasNext | type: boolean | description: Indicates if there are more results after the current page. If `true`, another page of results can be retrieved. If `false`, this is the last page. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: MISSING_ARGUMENTS | Description: Required request parameters are missing. Verify all required fields are provided. HTTP Code: 403 | Status Code: PERMISSION_DENIED | Application Code: UNAUTHORIZED_OPERATION | Description: The [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities.md) used to call the method doesn't have the required permissions. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: SERVICE_NOT_FOUND | Description: Couldn't find the service. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: MULTIPLE_IMPLEMENTERS_FOUND | Description: Multiple availability providers are installed. Only 1 provider can be active at a time. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: NO_IMPLEMENTERS_FOUND | Description: No availability provider is installed or configured for this operation. ``` ### Examples ### Paginate appointment availability results (next page) Retrieves the next page of available appointment slots using cursor pagination from a previous query. ```curl curl -X POST 'https://www.wixapis.com/_api/service-availability/v2/time-slots' \ -H 'Authorization: ' \ -d '{ "cursorPaging": { "cursor": "JWE.eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2Iiwia2lkIjoiSGp3NWZDbWcifQ.v62ZlVblOLN7Ba6AYq-mgwThqthA90F21nWdq77ziu9fqNmCO0T50g.7MFaJBVR6iivKV2gZuO_qg.W9dKt-UKfiocW2RfEseCyIE_mXBoFdg0LFxIYCykv8jtqkZVCcTWJ7X1sedwLIGt2FApoGxVo3gWpOr4sLbDPOpb5qMeSJKG5tppUw5Kr_squAFTFEZzDqUq1DSEbvLwxOoPZZp3YAsgX4P-Yi37UEC4OPYLNQkBOaunrGzP9IPCs-y5TONrIIa1eZud-AU85xXha5jRFH_d3s7fTJtHmHVH1W0sygQHgSyBtANsvcIouwFBGb9wSy-Ox9_O6ik87uBaKe6zNS8YQZo98WcoECmmrhCCCkJORkytuiDZGAja65GxJu9KIaLVLF6PjR7g1bvAj26kBoB-XWSk76BHt16ty68toBfUhKONMQtmtY5gF7U1CU9hsTzij0Hs2ppRVTJjhxBHzBs6aWz0gLg7bYeS7pvchJSnighIvf3WPNZn8dSuBXOs_j0g8-QAsUyyRb8YOyq_zUiHKh7PnMtaY9OM8PvVej9Vjll2Bj6pxyddw_L2EE234TwnIXh5ORfyOlM6HELDWnI-SUThqXreI2iyyUe1ml_5tuumiJ5t1kJoGnYC5bs8rlY8f5wfscJNT91Dxbb_rtLV9TL_qvpyghxlTW99y_FtpMQgfecoQ3Y.H412krucVqw99MaFH-FKSg", "limit": 5 } }' ``` ### All available appointments for a specific day Retrieves all available appointment slots for a single day to provide detailed scheduling options. ```curl curl -X POST 'https://www.wixapis.com/_api/service-availability/v2/time-slots' \ -H 'Authorization: ' \ -d '{ "includeResourceTypeIds": [ "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155" ], "locations": [ { "id": "92310bc9-10db-4163-85d2-65f83e0ddda9", "locationType": "BUSINESS" } ], "serviceId": "27f2fb02-8925-4ede-be26-991411d6c905", "fromLocalDate": "2025-09-15T00:00:00", "toLocalDate": "2025-09-15T23:59:00", "timeZone": "America/New_York", "bookable": true, "cursorPaging": { "limit": 10 } }' ``` ### Available days for appointment booking (monthly calendar view) Retrieves one available appointment slot per day for a month to support calendar interfaces. ```curl curl -X POST 'https://www.wixapis.com/_api/service-availability/v2/time-slots' \ -H 'Authorization: ' \ -d '{ "includeResourceTypeIds": [ "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155" ], "locations": [ { "id": "92310bc9-10db-4163-85d2-65f83e0ddda9", "locationType": "BUSINESS" } ], "serviceId": "27f2fb02-8925-4ede-be26-991411d6c905", "fromLocalDate": "2025-09-01T00:00:00", "toLocalDate": "2025-09-30T23:59:00", "timeZone": "America/New_York", "bookable": true, "timeSlotsPerDay": 1, "cursorPaging": { "limit": 5 } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.timeSlots.AvailabilityTimeSlots.listAvailabilityTimeSlots(options) Description: Retrieves a list of appointment time slots that match the provided filters. ### Defaults List Availability Time Slots uses the following defaults: - Sorts time slots by `localStartDate` in ascending order. - `cursorPaging.limit` set to `1000`. - Returns both bookable and un-bookable time slots. - If `bookable` filter isn't specified, bookable slots are returned first. - `fromLocalDate` is set to the current time. ### Filtering behavior The method automatically filters time slots: - **Past time slots**: Only time slots starting from the specified `fromLocalDate` are included. When you omit `fromLocalDate`, Wix Bookings uses the current time as the default. - **Resource availability**: Only time slots with at least some available resources are returned. ### Service type limitations Only appointment-based services are supported when calling List Availability Time Slots. To retrieve class availability, you can call [List Event Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-event-time-slots.md). To retrieve course availability, you can follow the [End-to-End Booking Flow for course](https://dev.wix.com/docs/api-reference/business-solutions/bookings/end-to-end-booking-flows.md#book-a-course). ### Booking policy filtering Use `bookingPolicyViolations` to filter slots based on booking restrictions defined in your [booking policies](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction.md). *Default behavior**: When you don't specify any `bookingPolicyViolations` filters, all slots are returned regardless of their booking policy status. - Set `tooEarlyToBook` to `true` to retrieve slots that can't be booked yet due to minimum advance booking time restrictions. Currently, you can't specify `earliestBookingDate` to further filter by when the slot becomes bookable. - Set `tooLateToBook` to `true` to retrieve slots that can no longer be booked due to maximum advance booking time restrictions. - Set `bookOnlineDisabled` to `true` or `false` to filter by online booking availability settings. ### Available resources Time slots aren't returned when they have no available resources. Each time slot includes details for up to 10 available resources. If there are more than 10 resources, you can call [Get Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/get-availability-time-slot.md) and filter by the resource Type GUID to get details for the remaining resources. ### Customer choices Use `customerChoices` to calculate availability based on the customer's selected service duration or add-ons. When using [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md), we recommend passing only `addOnIds` in `customerChoices` and omitting `durationInMinutes`. Wix Bookings then calculates the total duration automatically. If you specify both `addOnIds` and `durationInMinutes`, `durationInMinutes` must equal the service duration plus all selected add-on durations. ### Business hours exception Wix Bookings disregards business opening hours when all of the following conditions are met: 1. 1 or more [staff members](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/introduction.md) are needed to provide the service. 2. No other [resource type](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/introduction.md) is needed to provide the service. 3. The service doesn't have duration-based [variants](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/service-options-and-variants/introduction.md). 4. The service doesn't support [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md). In these cases, the working hours of the relevant staff member are used for availability calculation. Method parameters: param name: options | type: ListAvailabilityTimeSlotsOptions none - name: serviceId | type: string | description: Service GUID for which to retrieve time slots. You must specify the GUID of an appointment-based service. Required, unless you specify `cursorPaging.cursor`. - name: fromLocalDate | type: string | description: Lower boundary for `localStartDate` to include in response. Each returned time slot has a `localStartDate` within the provided `fromLocalDate` and `toLocalDate` exclusive. Required, unless you specify `cursorPaging.cursor`. Local start date in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. - name: toLocalDate | type: string | description: Upper boundary for `localStartDate` to include in response. Each returned time slot has a `localStartDate` within the provided `fromLocalDate` and `toLocalDate` exclusive. Required, unless you specify `cursorPaging.cursor`. Local end date in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. - name: timeZone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database) for adjusting `fromLocalDate` and `toLocalDate`. For example, `America/New_York` or `UTC`. Default: `timeZone` specified in the business [site properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties.md). - name: locations | type: array | description: Locations to include in response. If not specified, returns time slots for all locations where the service is available. - name: _id | type: string | description: [Location GUID](https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md). Available only for business locations. - name: name | type: string | description: Location name. - name: formattedAddress | type: string | description: Formatted location address. - name: locationType | type: LocationType | description: Location type. - enum: - BUSINESS: A business location, either the default business address, or locations defined for the business by the Business Info. - CUSTOM: The location is unique to this service and isn't defined as 1 of the business locations. - CUSTOMER: The location can be determined by the customer and isn't set up beforehand. - name: includeResourceTypeIds | type: array | description: Resource type GUIDs to include in the response. If specified, returns up to 10 `availableResources` with matching `resourceTypeId`. This controls which resource details are included in the response but doesn't filter the time slots themselves. - name: bookable | type: boolean | description: Whether the time slot is bookable according to the service's booking policies. If not specified, returns both bookable and un-bookable time slots. - name: bookingPolicyViolations | type: BookingPolicyViolations | description: Indicators for service's booking policy violations. Allows filtering for time slots with specific violation types based on [booking policies](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction.md)). When you don't specify `bookingPolicyViolations` filters, all slots are returned regardless of their booking policy status. - name: tooEarlyToBook | type: boolean | description: Whether it's too early for customers to book the slot. By default, all slots are returned. Specifying `{"tooEarlyToBook": false}` returns only those that customers can already book, while specifying `{"tooEarlyToBook": true}` returns only those that can't be booked yet. - name: earliestBookingDate | type: Date | description: Earliest time for booking the slot in `YYYY-MM-DDThh:mm:ss.sssZ` format. *In responses**: Contains a value when `tooEarlyToBook` is `true`, indicating the earliest time customers can book the slot. *In requests**: Don't specify a value for this field. Use `tooEarlyToBook` to filter slots that can't be booked yet due to minimum advance booking time restrictions. - name: tooLateToBook | type: boolean | description: Whether it's too late for customers to book the slot. By default, all slots are returned. Specifying `{"tooLateToBook": false}` returns only those that customers can still book, while specifying `{"tooLateToBook": true}` returns only those that can no longer be booked. - name: bookOnlineDisabled | type: boolean | description: Whether customers can book the service online. By default, both services with online booking enabled and disabled are returned. Providing the boolean set to `true` or `false` returns only matching slots. - name: timeSlotsPerDay | type: integer | description: Maximum number of slots to return for each day in the specified time range. If `bookable` filter isn't specified, bookable slots are returned first. - name: cursorPaging | type: CursorPaging | description: Cursor-based paging configuration. Enables fetching results in smaller chunks by setting a limit on the number of results. For consistent pagination behavior, use the same `limit` value throughout a pagination sequence. When specifying a new `limit` in follow-up requests, the API respects the new value. - name: limit | type: integer | description: Number of results to load. Default: `1000`. Max: `1000`. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: customerChoices | type: CustomerChoices | description: Selected customer choices for service configuration. If not specified, uses the service's default configuration. When using [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md), we recommend passing only `addOnIds` and omitting `durationInMinutes`. Wix Bookings then calculates the total duration automatically. If you specify both `addOnIds` and `durationInMinutes`, `durationInMinutes` must equal the service duration plus all selected add-on durations. - name: durationInMinutes | type: integer | description: Duration selected by the customer in minutes. Based on the customer's selection from [service options and variants](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/service-options-and-variants/introduction.md). When using [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md), we recommend passing only `addOnIds` instead of `durationInMinutes`. Wix Bookings then calculates the total duration automatically. If you specify both `addOnIds` and `durationInMinutes`, `durationInMinutes` must equal the service duration plus all selected add-on durations. - name: addOnIds | type: array | description: IDs of [add-ons](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/add-ons/introduction.md) selected by the customer. When specifying this field, we recommend omitting `durationInMinutes`. Wix Bookings then calculates the total duration based on the service duration plus all selected add-on durations. - name: resourceTypes | type: array | description: Resource types to filter time slots. Only returns time slots that have these specific resource types available. This filters the time slots themselves, unlike `includeResourceTypeIds` which only controls response details. - name: resourceTypeId | type: string | description: [Resource type GUID](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/introduction.md). - name: resourceIds | type: array | description: Resource GUIDs. Available only if there is at least 1 resource available for the slot. Return type: PROMISE - name: timeSlots | type: array | description: Retrieved time slots. Sorted by `localStartDate` in ascending order. When multiple slots have the same start time, no specific secondary sorting is guaranteed. - name: serviceId | type: string | description: [Service GUID] (https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction.md). Available only for single-service bookings. For multi-service bookings, this field is empty and individual service GUIDs are provided in `nestedTimeSlots`. - name: localStartDate | type: string | description: Local start date of the time slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. For multi-service bookings, this represents the start time of the first service in the sequence. In `ListAvailabilityTimeSlotEndOptions`, this is identical on every entry and equals the request's `localStartDate`. - name: localEndDate | type: string | description: Local end date of the time slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T14:00:00`. For multi-service bookings, this represents the end time of the last service in the sequence. - name: bookable | type: boolean | description: Whether customers can book the slot according to the service's [booking policies](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policies/introduction.md). For multi-service bookings, this is `true` only when all services in the sequence comply with their respective booking policies. - name: location | type: Location | description: Information about where the business provides the service to the customer. In `ListAvailabilityTimeSlotEndOptions`, this is the requested location, identical on every entry. - name: _id | type: string | description: [Location GUID](https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md). Available only for business locations. - name: name | type: string | description: Location name. - name: formattedAddress | type: string | description: Formatted location address. - name: locationType | type: LocationType | description: Location type. - enum: - BUSINESS: A business location, either the default business address, or locations defined for the business by the Business Info. - CUSTOM: The location is unique to this service and isn't defined as 1 of the business locations. - CUSTOMER: The location can be determined by the customer and isn't set up beforehand. - name: eventInfo | type: EventInfo | description: Information about the [event](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/introduction.md) related to the slot. Available only for classes. Not available for appointment-based services and courses. - name: eventId | type: string | description: Event GUID. - name: waitingList | type: WaitingList | description: Information about the event's waitlist. Available only if the service has a waitlist. - name: totalCapacity | type: integer | description: Total number of spots in the waitlist. - name: remainingCapacity | type: integer | description: Number of remaining spots in the waitlist. For example, an event with a waitlist for 10 people and 3 registrants, results in a remaining capacity of `7`. - name: eventTitle | type: string | description: Event title. - name: totalCapacity | type: integer | description: Total number of spots for the slot. For multi-service bookings, this is always `1` because customers book the entire service sequence as a single unit. In `ListAvailabilityTimeSlotEndOptions`, capacity reflects whether at least one resource can cover `[localStartDate, localEndDate]`; the specific resource is selected later via `GetAvailabilityTimeSlot`. - name: remainingCapacity | type: integer | description: Remaining number of spots for the slot. - For appointment bookings: Either `1` (available) or `0` (unavailable). - For classes: Total capacity minus booked spots. Doesn't account for waitlist reservations. For classes with waitlists, use `bookableCapacity` to get the actual number of spots customers can book. - For courses: Total capacity minus booked spots. Courses don't currently support waitlists. In `ListAvailabilityTimeSlotEndOptions`, capacity reflects whether at least one resource can cover `[localStartDate, localEndDate]`; the specific resource is selected later via `GetAvailabilityTimeSlot`. - name: bookableCapacity | type: integer | description: Number of spots that customers can book for the slot. Calculated as the remaining capacity minus the spots reserved for the waitlist. If the service has no waitlist, identical to `remainingCapacity`. For multi-service bookings, this is either `1` (sequence can be booked) or `0` (sequence can't be booked). In `ListAvailabilityTimeSlotEndOptions`, capacity reflects whether at least one resource can cover `[localStartDate, localEndDate]`; the specific resource is selected later via `GetAvailabilityTimeSlot`. - name: bookingPolicyViolations | type: BookingPolicyViolations | description: Information about booking policy violations for the slot. For multi-service bookings, this aggregates violations from all services in the sequence. - name: tooEarlyToBook | type: boolean | description: Whether it's too early for customers to book the slot. By default, all slots are returned. Specifying `{"tooEarlyToBook": false}` returns only those that customers can already book, while specifying `{"tooEarlyToBook": true}` returns only those that can't be booked yet. - name: earliestBookingDate | type: Date | description: Earliest time for booking the slot in `YYYY-MM-DDThh:mm:ss.sssZ` format. *In responses**: Contains a value when `tooEarlyToBook` is `true`, indicating the earliest time customers can book the slot. *In requests**: Don't specify a value for this field. Use `tooEarlyToBook` to filter slots that can't be booked yet due to minimum advance booking time restrictions. - name: tooLateToBook | type: boolean | description: Whether it's too late for customers to book the slot. By default, all slots are returned. Specifying `{"tooLateToBook": false}` returns only those that customers can still book, while specifying `{"tooLateToBook": true}` returns only those that can no longer be booked. - name: bookOnlineDisabled | type: boolean | description: Whether customers can book the service online. By default, both services with online booking enabled and disabled are returned. Providing the boolean set to `true` or `false` returns only matching slots. - name: availableResources | type: array | description: List of [resources](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/introduction.md) available during the time slot. Available only for single-service bookings. For multi-service bookings, resource information is provided in `nestedTimeSlots`. __Note__: Behavior varies by method: - For [List Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md), this list is empty by default. To include resource details, specify `includeResourceTypeIds` or `resourceIds` in the request. - For [Get Availability Time Slot](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/get-availability-time-slot.md), all resources are returned by default. - **End options** (`ListAvailabilityTimeSlotEndOptions`): Always empty. The response does not surface resource lists for end options. If the customer hasn't already picked a resource earlier in the flow, call `GetAvailabilityTimeSlot` with the picked `localEndDate` to retrieve candidate resources before booking; if a resource is already chosen, pass it through to booking directly. - name: resourceTypeId | type: string | description: [Resource type GUID](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/introduction.md). - name: resources | type: array | description: Details about resources available during the time slot. Behavior varies by method: List methods (List Availability Time Slots and List Multi Service Availability Time Slots): - Empty by default. - Up to 10 resources when specifying `includeResourceTypeIds` or `resourceIds` in the request. Get methods (Get Availability Time Slots and Get Multi Service Availability Time Slots): - All resources by default. - Filtered resources when specifying `includeResourceTypeIds` or `resourceIds` in the request. - name: _id | type: string | description: Resource GUID. - name: name | type: string | description: Resource name. - name: hasMoreAvailableResources | type: boolean | description: Whether there are more available resources for the slot than those listed in `resources`. - name: nestedTimeSlots | type: array | description: Nested time slots for multi-service bookings. Each nested slot represents 1 service in the sequence, ordered according to the service sequence specified in the request. Available only for multi-service bookings. Empty for single-service bookings. - name: serviceId | type: string | description: Service GUID of the nested time slot. - name: localStartDate | type: string | description: Local start date of the nested time slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. - name: localEndDate | type: string | description: Local end date of the nested time slot in `YYYY-MM-DDThh:mm:ss` [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2026-01-30T13:30:00`. - name: availableResources | type: array | description: List of [resources](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/introduction.md) available during the nested time slot. - name: scheduleId | type: string | description: The schedule GUID associated with this nested time slot. Same as the service's schedule GUID. - name: nonBookableReasons | type: NonBookableReasons | description: Information about why customers can't book the time slot. - name: noRemainingCapacity | type: boolean | description: Whether the slot is fully booked with no remaining capacity. - name: violatesBookingPolicy | type: boolean | description: Whether booking the slot violates any of the service's booking policies. - name: reservedForWaitingList | type: boolean | description: Whether the slot is reserved for the waitlist. A new customer can't book the reserved slot. - name: eventCancelled | type: boolean | description: Whether the related event is cancelled. - name: scheduleId | type: string | description: Schedule GUID associated with this time slot. Same as the service's schedule GUID. - name: allDay | type: boolean | description: Whether this time slot spans one or more full days. Populated only for class- and course-based services. Not populated for appointment-based services. When `true`, `localStartDate` is `00:00:00` of the first day and `localEndDate` is `00:00:00` of the day after the last day (exclusive). Midnight boundaries are interpreted in the event's `timeZone`. The time component should be ignored for display purposes. Default: `false` - name: timeZone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database) for adjusting `fromLocalDate` and `toLocalDate`. For example, `America/New_York` or `UTC`. Default: `timeZone` specified in the business [site properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties.md). - name: cursorPagingMetadata | type: CursorPagingMetadata | description: Paging metadata for the next page of results. Contains a cursor if there are more than 1000 results. - name: cursors | type: Cursors | description: Offset that was requested. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: prev | type: string | description: Cursor pointing to previous page in the list of results. - name: hasNext | type: boolean | description: Indicates if there are more results after the current page. If `true`, another page of results can be retrieved. If `false`, this is the last page. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: MISSING_ARGUMENTS | Description: Required request parameters are missing. Verify all required fields are provided. HTTP Code: 403 | Status Code: PERMISSION_DENIED | Application Code: UNAUTHORIZED_OPERATION | Description: The [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities.md) used to call the method doesn't have the required permissions. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: SERVICE_NOT_FOUND | Description: Couldn't find the service. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: MULTIPLE_IMPLEMENTERS_FOUND | Description: Multiple availability providers are installed. Only 1 provider can be active at a time. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: NO_IMPLEMENTERS_FOUND | Description: No availability provider is installed or configured for this operation. ``` ### Examples ### listAvailabilityTimeSlots ```javascript import { availabilityTimeSlots } from '@wix/bookings'; async function listAvailabilityTimeSlots(options) { const response = await availabilityTimeSlots.listAvailabilityTimeSlots(options); }; ``` ### listAvailabilityTimeSlots (with elevated permissions) ```javascript import { availabilityTimeSlots } from '@wix/bookings'; import { auth } from '@wix/essentials'; async function myListAvailabilityTimeSlotsMethod(options) { const elevatedListAvailabilityTimeSlots = auth.elevate(availabilityTimeSlots.listAvailabilityTimeSlots); const response = await elevatedListAvailabilityTimeSlots(options); } ``` ### listAvailabilityTimeSlots (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { availabilityTimeSlots } from '@wix/bookings'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { availabilityTimeSlots }, // Include the auth strategy and host as relevant }); async function listAvailabilityTimeSlots(options) { const response = await myWixClient.availabilityTimeSlots.listAvailabilityTimeSlots(options); }; ``` ---