POST

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.

Permissions
Manage Bookings - all permissions
Manage Bookings
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/_api/bookings-service/v2/bookings
Body Params
bookingBookingRequired

The booking to create.

participantNotificationParticipantNotification

Information about whether to notify the customer and the message to send.

sendSmsReminderboolean

Whether to send an SMS reminder to the customer 24 hours before the session starts. The phone number is taken from contactDetails.phone. Default: true.

flowControlSettingsFlowControlSettings

Whether to ignore specific standard procedures of the Wix Bookings flow. For example, whether to check availability when creating a booking.

Response Object
bookingBooking

Created booking.

Request
cURL
curl -X POST \
'https://www.wixapis.com/bookings/v2/bookings' \
-H 'Authorization: <AUTH>' \
-d '{
  "booking": {
    "bookedEntity": {
      "slot": {
        "serviceId": "8ee826a3-64c4-416d-a22c-e01d39f56931",
        "scheduleId": "844772a6-ad31-49fb-b3d9-7aef1e559b7e",
        "startDate": "2022-12-26T12:00:00.000Z",
        "endDate": "2022-12-26T13:00:00.000Z",
        "timezone": "Europe/Dublin",
        "resource": {
          "id": "5fa50f19-4c94-4c42-a72b-289505ba2028",
          "name": "Tom Jones",
          "scheduleId": "a4166c1f-728c-4895-8a6e-1942bb321315"
        },
        "location": {
          "id": "9de094d5-8985-484e-9218-d020d9d17953",
          "name": "Location Name",
          "formattedAddress": "Location Address",
          "locationType": "OWNER_BUSINESS"
        }
      },
      "title": "In-person Appointment",
      "tags": [
        "INDIVIDUAL"
      ]
    },
    "contactDetails": {
       "firstName": "John",
       "email": "john@example.com"
    },
    "additionalFields": [],
    "totalParticipants": 1,
    "selectedPaymentOption": "ONLINE"
  },
  "sendSmsReminder": false,
  "participantNotification": {
    "notifyParticipants": true
  },
  "flowControlSettings": {
    "skipAvailabilityValidation": false,
    "skipBusinessConfirmation": false,
    "skipSelectedPaymentOptionValidation": false
  }
}'
Response
JSON
{
  "booking": {
    "id": "084e2d07-62ae-42f6-bf7f-5796a393d81d",
    "bookedEntity": {
      "slot": {
        "serviceId": "8ee826a3-64c4-416d-a22c-e01d39f56931",
        "scheduleId": "844772a6-ad31-49fb-b3d9-7aef1e559b7e",
        "startDate": "2022-12-26T12:00:00.000Z",
        "endDate": "2022-12-26T13:00:00.000Z",
        "timezone": "Europe/Dublin",
        "resource": {
          "id": "5fa50f19-4c94-4c42-a72b-289505ba2028",
          "name": "Tom Jones",
          "scheduleId": "a4166c1f-728c-4895-8a6e-1942bb321315"
        },
        "location": {
          "id": "9de094d5-8985-484e-9218-d020d9d17953",
          "name": "Location Name",
          "formattedAddress": "Location Address",
          "locationType": "OWNER_BUSINESS"
        }
      },
      "title": "In-person Appointment",
      "tags": ["INDIVIDUAL"]
    },
    "contactDetails": {
      "firstName": "John",
      "email": "john@example.com"
    },
    "additionalFields": [],
    "totalParticipants": 1,
    "status": "CREATED",
    "paymentStatus": "UNDEFINED",
    "selectedPaymentOption": "ONLINE",
    "createdDate": "2022-12-24T17:42:12.019Z",
    "revision": "1",
    "createdBy": {
      "identityType": "UNKNOWN",
      "wixUserId": "086ca7ca-ee70-4ab3-a96e-78f8420e9428"
    },
    "startDate": "2022-12-26T12:00:00Z",
    "endDate": "2022-12-26T13:00:00Z",
    "updatedDate": "2022-12-24T17:42:12.019Z",
    "totalParticipants": 1
  }
}
Errors
400Invalid Argument

There are 4 errors with this status code.

403Permission Denied

There are 2 errors with this status code.

428Failed Precondition

There are 12 errors with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Event TriggersThis method triggers the following events:
Booking Created
Did this help?