Sample Flows

This article presents a use case and corresponding sample flow that you can support. It provides a useful starting point as you plan your implementation.

Provide custom time slot configurations during booking

This flow shows what happens when a customer views available booking times, including when they select service variants or add-ons.

1. A customer opens the Bookings calendar on a site.
2. The customer selects a service, and optionally chooses a duration variant and/or add-ons.
3. Wix calls your List Availability Time Slot Configurations implementation with services.serviceId for each service. If the customer made choices, the request also includes services.customerChoices with:
   • durationInMinutes: The duration selected by the customer from the service's options and variants.
   • addOnIds: IDs of selected add-ons.
4. Your implementation returns a configuration for each service, specifying duration, bufferTimeInMinutes, splitIntervalInMinutes, resourceTypes, and locations.
5. To set duration.defaultInMinutes, your implementation must calculate the correct value based on the customer choices. The Time Slots API forwards customer choices to your implementation without processing them, so your implementation is responsible for using them to calculate the correct duration:
   • Only addOnIds: Calculate the total duration as the service's base duration from service.schedule.availabilityConstraints.sessionDurations plus the durationInMinutes of all selected add-ons.
   • Only durationInMinutes: Use it directly as the slot duration.
   • Both addOnIds and durationInMinutes: The durationInMinutes value already includes the service duration plus all selected add-on durations. Use it directly.
   • Neither: Use the service's default duration from service.schedule.availabilityConstraints.sessionDurations.
6. Wix calculates available time slots based on your configuration, resource schedules, and existing bookings.
7. The customer selects a slot and proceeds to book.

Provide duration range configurations for flexible-duration services

This flow shows what happens when a customer views available booking times for a service that supports a bookable duration range. Instead of fixed durations, the customer selects how long they want to book within a minimum and maximum range.

1. A customer opens the Bookings calendar on a site for a flexible-duration service (for example, a conference room that can be booked for 1 to 4 hours).
2. Wix calls your List Availability Time Slot Configurations implementation with services.serviceId for the service.
3. Your implementation returns a configuration that includes both duration and durationUnit. For an hourly service:
   • duration.defaultInMinutes: The minimum bookable duration in minutes. For example, 60 for a 1-hour minimum. Wix uses this to calculate available start times.
   • durationUnit.unitType: HOUR
   • durationUnit.minDuration: Minimum bookable duration in minutes. For example, 60 for a 1-hour minimum.
   • durationUnit.maxDuration: Maximum bookable duration in minutes. For example, 240 for a 4-hour maximum.
4. Wix uses duration.defaultInMinutes to calculate available start times and displays them to the customer.
5. After the customer selects a start time, Wix uses durationUnit to calculate available end times based on the maximum duration and resource availability.
6. The customer selects an end time and proceeds to book.

For daily services, return only durationUnit and leave duration empty. Set durationUnit.unitType to DAY and specify minDuration and maxDuration in days. For example, 1 for a 1-day minimum and 5 for a 5-day maximum. Wix then calculates availability as full-day windows instead of time slots.