About the Bookings Writer V2 API

The Bookings Writer V2 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 Writer V2 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. Doesn't appear on the Booking Calendar or block availability.
• PENDING: Awaiting manual business confirmation. Doesn't appear on the Booking Calendar or block availability.
• CONFIRMED: Active booking that appears on the Booking Calendar and blocks resource availability.

Terminal statuses

• CANCELED: Customer-initiated cancellation that 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 with automatic booking approval.
• Manual approval: CREATED → PENDING → CONFIRMED or DECLINED.
• Waitlist flow: CREATED → WAITING_LIST → CONFIRMED or DECLINED for classes only.
• Cancellation: Any active status → CANCELED.

Double booking management

Wix Bookings prevents double bookings by default, but conflicts can occasionally occur. When they do, the system sets a booking's doubleBooked flag to true and requires the business to manually resolve the conflict.

To prevent conflicts, always use the Time Slots V2 API before creating or rescheduling bookings to verify availability. When conflicts do occur, you can detect them through events and choose from these resolution options:

• Standard resolution: Reschedule conflicted bookings to an alternative time or cancel them.
• Force resolution: Force confirm or decline bookings regardless of conflicts.

See complete implementation details for handling double booking conflicts in the sample flows article.

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 in the package must be scheduled sequentially with each booking starting when the previous booking ends.

Requirements and constraints

Multi-service bookings have the following requirements and limitations:

• 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

Multi-service bookings have specific operational characteristics:

• Method restrictions: Single-service bookings in 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

• Book an appointment.
• Book a class session.
• Book a course.
• Create a multi-service booking.
• Reschedule a multi-service booking and add a single-service booking.

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 V2 APIs.
• The Bookings Writer V2 API doesn't include methods to retrieve individual single-service bookings. Use the Bookings Reader V2 API for reading single-service bookings. The Bookings Writer V2 API does include multi-service booking retrieval methods: Get Multi Service Booking and Bulk Get Multi Service Booking Allowed Actions.
• 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 using Confirm Booking or Decline Booking.
• You can't track attendance with the Bookings Writer V2 API. Instead, use the Attendance API.
• Always call the Time Slots V2 API 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 in 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

• Bookings Reader V2 API: Retrieve single-service bookings, allowed actions, and query booking data.
• Bookings Services API: Manage a business's services so customers can book appointments, class sessions, and courses.
• Availability Calendar API: Calculate the availability of appointments and class sessions.
• Attendance API: Lets you track attendance data for booking sessions.
• Calendar V3 APIs: Manage a business' schedules and events.
• eCommerce Checkout and eCommerce Orders APIs: Manage checkout and payment flows for a business' bookings.