Setting the file. One moment.
Subchapter 8.9
references/bookings/booking-system-integration-gaps.mdMarkdown17 KBView on GitHub
This recipe addresses critical undocumented API patterns and business integration gaps across the entire Wix Bookings ecosystem. While Wix extensively documents individual booking creation APIs, there exist fundamental undocumented integration patterns that are essential for any payment-enabled booking business but completely absent from all official documentation sources.
Before implementing any booking integration, ensure the following requirements are met:
If you encounter service-related errors, install the required apps using the Apps Installer API.
For detailed app installation procedures, refer to:
The Wix Bookings system contains fundamental undocumented integration patterns that affect every booking scenario requiring payment processing. These gaps create confusion and implementation barriers across all booking types:
The Universal Undocumented Pattern: Bookings→Ecommerce Integration Architecture
Documentation Status Across ALL Booking Types:
BACKOFFICE_MERCHANT channel requirementAdditional Service-Specific Gaps:
What Developers Expect (Based on Documentation):
Actual Undocumented Architecture:
Reality Check:
Standard Documentation Shows: Booking API → Payment ✓
Actual Required Flow: Booking API → Ecom Integration → Payment ✓Without Understanding Universal Integration Patterns:
Without Service-Specific Knowledge:
Current Developer Confusion Patterns:
CRITICAL DISCOVERY: All Wix booking payments flow through undocumented ecommerce integration.
The Hidden Architecture:
Universal Pattern (Works for ALL Service Types):
Create Booking → Extract Booking ID → Use as Catalog Item ID → Create Checkout → Create Order → Process PaymentDifferent service types use different booking structures but same payment integration:
Appointments: Use bookedEntity.slot with all required fields
{
"booking": {
"bookedEntity": {
"slot": {
"serviceId": "<SERVICE_ID>",
"scheduleId": "<SCHEDULE_ID>",
"startDate": "2024-06-14T14:00:00",
"endDate": "2024-06-14T15:15:00",
"timezone": "America/New_York",
"resource": { "id": "<RESOURCE_ID>" },
"location": { "locationType": "OWNER_BUSINESS" }
}
},
"contactDetails": {
"firstName": "John",
"email": "john@example.com"
},
"totalParticipants": 1
}
}Critical: All slot fields (
scheduleId,resource.id,location.locationType,timezone) are required for appointments. Omitting any of them returns a 400 error. ThelocationTypemust beOWNER_BUSINESS(notBUSINESSwhich is what Time Slots V2 returns).
Classes: Use bookedEntity.slot with eventId (auto-derives other fields)
{
"booking": {
"bookedEntity": {
"slot": {
"serviceId": "<SERVICE_ID>",
"eventId": "<EVENT_ID>"
}
},
"contactDetails": {
"firstName": "Jane",
"email": "jane@example.com"
},
"totalParticipants": 1
}
}Courses: Use bookedEntity.schedule structure + require separate calendar events
{
"booking": {
"bookedEntity": {
"schedule": {
"scheduleId": "<SCHEDULE_ID>",
"serviceId": "<SERVICE_ID>",
"timezone": "America/New_York",
"location": { "locationType": "OWNER_BUSINESS" }
}
},
"contactDetails": {
"firstName": "Bob",
"email": "bob@example.com"
},
"totalParticipants": 1
}
}Use standard booking creation APIs with service-specific structures:
Standard Booking Endpoint: POST https://www.wixapis.com/_api/bookings-service/v2/bookings (REST (opens in a new tab))
Critical Parameters for All Types:
booking.contactDetails — at minimum firstName and emailbooking.totalParticipants — number of participantsselectedPaymentOption: "OFFLINE" — for ecom integration flowsflowControlSettings.skipBusinessConfirmation: true — for administrative bookingsbookedEntity structure (see Step 2 above)MAJOR DISCOVERY: Courses require dual API implementation - booking alone is insufficient.
Course Booking Problem: Creating course booking without calendar sessions results in:
Required Additional Step for Courses:
Create calendar events using POST https://www.wixapis.com/calendar/v3/bulk/events/create (REST (opens in a new tab)):
{
"events": [{
"event": {
"type": "COURSE",
"scheduleId": "<COURSE_SCHEDULE_ID>",
"externalScheduleId": "<STAFF_RESOURCE_ID>",
"start": { "localDate": "2025-06-16T09:00:00" },
"end": { "localDate": "2025-06-16T10:00:00" },
"resources": [{ "id": "<STAFF_RESOURCE_ID>" }],
"recurrenceRule": {
"frequency": "WEEKLY",
"interval": 1,
"days": ["MONDAY"],
"until": { "localDate": "2025-08-11T23:59:59" }
}
}
}]
}Critical: Each element in the
eventsarray must be wrapped in{ "event": {...} }. Theresourcesarray with at least one resource ID is required for CLASS/COURSE events — without it the API returns 400.start/endfields andexternalScheduleIdare also required.
CRITICAL UNDOCUMENTED ENDPOINT: For businesses requiring unified package experiences.
Endpoint: POST https://manage.wix.com/_api/bookings-service/v2/multi_service_bookings
Business Use Cases:
Undocumented Requirements:
skipAvailabilityValidation: true for back-to-back schedulingMAJOR DISCOVERY: ALL booking payments use identical ecommerce integration pattern.
Step 6A: Create Checkout with Booking ID as Catalog Item
Endpoint: POST https://www.wixapis.com/ecom/v1/checkouts (REST (opens in a new tab))
{
"lineItems": [{
"catalogReference": {
"catalogItemId": "<BOOKING_ID>",
"appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97"
},
"quantity": 1
}],
"channelType": "WEB"
}Step 6B: Create Order for Payment Processing
Endpoint: POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder
Critical Architecture Discoveries:
"preset": "SERVICE" automatically appliedPayment Processing Architecture:
Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
↓
Messaging System
↓
Final Status UpdatesStatus Management Patterns:
Operational Benefits:
Single Appointments: Basic booking + ecom integration Group Classes: Booking with participant count + ecom integration Course Programs: Booking + calendar events + ecom integration Service Packages: Multi-service booking + ecom integration
Universal Integration Considerations:
Booking ID Not Working as Catalog Item:
Course Bookings Not Visible on Calendar:
Payment Status Confusion:
Multi-Service Booking Failures:
skipAvailabilityValidationEcommerce Integration Errors:
"BACKOFFICE_MERCHANT" channel type for owner flowsHeadless Implementation:
Mobile Integration:
Third-Party Integration:
Payment Model Planning:
Service Type Planning:
Scaling Considerations:
Documented APIs (That Don’t Explain Integration Requirements):
Completely Undocumented:
https://manage.wix.com/_api/bookings-service/v2/multi_service_bookings