Tutorial | Create a Custom Bookings Experience for Appointment Services

Using the JavaScript SDK Bookings APIs, you can create a custom booking experience for the appointment-based services you offer on your site. This tutorial demonstrates how to build a complete booking flow that integrates with Wix eCommerce for payment processing.

What you'll build

By the end of this tutorial, you'll have a fully functional booking flow that allows site visitors to:

• Browse available appointment services.
• Select an appointment time slot.
• Enter their contact information.
• Complete payment through Wix eCommerce.

To build the custom bookings experience, follow these steps:

1. Set up the page elements and structure.
2. Build the backend logic to fetch available time slots.
3. Build the backend logic to create bookings and process payments.
4. Create the basic booking flow framework.
5. Enable customers to browse and select services.
6. Display available appointment times to customers.
7. Allow customers to choose their preferred time slot.
8. Process the booking and redirect to Wix eCommerce checkout.

Before you begin

It's important to note the following points before doing this tutorial:

• Set up your services using the Bookings app.
• This tutorial covers appointment-based services only. Class and course services have different availability patterns and booking flows that aren't covered in this tutorial.
• For paid bookings, set up payment processing before using the Bookings APIs.

Step 1 | Add elements to your page

This step sets up the page elements needed for the booking flow. At the end of this step, you'll have a complete page structure ready for implementing the booking functionality.

To set up the page structure:

1. Add a dataset and connect it to the Bookings/Services collection. Learn more about Adding a Dataset.

2. Add the following elements to your page for services display and connect the repeater elements to their respective fields from the Bookings/Services collection through the dataset:

   Type	ID	Connected to collection/field
   Section	serviceSection	-
   Repeater	serviceRepeater	Bookings/Services
   Text	titleText	Service Name (Text)
   Image	serviceImage	Service Image (Image)
   Text	descriptionText	Service Description (Text)
   Text	priceText	Price Summary (Text)
   Button	bookButton	-

The layout should look like this:

3. Add the following page elements for time slots display.

   Type	ID	Purpose
   Section	slotSection	Contains slot selection UI
   Repeater	slotRepeater	Display available time slots
   Text	dateText	Show slot date
   Text	timeText	Show slot time
   Text	durationText	Show slot duration
   Button	slotButton	Select time slot

The layout should look like this:

4. Add the following page elements for the booking form.

   Type	ID	Purpose
   Section	formSection	Contains customer input fields
   Input	firstNameInput	Customer first name
   Input	lastNameInput	Customer last name
   Input	emailInput	Customer email
   Input	phoneInput	Customer phone number
   Button	checkoutButton	Add booking to cart

The layout should look like this:

Step 2 | Add backend code

This step creates the backend web module for checking slot availability. At the end of this step, you'll have a backend web module that handles slot availability: fetching a list of available slots and verifying that a specific slot is still bookable right before creating a booking.

1. Create a new backend file called bookings-availability.web.js in your backend folder.

2. Add the required imports.

   Copy

3. Add a web method to list available slots.

   It calls listAvailabilityTimeSlots() to retrieve available booking slots for a service. The frontend code passes the required parameters: serviceId, fromDate, toDate, timeSlotsPerDay, and timeZone:

   Copy

4. Add the second method to verify slot availability.

   This prevents double-booking by checking if a slot is still available right before creating the booking. It calls getAvailabilityTimeSlot() to verify a specific time slot is still bookable. The method checks the slot's bookable property to determine if it can still accept bookings. The frontend code passes the required parameters: serviceId, localStartDate, localEndDate, timeZone, and location.

   Copy

Step 3 | Build booking and payment logic

This step creates the backend web module for booking creation and cart integration. The backend web module handles a 2-step process: first creating a booking and then adding it to the eCommerce cart for payment processing.

1. Create a new backend file called bookings-checkout.web.js in your backend folder.

2. Add the required imports.

   Copy

3. Add a helper function to prepare booking data.

   Copy

4. Add a helper function to create the booking.

   This function calls createBooking() and handles any errors that occur during booking creation.

   Copy

5. Add a helper function to add the booking to the cart.

   This function uses addToCurrentCart() to add the created booking to the eCommerce cart by specifying the Wix Bookings app ID and the booking ID.

   Copy

6. Implement the main web method that coordinates the helper functions.

   Copy

Step 4 | Add frontend code

This step sets up the frontend code structure for the booking flow. You'll create the imports, utility functions, and basic UI setup needed for the booking functionality.

At the end of this step, you'll have a page with form validation and checkout button handling, ready to integrate with the service and slot selection features.

To set up the booking infrastructure:

1. Add the imports and global variables at the top of your page code.

   Copy

2. Add utility and helper functions.

   Copy

3. Set up the $w.onReady() function with complete functionality.

   Copy

Step 5 | Enable customers to browse and select services

This step implements the service selection user interface. At the end of this step, clicking a service's book button shows the slot selection section though slots don't load yet.

To set up service selection:

1. Add the service repeater item ready function.

   This function handles when a service item is displayed in the repeater and sets up the book button click handler.

   Copy

2. Add the service repeater registration to your $w.onReady() function.

   Copy

Step 6 | Display available appointment times to customers

This step implements the actual slot loading functionality by replacing the stub function with a real implementation. At the end of this step, site visitors can view available time slots for their selected service.

To load and display available slots:

1. Add the loadAvailableSlots function to your page code.

   When a site visitor selects a service by clicking the book button, this function fetches available time slots for that service. This example queries availability for the next 7 days and limits results to 1 slot per day. You can adjust the time range and slots per day to better suit your business needs and user experience requirements.

   Copy

Step 7 | Allow customers to choose their preferred time slot

This step implements the slot selection functionality with helper functions for cleaner, more maintainable code. At the end of this step, site visitors can choose from available appointment times.

To display and interact with time slots:

1. Add the populateSlotRepeater function to your page code.

   Repeaters require each data item to have an _id field that doesn't contain underscores within its value. The raw slot data from the listAvailabilityTimeSlots() doesn't include an id field, so you must transform the data. For example, by using the map() method. Without this transformation, the repeater won't display any items while no error is logged.

   Copy

2. Add a helper function to format slot display data.

   Copy

3. Add a helper function to handle slot selection.

   Copy

4. Implement the main slot repeater item ready method that uses the helper functions.

   Copy

5. Add the slot repeater registration to your $w.onReady() function.

   Copy

Step 8 | Process the booking and redirect to Wix eCommerce checkout

This step implements the booking creation functionality with a comprehensive set of helper functions for better code organization. The frontend processBooking() function calls the backend web module addBookingToCart() (created in step 3) that handles both creating the booking and adding it to the eCommerce cart. At the end of this step, you create the booking and automatically redirect customers to the cart page to complete their purchase.

To implement the booking process:

1. Add helper functions to collect form data and validate slot selection.

   Copy

2. Add a helper function to transform slot data for booking creation.

   You must transform the slot object returned from listAvailabilityTimeSlots() before specifying it in createBooking(). The required transformations are:

   • Rename date fields: localStartDate/localEndDate → startDate/endDate.
   • Select a resource: Choose 1 resource from the availableResources array.
   • Map location type: Convert between different enum values.

   From listAvailabilityTimeSlots()	To createBooking()
   CUSTOMER	OWNER_CUSTOM
   CUSTOM	CUSTOM
   BUSINESS	OWNER_BUSINESS

   Copy

3. Add a helper function to verify slot availability.

   Copy

4. Implement the main processBooking function that coordinates the helper functions.

   This function orchestrates the entire booking process using the helper functions in a clear 6-step workflow.

   Copy

What happens next

After the booking is added to the cart and the customer is redirected, they continue through the standard Wix eCommerce checkout flow:

1. Cart page: Site visitors review their booking details and continue to checkout.
2. Checkout page: Site visitors enter payment information and billing details.
3. Confirmation: Site visitors receive booking confirmation after successful payment.

Congratulations. You've successfully created a custom bookings experience that integrates with Wix eCommerce for payment processing.

You can continue building upon this example by adding features like booking confirmations, customer notifications, or apply what you learned in this tutorial to create entirely new booking workflows.

Complete implementation code

See also

• Wix Bookings API Reference
• Wix Bookings architecture and data flow
• Wix eCommerce API Reference
• Wix eCommerce architecture and data flow
• Working with Web Modules