About the Bookings API

The Bookings API allows you to manage bookings for a business's services. You can create single-service bookings or multi-service bookings that combine the booking of multiple services into a single transaction. For payment processing, you can integrate with Wix eCommerce (Checkout and Orders APIs) or implement your own custom checkout flow. The booking object holds information about the customer and the session or schedule they have booked.

With the Bookings API you can:

  • Create single-service and multi-service bookings.
  • Manage bookings' life cycles.

Booking lifecycle

Bookings can progress through different statuses depending on service configuration and business workflow:

Core statuses:

  • CREATED: Initial booking created, customer hasn't completed payment.
  • PENDING: Awaiting manual business confirmation (if required by service settings).
  • CONFIRMED: Active booking that appears in the business calendar.

Terminal statuses:

  • CANCELED: Customer-initiated cancellation (may include fees or refunds).
  • DECLINED: Business has rejected the booking before customer payment.

Special status:

  • WAITING_LIST: Booking is placed on a waitlist when the requested class session is at capacity. Only available for class bookings when capacity is exceeded.

Common booking flows:

  • Direct confirmation: CREATED → CONFIRMED (automatic booking approval).
  • Manual approval: CREATED → PENDING → CONFIRMED or DECLINED.
  • Waitlist flow: CREATED → WAITING_LIST → CONFIRMED or DECLINED (classes only).
  • Cancellation: Any active status → CANCELED.

Double booking management

By default, Wix Bookings prevents double bookings as much as possible. In rare instances when scheduling conflicts occur, the doubleBooked flag is set to true and requires manual intervention by the business to resolve the conflict. You can override this behavior using admin overwrites with appropriate permissions.

Multi-service bookings

Multi-service bookings enable businesses to offer comprehensive service packages where customers can book multiple related services together in a single transaction. Each multi-service booking contains several single-service bookings. Single-service bookings within the package must be scheduled sequentially with each booking starting when the previous booking ends.

Requirements and constraints

  • Booking creation: You can't create a multi-service booking using existing single-service bookings. Create Multi Service Booking creates the multi-service booking and all included single-service bookings simultaneously.
  • Number of single-service bookings: 2-8 single-service bookings per multi-service booking.
  • Scheduling type: Sequential only with single-service bookings running consecutively without gaps.
  • Location requirement: All single-service bookings must be at the same business location.
  • Service type limitation: Only appointment-based services are supported. Courses and classes aren't supported.
  • Status synchronization: Operations affect all grouped single-service bookings simultaneously.
  • Pricing: Total price equals the sum of all individual service prices. There are no automatic package discounts.

Operational behaviors

Method restrictions: Single-service bookings within a multi-service booking must be managed using multi-service methods only. For example, call Reschedule Multi Service Booking instead of Reschedule Booking.

Booking modifications: You can add or remove single-service bookings after creating a multi-service booking. If only 1 booking remains after removals, Wix Bookings automatically deletes the multi-service booking while keeping the remaining single-service booking.

Error handling: Multi-service bookings can experience partial failures where some operations succeed while others fail due to availability conflicts, policy violations, or capacity issues.

Use cases

Refer to End-to-End Booking Flows for a complete step-by-step overview of the full booking process (including service selection, availability checks, and payment).

Before you begin

It's important to note the following points before starting to code:

  • Wix Bookings must be installed on a site before you can use the Bookings APIs.
  • The Bookings API doesn't include methods to retrieve individual single-service bookings. Use the Extended Bookings API for reading single-service bookings. The Bookings API does include multi-service booking retrieval methods.
  • You can handle checkout and payment flows with the eCommerce Checkout and eCommerce Orders APIs or use your own custom flow. When customers pay via a Wix eCommerce checkout, Wix Bookings automatically syncs the booking's payment status with the Wix eCommerce order, so avoid manually updating the booking status. Only for custom payment flows, you must manually update the booking's payment status.
  • You can't track attendance with the Bookings API. Instead, use the Attendance API.
  • Always call the availability checking methods before creating bookings to ensure the requested time slot is available.

Terminology

  • Booking: A customer's reservation for a specific service, time slot, or schedule. This is the standard booking type used by most businesses.
  • Single-service booking: Another term for "booking" used in multi-service booking contexts to distinguish individual bookings from packages.
  • Multi-service booking: A package that combines multiple bookings under a single ID, scheduled sequentially for a seamless customer experience. All bookings within a multi-service booking are managed together as a group.
  • Service: A bookable offering such as an appointment, class, or course.
  • Slot: A specific time period when a service is available for booking.
  • Schedule: A recurring pattern of availability for a service, such as a weekly yoga class.
  • Session: An individual occurrence of a class or course.

For a comprehensive glossary of Wix Bookings terms, see Terminology.

See also

Did this help?