CorvidReference

wix-bookings

The wix-bookings module contains functionality for working with bookings from client-side code.

Using the Bookings API, you can build a customized bookings experience.

To process bookings on your site, first set up your site to accept bookings as described in About Wix Bookings.

You can checkout bookings for 1-on-1 Sessions (Appointments) from any type of Wix account. To checkout bookings for Ongoing Sessions (Classes) or a Set of Sessions (Courses) you need to upgrade to a Business Premium Plan.

Typical Booking Lifecycle

The following list outlines the data flow in a typical booking lifecycle:

  1. Get a list of services from one of:
    • A dataset connected to the Bookings/Services collection.
    • A query on the Bookings/Services collection.
  2. A service is selected.
  3. Call the getServiceAvailability() function using the selected service's Service ID (_id) value. (Optionally, you can pass a AvailabilityOptions object to change the limits on the slots that are returned.)
  4. You can match the returned slots to their related staff member items using the Bookings/Staff collection.
  5. A slot is selected.
  6. Gather values for the selected service's form fields, if there are any. The list of form fields is found in the form property of the items in the Bookings/Services collection.
  7. Call the checkoutBooking() function. Pass the selected slot object, the values for the form fields, and the payment type if neccessary. Note, the specified payment type must match the service's configuration in your site's Dashboard. You cannot book a paid service as if it were free.

    • If the service is free, you do not need to pass a paymentOptions object.
    • If the service is not free and you pass a paymentOptions object indicating the payment should be online, a payment popup is presented for the user to enter payment information, such as credit card information.
    • If the service is not free and you pass a paymentOptions object indicating the payment should be offline, the payment popup is not presented to the user.

    To use the Bookings API, import wixBookings from the wix-bookings module:

    import wixBookings from 'wix-bookings';

Note

Different terminology is used for the types of services, depending on the context. The following list shows the term used in your site's Dashboard on the left and the term used in the Bookings/Services collection on the right:

  • 1-on-1 Session: APPOINTMENT
  • Ongoing Session: CLASS
  • Set of Sessions: COURSE

Table of Contents

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
AvailabilityOptions

An object used when calling getServiceAvailability() containing options for which slots should be returned.

BookingInfo

An object used when calling checkoutBooking() containing information about the slot to be booked.

BookingResultAn object representing the result of a call to checkoutBooking().
FormField

An object used when calling checkoutBooking() containing values for form fields required to book the session.

PaymentOptions

An object used when calling checkoutBooking() containing information about the payment options.

ServiceAvailability

An object returned from getServiceAvailability() containing the available bookings slots.

SlotAn object representing a booking slot.

Related Content

checkoutBooking( )

Books a service and processes payment for the service.

Description

The checkoutBooking() function returns a Promise that resolves to a unique booking ID when the service is booked successfully.

To understand how checkoutBooking() is used in a typical booking lifecycle, see Typical Booking Lifecycle.

Call the checkoutBooking() with a BookingInfo object that contains the slot to book, values for all the form fields, and the number of spots to book.

The form fields contain additional information required for the booking.

If the service being checked out is not a free service, you also need to pass a PaymentOptions object containing information about the method of payment and any coupon codes. If an online method of payment is specified, a payment popup is presented for the user to input payment information, such as credit card information. The function's returned Promise resolves after the user finishes entering the payment information and the service has been successfully booked. If no payment or an offline method of payment is specified, the payment popup is not presented and the Promise resolves when the service has been successfully booked.

If a service is configured as a paid service in the Dashboard, attempting to perform a checkout as if it is a free service results in an error.

When a service is booked successfully:

  • A site contact is created with the provided booking information.
  • An email is sent to you about the new booking.
  • An email is sent to the user confirming that the service was booked.

Note

You can checkout bookings for 1-on-1 Sessions (Appointments) from any type of Wix account. To checkout bookings for Ongoing Sessions (Classes) or a Set of Sessions (Courses) you need to upgrade to a Business Premium Plan.

Syntax

function checkoutBooking(bookingInfo: BookingInfo, [options: PaymentOptions]): Promise<BookingResult>
PARAMETERS
?
Values that you pass to a function.
bookingInfo
Information about the slot to be booked.
options(Optional)
Information about the payment method and coupon codes.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<BookingResult>
Fulfilled - Results of the booking checkout.

Examples

Book a service

import wixBookings from 'wix-bookings';

// ...

let chosenSlot = // get chosen slot

let formFieldValues = [
  {
    "_id": "20657271-c55f-43d6-adfd-39b7acc38e11", // name field ID
    "value": "John Doe"
  }, {
    "_id": "87edd4e0-42b1-4802-8766-584f3eeb6436", // email field ID
    "value": "john@doe.com"
  }
];

let bookingInfo = {
  "slot": chosenSlot,
  "formFields": formFieldValues
};

wixBookings.checkoutBooking(bookingInfo)
  .then( (results) => {
    let id = results.bookingId;
    let status = results.status;
  } );

Book a service with payment options

import wixBookings from 'wix-bookings';

// ...

let chosenSlot = // get chosen slot

let formFieldValues = [
  {
    "_id": "20657271-c55f-43d6-adfd-39b7acc38e11", // name field ID
    "value": "John Doe"
  }, {
    "_id": "87edd4e0-42b1-4802-8766-584f3eeb6436", // email field ID
    "value": "john@doe.com"
  }
];

let bookingInfo = {
  "slot": chosenSlot,
  "formFields": formFieldValues
};

let options = {
  "paymentType": "wixPay_Offline",
  "couponCode": "thecouponcode"
}

wixBookings.checkoutBooking(bookingInfo, options)
  .then( (results) => {
    let id = results.bookingId;
    let status = results.status;
  } );

A full bookings scenario

This examples demonstrates a simple bookings scenario. In the interest of simplicity the code does not deal with display considerations or validations that would normally be required to make sure users perform the flow as intended. The code assumes a page with the following elements:

  • serviceRepeater: Displays the services that can be booked. The elements in the repeater match the information we want to display for each service.
  • slotRepeater: Displays the slots that are available for the selected service. The elements in the repeater match the information we want to display for each slot.
  • formFieldRepeater: Contains input fields for collecting form field values needed to book the selected service. Each item contains one input element.
  • bookButton: Perfoms a booking checkout after a service and slot are selected and the form fields have been entered.
import wixData from 'wix-data';
import wixBookings from 'wix-bookings';

let formFields;   // form fields the selected service requires
let selectedSlot; // service slot that was selected

// When the page loads, query for all services and use the
// results to set the service repeater's data.
$w.onReady(function () {
  wixData.query("Bookings/Services")
    .find()
    .then( (results) => {
      $w("#serviceRepeater").data = results.items;
    } );
});

// When the service repeater's data is set, populate its items
// with the service data.
export function serviceRepeater_itemReady($item, itemData, index) {
  $item("#serviceName").text = itemData.serviceName;
  $item("#tagLine").text = itemData.tagLine;
  $item("#image").src = itemData.imageURL;
}

// When a service is selected, store its form fields for later,
// get the service's available slots, and use the results to set
// the slot repeater's data.
export function serviceRepeaterContainer_click(event) {
  $w("#serviceRepeater").forItems([event.context.itemId], ($item, itemData, index) => {
    formFields = itemData.form.fields;
  } );

  wixBookings.getServiceAvailability(event.context.itemId)
    .then( (availability) => {
      $w("#slotRepeater").data = availability.slots;
    } );
}

// When the slot repeater's data is set, populate its items
// with the slot data.
export function slotRepeater_itemReady($item, itemData, index) {
  $item("#dateText").text = itemData.startDateTime.toLocaleDateString();
  $item("#timeText").text = itemData.startDateTime.toLocaleTimeString();
}

// When a slot is selected, store it for later, use the stored form
// fields to set form field repeater's data.
export function slotRepeateContainer_click(event) {
  $w("#slotRepeater").forItems([event.context.itemId], ($item, itemData, index) => {
    selectedSlot = itemData;
  } );

  $w("#formFieldRepeater").data = formFields;
}

// When the form field repeater's data is set, populate its items
// with the form fields.
export function formFieldRepeater_itemReady($item, itemData, index) {
  $item("#fieldInput").placeholder = itemData.label;
}

// When the booking button is clicked, grab the form field values,
// build the bookingInfo object, and perform a booking checkout.
export function bookButton_click(event) {
  let formFieldValues = [];

  $w("#formFieldRepeater").forEachItem( ($item, itemData, index) => {
    formFieldValues.push({
      "_id": itemData._id,
      "value": $item("#fieldInput").value
    });
  } );

  let bookingInfo = {
    "slot": selectedSlot,
    "formFields": formFieldValues
  };

  wixBookings.checkoutBooking(bookingInfo)
    .then( (results) => {
      $w("#confirmationText").text = `Booking ID: ${results.bookingId} Status: ${results.status}`;
    } );
}

getServiceAvailability( )

Gets the available slots for a specific service.

Description

The getServiceAvailability() function returns a Promise that resolves to a list of slots from the given service that have open spots, and can therefore still be booked.

Service availability means different things for the different service types:

  • 1-on-1 Sessions (APPOINTMENT): See here to understand what affects the availability of a 1-on-1 session. A 1-on-1 session is returned as available if it meets the conditions outlined in the article linked above and the session slot's time falls within the time specified by the AvailabilityOptions or within the default time frame if no options are specified.
  • Ongoing Sessions (CLASS): An ongoing session slot is returned as available if the slot's time falls within the time specified by the AvailabilityOptions or within the default time frame if no options are specified.
  • Set of Sessions (COURSE): The first session slot from a set of sessions is returned as available if the first session slot's time falls within the time specified by the AvailabilityOptions or within the default time frame if no options are specified.

    To understand how getServiceAvailability() is used in a typical booking lifecycle, see Typical Booking Lifecycle.

    The passed serviceId must be an ID from your site's Bookings/Services collection. Typically, you retrieve the ID from from the collection using a query or through a dataset.

    Optionally, you can pass an AvailabilityOptions object that defines a date range for which slots should be returned. If you do not pass an an AvailabilityOptions object, the default date range is from the date and time the function is called until one week later.

Syntax

function getServiceAvailability(serviceId: string, [options: AvailabilityOptions]): Promise<ServiceAvailability>
PARAMETERS
?
Values that you pass to a function.
serviceId
string
The ID of the service for which to check slot availability.
options(Optional)
Options that refine which slots should be returned.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.

Fulfilled - A list of available slots. Rejected - Bookings error object.

Examples

Get the available slots for a service

import wixBookings from 'wix-bookings';

// ...

let serviceId = // get service ID

wixBookings.getServiceAvailability(serviceId)
  .then( (availability) => {
    let slots = availability.slots;
    let firstSlot = slots[0];
  } );

/* firstSlot:
 * {
 *   "_id": "eyIjoxN2xhc3NJbnN0YW5jZUlkIjoiNjc4ZDYyMzItZ",
 *   "startDateTime": "2018-11-20T08:00:00Z",
 *   "endDateTime": "2018-11-20T09:00:00Z",
 *   "serviceId": "a642caa6-1aba-4aa4-9f07-5aed39fbd3ba",
 *   "capacity": 20,
 *   "remainingSpots": 20,
 *   "staffMemberId": "5a55aa7c-8e5d-488a-8191-7d430f2cdcc2"
 * }
 */

Get the available slots for a service for a specific date range

import wixBookings from 'wix-bookings';

// ...

let serviceId = // get service ID

let today = new Date();
let startRange = new Date();
let endRange = new Date();
startRange.setDate(today.getDate() + 7);  // one week from now
endRange.setDate(today.getDate() + 14);   // two weeks from now

let options = {
  startDateTime: startRange,
  endDateTime: endRange
};

wixBookings.getServiceAvailability(serviceId, options)
  .then( (availability) => {
    let slots = availability.slots;
    let firstSlot = slots[0];
  } );

/* firstSlot:
 * {
 *   "_id": "eyIjoxN2xhc3NJbnN0YW5jZUlkIjoiNjc4ZDYyMzItZ",
 *   "startDateTime": "2018-11-20T08:00:00Z",
 *   "endDateTime": "2018-11-20T09:00:00Z",
 *   "serviceId": "a642caa6-1aba-4aa4-9f07-5aed39fbd3ba",
 *   "capacity": 20,
 *   "remainingSpots": 20,
 *   "staffMemberId": "5a55aa7c-8e5d-488a-8191-7d430f2cdcc2"
 * }
 */

A full bookings scenario

This examples demonstrates a simple bookings scenario. In the interest of simplicity the code does deal with display considerations or validations that would normally be required to make sure users perform the flow as intended. The code assumes a page with the following elements:

  • serviceRepeater: Displays the services that can be booked. The elements in the repeater match the information we want to display for each service.
  • slotRepeater: Displays the slots that are available for the selected service. The elements in the repeater match the information we want to display for each slot.
  • formFieldRepeater: Contains input fields for collecting form field values needed to book the selected service. Each item contains one input element.
  • bookButton: Perfoms a booking checkout after a service and slot are selected and the form fields have been entered.
import wixData from 'wix-data';
import wixBookings from 'wix-bookings';

let formFields;   // form fields the selected service requires
let selectedSlot; // service slot that was selected

// When the page loads, query for all services and use the
// results to set the service repeater's data.
$w.onReady(function () {
  wixData.query("Bookings/Services")
    .find()
    .then( (results) => {
      $w("#serviceRepeater").data = results.items;
    } );
});

// When the service repeater's data is set, populate its items
// with the service data.
export function serviceRepeater_itemReady($item, itemData, index) {
  $item("#serviceName").text = itemData.serviceName;
  $item("#tagLine").text = itemData.tagLine;
  $item("#image").src = itemData.imageURL;
}

// When a service is selected, store its form fields for later,
// get the service's available slots, and use the results to set
// the slot repeater's data.
export function serviceRepeaterContainer_click(event) {
  $w("#serviceRepeater").forItems([event.context.itemId], ($item, itemData, index) => {
    formFields = itemData.form.fields;
  } );

  wixBookings.getServiceAvailability(event.context.itemId)
    .then( (availability) => {
      $w("#slotRepeater").data = availability.slots;
    } );
}

// When the slot repeater's data is set, populate its items
// with the slot data.
export function slotRepeater_itemReady($item, itemData, index) {
  $item("#dateText").text = itemData.startDateTime.toLocaleDateString();
  $item("#timeText").text = itemData.startDateTime.toLocaleTimeString();
}

// When a slot is selected, store it for later, use the stored form
// fields to set form field repeater's data.
export function slotRepeateContainer_click(event) {
  $w("#slotRepeater").forItems([event.context.itemId], ($item, itemData, index) => {
    selectedSlot = itemData;
  } );

  $w("#formFieldRepeater").data = formFields;
}

// When the form field repeater's data is set, populate its items
// with the form fields.
export function formFieldRepeater_itemReady($item, itemData, index) {
  $item("#fieldInput").placeholder = itemData.label;
}

// When the booking button is clicked, grab the form field values,
// build the bookingInfo object, and perform a booking checkout.
export function bookButton_click(event) {
  let formFieldValues = [];

  $w("#formFieldRepeater").forEachItem( ($item, itemData, index) => {
    formFieldValues.push({
      "_id": itemData._id,
      "value": $item("#fieldInput").value
    });
  } );

  let bookingInfo = {
    "slot": selectedSlot,
    "formFields": formFieldValues
  };

  wixBookings.checkoutBooking(bookingInfo)
    .then( (results) => {
      $w("#confirmationText").text = `Booking ID: ${results.bookingId} Status: ${results.status}`;
    } );
}

AvailabilityOptions

An object used when calling getServiceAvailability() containing options for which slots should be returned.

Syntax

type AvailabilityOptions = {
  startDateTime: Date
  endDateTime: Date
}
MEMBERS
?
The properties of an object.
startDateTime(Optional)
Date

Start date and time of the slots to be returned. Defaults to the current date and time.

endDateTime(Optional)
Date

End date and time of the slots to be returned. Defaults to one week from startDateTime, which is one week from the current date and time if startDateTime is also omitted.

Examples

Get the available slots for a service for a specific date range

import wixBookings from 'wix-bookings';

// ...

let serviceId = // get service ID

let today = new Date();
let startRange = new Date();
let endRange = new Date();
startRange.setDate(today.getDate() + 7);  // one week from now
endRange.setDate(today.getDate() + 14);   // two weeks from now

let options = {
  startDateTime: startRange,
  endDateTime: endRange
};

wixBookings.getServiceAvailability(serviceId, options)
  .then( (availability) => {
    let slots = availability.slots;
    let firstSlot = slots[0];
  } );

/* firstSlot:
 * {
 *   "_id": "eyIjoxN2xhc3NJbnN0YW5jZUlkIjoiNjc4ZDYyMzItZ",
 *   "startDateTime": "2018-11-20T08:00:00Z",
 *   "endDateTime": "2018-11-20T09:00:00Z",
 *   "serviceId": "a642caa6-1aba-4aa4-9f07-5aed39fbd3ba",
 *   "capacity": 20,
 *   "remainingSpots": 20,
 *   "staffMemberId": "5a55aa7c-8e5d-488a-8191-7d430f2cdcc2"
 * }
 */

BookingInfo

An object used when calling checkoutBooking() containing information about the slot to be booked.

Syntax

type BookingInfo = {
  slot: Slot
  numberOfSpots: number
  formFields: Array<FormField>
}
MEMBERS
?
The properties of an object.
slot
The slot to be booked.
numberOfSpots(Optional)
number
Number of spots to book. Defaults to 1.
formFields
Array<FormField>
List of form field values required to book the session.

Examples

Book a service

import wixBookings from 'wix-bookings';

// ...

let chosenSlot = // get chosen slot

let formFieldValues = [
  {
    "_id": "20657271-c55f-43d6-adfd-39b7acc38e11", // name field ID
    "value": "John Doe"
  }, {
    "_id": "87edd4e0-42b1-4802-8766-584f3eeb6436", // email field ID
    "value": "john@doe.com"
  }
];

let bookingInfo = {
  "slot": chosenSlot,
  "formFields": formFieldValues
};

wixBookings.checkoutBooking(bookingInfo)
  .then( (results) => {
    let id = results.bookingId;
    let status = results.status;
  } );

BookingResult

An object representing the result of a call to checkoutBooking().

Syntax

type BookingResult = {
  status: string
  bookingId: string
}
MEMBERS
?
The properties of an object.
status
string

Status of the booking that was checked out. One of:

  • "Confirmed": Payment was successful or payment is to be done offline.
  • "Pending Payment": Payment is pending.
  • "Terminated": Payment failed or was cancelled.
bookingId
string
ID of the booking that was checked out.

Examples

Book a service with payment options

import wixBookings from 'wix-bookings';

// ...

let chosenSlot = // get chosen slot

let formFieldValues = [
  {
    "_id": "20657271-c55f-43d6-adfd-39b7acc38e11", // name field ID
    "value": "John Doe"
  }, {
    "_id": "87edd4e0-42b1-4802-8766-584f3eeb6436", // email field ID
    "value": "john@doe.com"
  }
];

let bookingInfo = {
  "slot": chosenSlot,
  "formFields": formFieldValues
};

let options = {
  "paymentType": "wixPay_Offline",
  "couponCode": "thecouponcode"
}

wixBookings.checkoutBooking(bookingInfo, options)
  .then( (results) => {
    let id = results.bookingId;
    let status = results.status;
  } );

FormField

An object used when calling checkoutBooking() containing values for form fields required to book the session.

Syntax

type FormField = {
  value: string
  _id: string
}
MEMBERS
?
The properties of an object.
value
string
Form field value.
_id
string
ID of the form field from the form property in the Booking/Sessions collection.

Examples

Book a service

import wixBookings from 'wix-bookings';

// ...

let chosenSlot = // get chosen slot

let formFieldValues = [
  {
    "_id": "20657271-c55f-43d6-adfd-39b7acc38e11", // name field ID
    "value": "John Doe"
  }, {
    "_id": "87edd4e0-42b1-4802-8766-584f3eeb6436", // email field ID
    "value": "john@doe.com"
  }
];

let bookingInfo = {
  "slot": chosenSlot,
  "formFields": formFieldValues
};

wixBookings.checkoutBooking(bookingInfo)
  .then( (results) => {
    let id = results.bookingId;
    let status = results.status;
  } );

PaymentOptions

An object used when calling checkoutBooking() containing information about the payment options.

Syntax

type PaymentOptions = {
  paymentType: string
  couponCode: string
}
MEMBERS
?
The properties of an object.
paymentType
string

Type of the payment. Either "wixPay_Online" for online collection, or "wixPay_Offline" for offline collection.

couponCode
string
A coupon code to be used with the payment.

Examples

Book a service with payment options

import wixBookings from 'wix-bookings';

// ...

let chosenSlot = // get chosen slot

let formFieldValues = [
  {
    "_id": "20657271-c55f-43d6-adfd-39b7acc38e11", // name field ID
    "value": "John Doe"
  }, {
    "_id": "87edd4e0-42b1-4802-8766-584f3eeb6436", // email field ID
    "value": "john@doe.com"
  }
];

let bookingInfo = {
  "slot": chosenSlot,
  "formFields": formFieldValues
};

let options = {
  "paymentType": "wixPay_Offline",
  "couponCode": "thecouponcode"
}

wixBookings.checkoutBooking(bookingInfo, options)
  .then( (results) => {
    let id = results.bookingId;
    let status = results.status;
  } );

ServiceAvailability

An object returned from getServiceAvailability() containing the available bookings slots.

Syntax

type ServiceAvailability = {
  slots: Array<Slot>
}
MEMBERS
?
The properties of an object.
slots
Array<Slot>
List of available slots.

Examples

Get the available slots for a service

import wixBookings from 'wix-bookings';

// ...

let serviceId = // get service ID

wixBookings.getServiceAvailability(serviceId)
  .then( (availability) => {
    let slots = availability.slots;
    let firstSlot = slots[0];
  } );

/* firstSlot:
 * {
 *   "_id": "eyIjoxN2xhc3NJbnN0YW5jZUlkIjoiNjc4ZDYyMzItZ",
 *   "startDateTime": "2018-11-20T08:00:00Z",
 *   "endDateTime": "2018-11-20T09:00:00Z",
 *   "serviceId": "a642caa6-1aba-4aa4-9f07-5aed39fbd3ba",
 *   "capacity": 20,
 *   "remainingSpots": 20,
 *   "staffMemberId": "5a55aa7c-8e5d-488a-8191-7d430f2cdcc2"
 * }
 */

Slot

An object representing a booking slot.

Syntax

type Slot = {
  startDateTime: Date
  endDateTime: Date
  serviceId: string
  capacity: number
  remainingSpots: number
  staffMemberId: string
  _id: string
}
MEMBERS
?
The properties of an object.
startDateTime
Date
Starting date and time of the slot.
endDateTime
Date
Ending date and time of the slot.
serviceId
string
ID of the service that the slot belongs to.
capacity
number
Maximum number of participants that can book the service for this slot.
remainingSpots
number
Number of remaining spots that can be booked for the slot.
staffMemberId
string
ID of the slot's staff member.
_id
string
Unique slot identifier.

Examples

Get the available slots for a service

import wixBookings from 'wix-bookings';

// ...

let serviceId = // get service ID

wixBookings.getServiceAvailability(serviceId)
  .then( (availability) => {
    let slots = availability.slots;
    let firstSlot = slots[0];
  } );

/* firstSlot:
 * {
 *   "_id": "eyIjoxN2xhc3NJbnN0YW5jZUlkIjoiNjc4ZDYyMzItZ",
 *   "startDateTime": "2018-11-20T08:00:00Z",
 *   "endDateTime": "2018-11-20T09:00:00Z",
 *   "serviceId": "a642caa6-1aba-4aa4-9f07-5aed39fbd3ba",
 *   "capacity": 20,
 *   "remainingSpots": 20,
 *   "staffMemberId": "5a55aa7c-8e5d-488a-8191-7d430f2cdcc2"
 * }
 */