Sample Flows

This article provides sample flows focusing on the technical details of creating appointment, class session, and course bookings using Create Booking. It also shows how to create and reschedule multi-service bookings. For a complete step-by-step overview of the full booking process (including service selection, availability checks, and payment), see End-to-End Booking Flows.

Book an appointment

To create a booking for an appointment:

1. Identify the business time zone and relevant service ID. For example, as described in End-to-End Booking Flows.
2. Call List Availability Time Slots specifying serviceId, timeZone, fromLocalDate, and toLocalDate as filters. Save the relevant time slot details.
3. To obtain the selected slot's full capacity and booking-policy status, call Get Availability Time Slot. Specify the selected slot's localStartDate and localEndDate.
4. Call Create Booking. Specify the slot's startDate, endDate, resource and location in booking.bookedEntity.slot. If the slot's availability hasn't changed since calling List Availability Time Slots, the call succeeds and the status of the booking is CREATED.

Book a class session

To create a booking for a class session:

1. Identify the business time zone and relevant service ID. For example, as described in End-to-End Booking Flows.
2. Call List Event Time Slots specifying serviceId, timeZone, fromLocalDate, toLocalDate, and the number of openSpots the customer intends to book as filters. Save the eventId from the selected time slot.
3. To obtain the selected slot's full capacity and booking-policy status, call Get Event Time Slot. Specify eventId to get detailed information about the class session.
4. Call Create Booking specifying the event ID in booking.bookedEntity.slot.eventId. If the class session's availability hasn't changed since calling List Event Time Slots, the call succeeds and the status of the booking is CREATED.

Book a course

To create a booking for a course:

1. Identify the relevant business time zone, service ID, service default capacity, and service schedule ID. For example, as described in End-to-End Booking Flows.
2. Retrieve all bookings for this service with Query Extended Bookings and calculate how many people are already booked for the course.
3. Make sure the intended numberOfParticipants doesn't exceed the remaining places.
4. Call Create Booking specifying the relevant schedule ID as booking.bookedEntity.scheduleId. If the course's availability hasn't changed since calling Query Extended Bookings, the call succeeds and the status of the booking is CREATED.

Create a multi-service booking

To create a multi-service booking (for example, a spa package with massage, facial, and manicure):

1. Identify the business time zone and relevant service IDs for each service in the package. For example, as described in the single-service appointment end-to-end booking flow.
2. Call List Multi Service Availability Time Slots specifying services with serviceId for each service, fromLocalDate, toLocalDate, timeZone, and location with locationType.
3. Call Create Multi Service Booking with an array of bookings (minimum 2, maximum 8) and multiServiceBookingType set to SEQUENTIAL_BOOKINGS. You must specify individual slot timing for each service with no gaps between bookings. If availability hasn't changed, the call succeeds and each single-service booking has a status of CREATED.

Reschedule a multi-service booking and add a single-service booking

To reschedule a multi-service booking and then add an additional single-service booking (for example, moving a spa package to a different time and adding a pedicure that couldn't be scheduled at the original end time):

1. Call Get Multi Service Booking to retrieve the current multi-service booking details, including all single-service booking IDs and their current revision numbers.
2. For each service you want to reschedule, identify the new slot details (scheduleId, startDate, endDate, resource, and location). For example, as described in the single-service appointment end-to-end booking flow.
3. Call List Multi Service Availability Time Slots specifying services with serviceId for each service, fromLocalDate, toLocalDate, timeZone, and location with locationType to verify availability for the new timing, ensuring all services can still be scheduled sequentially.
4. To obtain the selected multi-service slot's full capacity and booking-policy status, call Get Multi Service Availability Time Slot. Specify the exact localStartDate and localEndDate values from the selected slot.
5. Call Reschedule Multi Service Booking specifying the ID of the multi-service booking and an array of rescheduleBookingsInfo. For each single-service booking to reschedule, include the bookingId, current revision number, and new slot details with exact timing to maintain sequential scheduling with all services back-to-back and no gaps or overlaps.
6. Make sure you have an independent single-service booking to add to the package. For example, by following the single-service appointment end-to-end booking flow. Ensure the booking timing is compatible with the multi-service booking's sequential schedule and the booking has a compatible status.
7. Call Add Bookings to Multi Service Booking specifying the multiServiceBookingId and an array of bookings containing the bookingId and revision number. The existing timing of the added booking must be compatible with the multi-service booking's sequential schedule for successful integration.

Handle payments

Once you've created a booking, handle payments using Wix eCommerce or your own custom checkout flow. For step-by-step instructions for payment processing, see the End-to-End Booking Flows article.

Handle double booking conflicts

When scheduling conflicts occur and a booking's doubleBooked flag is set to true, you can follow this flow to resolve the conflict and handle necessary refunds.

To detect and resolve double booking conflicts:

1. Detect conflicts by listening for these events:

   • Booking Confirmed: Check if booking.doubleBooked is true.
   • Booking Marked as Pending: Check if booking.doubleBooked is true.

   Important: Only start conflict resolution for events where booking.flowControlSettings.skipAvailabilityValidation is false or undefined. Events with skipAvailabilityValidation: true indicate that force resolution was already applied, so processing them again would create an infinite loop.

2. Determine resolution options by calling Bulk Calculate Allowed Actions, specifying the relevant booking ID. If both cancel and reschedule flags are false, standard resolution isn't available and you'll need to force resolution.

3. Choose a resolution approach:

   • Standard reschedule.
   • Standard cancel.
   • Force resolution.

4. Notify the customer and business about the conflict resolution.

Standard reschedule

Move an appointment or class booking to a different available time slot that works for the customer. Course bookings can't be rescheduled.

1. Identify alternative time slots using the Time Slots V2 API:
   • For appointments: Call List Availability Time Slots.
   • For class events: Call List Event Time Slots.
2. Show alternatives to the customer and let them choose.
3. After customer selection, verify the chosen slot is still available:
   • For appointments: Call Get Availability Time Slot.
   • For classes: Call Get Event Time Slot.
4. Reschedule the booking to the new time slot.
5. If the booking was PENDING and used a custom checkout, call Confirm Or Decline Booking to finalize the booking status after rescheduling.

Standard cancel

Cancel the conflicted booking and process any necessary refunds.

1. Call Cancel Booking. Use flow control settings to protect the customer from penalties due to the conflict:
   • withRefund: true to ensure customers receive refunds for pricing plans payments since the conflict wasn't their fault.
   • waiveCancellationFee: true to waive the cancellation fee as the customer shouldn't be penalized for a booking conflict.

Force resolution

Override availability validation to confirm or decline the booking when standard options aren't available. Force resolution options differ significantly between checkout types:

For eCommerce checkouts

• Confirmation option: Call Reschedule Booking, specifying the existing slot and flowControlSettings: { skipAvailabilityValidation: true }. If the service requires manual approval, also specify skipBusinessConfirmation: true.
• Decline option:
  • Pricing plan payments: We recommend implementing the standard Cancel Booking call described above with withRefund: true instead of force declining. Use ignoreCancellationPolicy: true if you need to override timing restrictions.
  • Other payment methods: Manually issue a refund using the eCommerce Orders API. For step-by-step instruction, you can refer to these sample flows. Then, Wix Bookings automatically updates the booking's status to REFUNDED.

For custom checkouts

• Confirmation option: Call Confirm Or Decline Booking, specifying flowControlSettings: { skipAvailabilityValidation: true } to confirm regardless of conflicts.
• Decline option:
  1. Process any necessary refunds through the external payment system.
  2. Update the eCommerce order to reflect the refund. For step-by-step instructions, you can refer to these sample flows. Then, Wix Bookings automatically updates the booking status to REFUNDED.