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. Display the time slots and let the customer select one.
3. Call Wix Forms' Get Form Summary, specifying the service's form.id, to retrieve the booking form fields. Display the form to the customer and collect their input. Construct a JSON object using the exact values from formSummary.fields.target as keys. Learn more about How Bookings Integrates with Wix Forms.
4. Call Get Availability Time Slot, specifying the selected slot's localStartDate and localEndDate, to validate the slot is still available.
5. Call Create Booking. Specify the slot's startDate, endDate, resource and location in booking.bookedEntity.slot, and pass the constructed JSON object as formSubmission. The call succeeds if the slot hasn't been booked by another customer since calling Get Availability Time Slot, and the booking status 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. Display the time slots and let the customer select one. Save the eventId from the selected time slot.
3. Call Wix Forms' Get Form Summary, specifying the service's form.id, to retrieve the booking form fields. Display the form to the customer and collect their input. Construct a JSON object using the exact values from formSummary.fields.target as keys. Learn more about How Bookings Integrates with Wix Forms.
4. Call Get Event Time Slot, specifying eventId, to validate the class session is still available.
5. Call Create Booking specifying the event ID in booking.bookedEntity.slot.eventId, and pass the constructed JSON object as formSubmission. The call succeeds if the class session hasn't filled up since calling Get Event Time Slot, and the booking status 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. Call Query Extended Bookings to retrieve all bookings for this service and calculate how many people are already booked. Make sure the intended numberOfParticipants doesn't exceed the remaining places.
3. Call Wix Forms' Get Form Summary, specifying the service's form.id, to retrieve the booking form fields. Display the form to the customer and collect their input. Construct a JSON object using the exact values from formSummary.fields.target as keys. Learn more about How Bookings Integrates with Wix Forms.
4. Recheck availability by comparing against the service's defaultCapacity to ensure spots are still available.
5. Call Create Booking specifying the relevant schedule ID as booking.bookedEntity.scheduleId, and pass the constructed JSON object as formSubmission. The call succeeds if the course hasn't filled up since the availability check, and the booking status 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.
2. Handle refunds based on the payment method used:
   • Wix eCommerce checkouts: Issue a refund using the eCommerce Orders API. For step-by-step instructions, see the Order Billing sample flows. Wix Bookings automatically updates the booking's status to REFUNDED.
   • Custom checkouts: Process the refund through your external payment system, then update the eCommerce order to reflect the refund.

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.