Setting the file. One moment.
Subchapter 8.18
references/bookings/end-to-end-booking-flow.mdMarkdown11 KBView on GitHub
Step-by-step flow for implementing a complete booking experience using REST APIs.
13d21c63-b5ec-5912-8397-c3a5ddb27a97)Note: If you receive errors from Bookings APIs, the Wix Bookings app may not be installed on the site. Use List Installed Apps to verify, and Install Wix Apps to install it if missing.
Endpoint: POST https://www.wixapis.com/bookings/v2/services/query
{
"query": {
"filter": {
"type": "APPOINTMENT"
},
"paging": {
"limit": 20
}
}
}Service Types:
APPOINTMENT — One-on-one sessions with a staff memberCLASS — Group sessions at scheduled timesCOURSE — Multi-session series (customers book the entire course)Save from the response:
id — service IDschedule.id — schedule ID (needed for appointment bookings and course bookings)type — determines the booking flow (slot vs schedule)staffMemberIds — resource IDs of assigned staff (for appointments)Endpoint: POST https://www.wixapis.com/_api/service-availability/v2/time-slots
Important: The old Availability Calendar API (
/bookings/v2/availability/query) is deprecated. Always use Time Slots V2.
{
"serviceId": "<SERVICE_ID>",
"fromLocalDate": "2024-06-15T08:00:00",
"toLocalDate": "2024-06-16T18:00:00",
"timeZone": "America/New_York",
"bookable": true,
"includeResourceTypeIds": ["<RESOURCE_TYPE_ID>"]
}Dates must be in YYYY-MM-DDThh:mm:ss format (local datetime). Plain dates like 2024-06-15 will be rejected with a 400 error.
| Parameter | Required | Description |
|---|---|---|
serviceId | Yes | From Step 1 |
fromLocalDate | Yes | Start of range in YYYY-MM-DDThh:mm:ss format |
toLocalDate | Yes | End of range in YYYY-MM-DDThh:mm:ss format |
timeZone | Yes | IANA timezone (e.g. America/New_York) |
bookable | No | Set true to only get bookable slots |
includeResourceTypeIds | No | Array of resource type IDs — populates availableResources in response |
serviceId, scheduleId — needed for Create BookinglocalStartDate, localEndDate — slot timesavailableResources[].resources[].id — resource ID (only populated if includeResourceTypeIds was provided)location.locationType — warning: returns BUSINESS but Create Booking requires OWNER_BUSINESS (see Step 3)Use List Event Time Slots (opens in a new tab) instead. Each class session has an eventId — save it for the booking.
Endpoint: POST https://www.wixapis.com/_api/bookings-service/v2/bookings
{
"booking": {
"bookedEntity": {
"slot": {
"serviceId": "<SERVICE_ID>",
"scheduleId": "<SCHEDULE_ID>",
"startDate": "2024-06-15T14:00:00",
"endDate": "2024-06-15T15:00:00",
"timezone": "America/New_York",
"resource": {
"id": "<RESOURCE_ID>"
},
"location": {
"locationType": "OWNER_BUSINESS"
}
}
},
"contactDetails": {
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com"
},
"totalParticipants": 1
}
}All slot fields are required for appointments when no eventId is provided:
| Field | Source | Notes |
|---|---|---|
serviceId | Step 1 | Service GUID |
scheduleId | Step 2 | From the time slot response |
startDate / endDate | Step 2 | YYYY-MM-DDThh:mm:ss format |
timezone | Step 2 | IANA tz format |
resource.id | Step 2 | From availableResources in time slot response |
location.locationType | — | Must be OWNER_BUSINESS, OWNER_CUSTOM, or CUSTOM. Time Slots returns BUSINESS but that value is not accepted here |
{
"booking": {
"bookedEntity": {
"slot": {
"serviceId": "<SERVICE_ID>",
"eventId": "<EVENT_ID>"
}
},
"contactDetails": {
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com"
},
"totalParticipants": 1
}
}When you provide eventId, all other slot fields (startDate, endDate, timezone, resource, location) are auto-derived from the event. You only need serviceId + eventId.
{
"booking": {
"bookedEntity": {
"schedule": {
"scheduleId": "<SCHEDULE_ID>",
"serviceId": "<SERVICE_ID>",
"timezone": "America/New_York",
"location": {
"locationType": "OWNER_BUSINESS"
}
}
},
"contactDetails": {
"firstName": "Bob",
"lastName": "Test",
"email": "bob@example.com"
},
"totalParticipants": 1
}
}Specify exactly one of:
totalParticipants — for services with fixed pricing and no variantsparticipantsChoices — for services with variants and options (opens in a new tab)Booking is created with status: CREATED. This is not yet visible in the booking calendar. You must either:
Endpoint: POST https://www.wixapis.com/_api/bookings-service/v2/bookings/<BOOKING_ID>/confirm
{
"revision": "<REVISION>",
"paymentStatus": "EXEMPT"
}Use the id and revision from the Create Booking response. Set paymentStatus to EXEMPT for free services or NOT_PAID for pay-at-location.
Result: Booking status changes to CONFIRMED and is visible in the booking calendar.
4a. Create Checkout
Endpoint: POST https://www.wixapis.com/ecom/v1/checkouts
{
"lineItems": [
{
"catalogReference": {
"catalogItemId": "<BOOKING_ID>",
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97"
},
"quantity": 1
}
],
"channelType": "WEB"
}Use the booking ID as catalogItemId with the Wix Bookings app ID.
4b. Get Checkout URL
Endpoint: POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/getCheckoutUrl
Redirect the user to the returned checkoutUrl. After payment, the booking is automatically confirmed.
4c. Create Order (alternative, server-to-server)
Endpoint: POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder
Creates an order directly without redirect.
| Service Type | bookedEntity | Availability API | Key Difference |
|---|---|---|---|
| APPOINTMENT | slot (all fields required) | Time Slots V2 | Single session, specific time, needs resource + scheduleId |
| CLASS | slot (only serviceId + eventId) | Event Time Slots | Group session, auto-derives fields from event |
| COURSE | schedule | Check capacity via Query Extended Bookings | Multi-session, books entire schedule |