Flow: Single-Service Booking

This article describes how Wix Bookings handles single-service bookings, from service selection through booking confirmation. The flow shows what happens automatically when using the Wix Bookings app, and which API methods are involved at each step for developers implementing custom booking experiences.

Note: On Wix sites, bookings can be managed by the Wix Bookings app.

Before you begin

Single-service booking flow

The following diagram shows the full single-service booking flow.

Standard Booking Flow

The following steps describe the complete single-service booking flow from service discovery through booking confirmation and calendar integration.

Step 1 | Display service list

Display available services to the customer for selection.

Action: Call Query Services to retrieve available services and display them to the customer.

Result: The customer selects a service. Save relevant service details including id, type, form.id, payment configuration, staffMemberIds, schedule.id, bookingPolicy.id, and locations.

Step 2 | Display service variants

Retrieve available service variants and display them to the customer for selection.

Action: Call Get Service Options And Variants By Service Id to retrieve variants for the service. If the service has variants, display them to the customer.

Result: The customer selects variants and the number of participants per variant.

Learn more about service variants and options.

Step 3 | Display available add-ons

Retrieve available service add-ons and display them to the customer for selection.

Action: Call List Add On Groups by Service ID to retrieve all addOns available for the service. If the service has add-ons, display them to the customer.

Result: The customer selects add-ons.

Learn more about add-ons.

Step 4 | Display available slots

Display available time slots to the customer for selection.

Action: Check availability depending on the selected service type:

  • For appointments: Call List Availability Time Slots, specifying serviceId, "bookable": true, fromLocalDate, toLocalDate, and the relevant timeZone as filters. If the customer has selected duration-based variants or add-ons, also specify the relevant customerChoices. This retrieves available slots based on staff and resource availability. Display the time slots to the customer.
  • For class events: Call List Event Time Slots, specifying serviceId, timeZone, fromLocalDate, toLocalDate, and the number of openSpots the customer intends to book as filters to retrieve scheduled class sessions with available capacity.
  • For courses: Compare the requested number of participants against the service's defaultCapacity. Retrieve all bookings for this service with Query Extended Bookings, specifying bookedEntity.item.schedule.serviceId as filter. Calculate the total number of participants already booked by adding up the attendance.numberOfAttendees from all extended bookings. Then, subtract this total from the service's defaultCapacity to determine the number of remaining spots. Ensure the intended number of participants doesn't exceed the remaining places.

Result: The customer selects their preferred available time slot or course.

Step 5 | Display booking form

Display the booking form to the customer and collect their information.

Action: Call Get Form Summary with the booking form ID from the selected service. Display the retrieved booking form to the customer.

Result: The customer enters their contact details, number of participants, and any service-specific requirements into the booking form. Collect form information as a JSON object using the field names from the form schema in preparation for the booking creation. Learn more about how Wix Bookings integrates with Wix Forms.

Step 6 | Validate availability

Validate the selected time slot to ensure it's still available before creating the booking.

Action: Revalidate service availability depending on the selected service type:

  • For appointments: Call Get Availability Time Slot, specifying the selected slot's localStartDate and localEndDate to verify the specific slot is still open.
  • For class events: Call Get Event Time Slot, specifying eventId to revalidate availability for the selected class event.
  • For courses: Recheck the requested number of participants against remaining capacity as described in step 4.

Possible results:

  • Time slot or course still available. Continue to step 7.
  • Time slot or course no longer available. Return to step 4 to select a different appointment slot, class event, or course.

Step 7 | Create booking

Create a booking with the selected service, time slot, and customer information.

Action: Call Create Booking with the selected service and form data. For appointments and class events, also specify the selected slot. If the customer has selected a variant, specify all selected participantsChoices.serviceChoices. If the customer has selected add-ons, specify their IDs in bookedAddOns.id.

Result:

  • The booking has "status": "CREATED" and isn't visible in the booking calendar. Save the booking ID.
  • Wix Bookings automatically calls Create Submission with the form data specified in the Create Booking request and saves the formSubmissionId on the booking.

Learn more about how you can retrieve submitted booking forms.

Step 8 | Optional: Retrieve custom pricing

Wix Bookings automatically checks if the business has set up custom pricing via the Pricing service plugin.

Action: If the business uses custom pricing logic, Wix Bookings calls Calculate Price to retrieve the custom pricing from the service plugin implementation.

Result: The service plugin implementor returns the custom price for the booking.

Step 9 | Create an eCommerce checkout

Create a checkout to initiate the eCommerce purchase flow for the booking.

Action: Call Create Checkout, specifying the Wix Bookings business solution app ID as catalogReference.appId and the booking ID as catalogReference.catalogItemId. Save the checkout ID.

Result: Checkout created.

Alternatively, you can also create a custom checkout. Learn more about handling payments with a custom checkout.

Step 10 | Customer completes purchase

Redirect the customer to the checkout page so they complete the eCommerce purchase flow.

Action: Call Get Checkout URL to generate the checkout page URL and redirect the customer.

Result: The customer completes the purchase. Wix eCommerce automatically creates an order and charges the customer.

Step 11 | Handle booking confirmation

After the customer completes their purchase, Wix Bookings finalizes the booking. Once the Order Approved event triggers, Wix Bookings automatically calls Confirm Or Decline Booking. The resulting booking status depends on the service's approval configuration and current availability.

Action: Listen to the Booking Confirmed, Booking Declined, and Booking Marked As Pending events to get notified when the booking status changes.

Automatic approval flow:

Wix Bookings validates availability:

  • If the slot is available, booking status updates to CONFIRMED and appears in the booking calendar.
  • If there's a double booking conflict:
    • Unpaid bookings: Status updates to DECLINED and the customer is notified.
    • Paid or partially paid bookings: Status updates to CONFIRMED with doubleBooked set to true. The business receives a notification to resolve the conflict. Learn more about handling double booking conflicts.

Manual approval flow:

Wix Bookings updates booking status to PENDING. The business receives a notification to review the request:

  • If the business confirms, status updates to CONFIRMED and the booking appears in the calendar.
  • If the business declines, status updates to DECLINED and the customer is notified.

Results

After implementing this flow, customers can discover services, select time slots, complete booking forms, and receive confirmation notifications for their bookings. Wix users can manage bookings through the Booking calendar, while customers can view and manage their bookings through the members area.

See also

Did this help?