Create Booking

Creates a booking.

Appointment booking

For appointment-based services, specify the relevant slot in bookedEntity.slot. We recommend specifying the complete availabilityEntries.slot returned in Query Availability (SDK | REST) in your call's request to avoid failed calls due to unavailability.

Class session booking

For class services, specify the relevant event ID (SDK | REST) as bookedEntity.slot.eventId. We recommend retrieving the event ID from Query Availability's (SDK | REST) availabilityEntries.slot.eventId to avoid failed calls due to unavailability. Specifying an event ID leads to automatic calculations of slot.startDate, slot.endDate, slot.timezone, slot.resource, and slot.location. All manually specified values are overridden.

Course booking

For course services, specify the course's schedule ID in bookedEntity.schedule.scheduleId. We recommend following this sample flow to minimize failed calls due to unavailability.

Related resources

Specifying a resource triggers an availability check, resulting in a failed call if the resource is unavailable. Omitting a resource allows Wix Bookings to assign a resource belonging to the relevant type randomly when the merchant confirms the booking.

Participant information

You must specify either participantsChoices or totalParticipants. The call fails if the specified participantsChoices aren't among the supported service options and variants (SDK | REST).

Notify customers

You can specify a participantNotification.message for the customer that's send immediately. Ensure participantNotification.notifyParticipants is set to true to send the message.

If you specify {"sendSmsReminder": true}, the customer receives an SMS 24 hours before the session starts. The phone number is taken from contactDetails.phone.

Booking status

Bookings default to the CREATED status, not affecting the business calendar or resource availability. You can specify a different status when the calling identity has Manage Bookings permissions.

Payment options

The specified selectedPaymentOption indicates how the customer intends to pay, allowing for later changes to a different method supported by the service.

Payment status

A booking is initially created with {"paymentStatus": "UNDEFINED"} regardless of the payment status specified in Create Booking. If a customer uses an eCommerce checkout (SDK | REST), Wix Bookings automatically syncs the booking's payment status from the corresponding eCommerce order (SDK | REST).

If a booking doesn't have a corresponding eCommerce order, for example, since the customer didn't use the eCommerce checkout, you can update the booking's payment status with Confirm Or Decline Booking (SDK | REST).

Booking form data

When customers sign up for a service, they must fill out the booking form. To create a booking with a completed booking form, specify the relevant data in formSubmission. Ensure the values of the corresponding fields in booking.contactDetails and formSubmission are identical. If these values don't match, Create Booking fails. Therefore, we recommend specifying only booking.contactDetails.contactId when providing formSubmission. Learn more about managing booking form data with APIs (SDK | REST).

Admin overwrites

There are small but important differences when you specify special flowControlSettings:

• {"skipAvailabilityValidation": true}: The call succeeds regardless of availability. If you don't specify any resource, the call succeeds even if no resource of the relevant type is available.
• {"skipBusinessConfirmation": true}: Automatically confirms PENDING bookings that require manual confirmation.
• {"skipSelectedPaymentOptionValidation": true}: Allows customers to pay with payment methods that aren't supported for the service.

When using special flowControlSettings, ensure you have sufficient permissions. If you encounter failed calls due to insufficient permissions, consider the following options:

• App developers can use a higher permission, such as MANAGE BOOKINGS - ALL PERMISSIONS.
• Site developers can utilize elevation.

Granting additional permissions and using elevation permits method calls that would typically fail due to authorization checks. Therefore, you should use them intentionally and securely.