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:
- Wix Bookings - Core app must be installed and configured
- Wix Ecommerce - Required for payment processing (undocumented dependency)
- Services Created - At least one bookable service must exist on the site
- Staff Resources - Staff members must be available for service delivery
- Business Schedule - Operating hours must be configured
If you encounter service-related errors, install the required apps using the Apps Installer API.
For detailed app installation procedures, refer to:
- Apps Installer API Documentation
- Business setup recipes for comprehensive app installation workflows
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:
- Single Appointment Bookings: How booking payments actually work
- Class Bookings: Payment processing for group services
- Course Bookings: Complex dual-API requirements for scheduling
- Multi-Service Packages: Completely undocumented unified booking endpoint
The Universal Undocumented Pattern: Bookings→Ecommerce Integration Architecture
Documentation Status Across ALL Booking Types:
- ❌ NOT documented how booking IDs become catalog items
- ❌ NOT documented that ecom system handles all pricing/tax calculations
- ❌ NOT documented async payment confirmation patterns
- ❌ NOT documented booking status vs order status separation
- ❌ NOT documented service properties preservation in checkout
- ❌ NO mention of
BACKOFFICE_MERCHANT channel requirement
- ❌ NO explanation of why checkout/order APIs are needed for bookings
Additional Service-Specific Gaps:
- ❌ Courses: Dual API requirement (booking + calendar events) completely undocumented
- ❌ Multi-Service: Entire endpoint missing from all documentation
- ❌ Payment Flow: Universal integration pattern affects all booking types
What Developers Expect (Based on Documentation):
- Create booking → Booking system handles payment → Done
- Payment status managed within booking system
- Booking APIs contain all necessary functionality
Actual Undocumented Architecture:
- Create booking → Booking system creates reservation only
- Use booking ID as catalog item in ecom system
- Ecom system handles all pricing, tax, discount calculations
- Create checkout and order for actual payment processing
- Async messaging system handles payment confirmation
- Booking status (CONFIRMED) independent of payment status
Reality Check:
Without Understanding Universal Integration Patterns:
- Developers assume booking creation includes payment processing
- No knowledge that ecom system handles all financial calculations
- Missing understanding of async payment confirmation architecture
- Confusion about booking status vs payment status separation
- Unknown relationship between booking system and ecommerce system
Without Service-Specific Knowledge:
- Course businesses cannot create functioning course delivery schedules
- Package-based businesses cannot create unified booking experiences
- Payment implementation becomes trial-and-error process
- Integration projects fail due to missing critical steps
Current Developer Confusion Patterns:
- "Why do I need ecommerce APIs for booking payments?"
- "How do booking payments actually work?"
- "Why are my course bookings invisible on the calendar?"
- "How do I create spa day packages?"
- "What's the difference between booking status and payment status?"
- Universal Integration Gap: Every booking requiring payment uses undocumented ecom integration
- Service Type Complexity: Different booking structures but same payment patterns
- Async Architecture: Payment confirmation decoupled from booking creation
- Status Separation: Booking confirmation independent of payment processing
- Hidden Dependencies: Ecommerce system required for all booking payments
- Business Model Impact: Documentation gaps prevent entire business models
CRITICAL DISCOVERY: All Wix booking payments flow through undocumented ecommerce integration.
The Hidden Architecture:
- Booking System: Handles time slot reservations, service coordination, scheduling
- Ecommerce System: Handles pricing, tax calculations, discount processing, payment collection
- Integration Bridge: Booking IDs automatically become catalog item IDs
Universal Pattern (Works for ALL Service Types):
Different service types use different booking structures but same payment integration:
Appointments: Use bookedEntity.slot with all required fields
Critical: All slot fields (scheduleId, resource.id, location.locationType, timezone) are required for appointments. Omitting any of them returns a 400 error. The locationType must be OWNER_BUSINESS (not BUSINESS which is what Time Slots V2 returns).
Classes: Use bookedEntity.slot with eventId (auto-derives other fields)
Courses: Use bookedEntity.schedule structure + require separate calendar events
Use standard booking creation APIs with service-specific structures:
Standard Booking Endpoint: POST https://www.wixapis.com/_api/bookings-service/v2/bookings (REST)
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 bookings- Service-appropriate
bookedEntity 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:
- Participant enrollment and payment processing works
- No visible sessions on business calendar
- Staff unaware of when/where to conduct sessions
- Course delivery schedule missing
Required Additional Step for Courses:
Create calendar events using POST https://www.wixapis.com/calendar/v3/bulk/events/create (REST):
Critical: Each element in the events array must be wrapped in { "event": {...} }. The resources array with at least one resource ID is required for CLASS/COURSE events — without it the API returns 400. start/end fields and externalScheduleId are 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:
- Spa packages (massage + facial + manicure as single booking)
- Beauty services (cut + color + styling as unified experience)
- Wellness programs (consultation + treatment + follow-up coordination)
Undocumented Requirements:
- Identical contact information across all services in package
- Sequential service timing coordination (second service start = first service end)
skipAvailabilityValidation: true for back-to-back scheduling
MAJOR 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)
Step 6B: Create Order for Payment Processing
Endpoint: POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder
Critical Architecture Discoveries:
- Automatic ID Transformation: Booking IDs automatically valid as catalog item IDs
- Service Properties Preserved: Booking context (scheduledDate, numberOfParticipants) maintained
- Pricing Calculation: Ecom system handles all financial calculations (not booking system)
- Item Type Assignment:
"preset": "SERVICE" automatically applied
Payment Processing Architecture:
Status Management Patterns:
- Booking Status: CONFIRMED (reserves time slot regardless of payment)
- Order Status: PAID/NOT_PAID (reflects payment processing outcome)
- Business Logic: Time slot reservation independent of payment success
Operational Benefits:
- Payment failures don't lose reserved time slots
- Supports multiple payment models (prepaid, deposits, invoicing)
- Retry payment without recreating complex booking coordination
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:
- All service types use same checkout/order creation pattern
- Pricing calculations always handled by ecom system
- Async payment confirmation applies to all booking types
- Service properties preserved across all integration points
- Universal Integration Required: Every booking payment flows through ecommerce system
- Service-Specific Booking Creation: Different booking structures for different service types
- Courses Require Dual APIs: Booking system + calendar events system
- Multi-Service Endpoint Undocumented: Complete gap for package-based businesses
- Async Payment Architecture: Payment confirmation decoupled from booking creation
- Status Independence: Booking confirmation separate from payment processing
- Hidden Ecommerce Dependency: Not mentioned in any booking documentation
Booking ID Not Working as Catalog Item:
- Verify booking was created successfully and has valid ID
- Ensure using correct Wix Bookings app ID in catalog reference
- Check that booking status is CONFIRMED before attempting checkout
Course Bookings Not Visible on Calendar:
- Course bookings handle enrollment only, not session scheduling
- Must create calendar events separately using calendar API
- Session scheduling independent of participant enrollment
Payment Status Confusion:
- Booking status (CONFIRMED) indicates time slot reservation
- Order status (PAID/NOT_PAID) indicates payment processing outcome
- These statuses operate independently through async messaging
Multi-Service Booking Failures:
- Contact details must be identical across all services in package
- Service timing must be precisely coordinated (end time = next start time)
- Resource allocation requires manual verification with
skipAvailabilityValidation
Ecommerce Integration Errors:
- Verify ecommerce app is installed and enabled
- Ensure using
"BACKOFFICE_MERCHANT" channel type for owner flows
- Check that service pricing is properly configured in booking system
Headless Implementation:
- No documented SDK methods for booking→ecom integration
- Manual API orchestration required for payment processing
- Frontend developers must understand backend integration patterns
Mobile Integration:
- Booking creation patterns differ across service types
- Payment flow design requires understanding async confirmation
- Course management requires dual API coordination
Third-Party Integration:
- Booking export may not include payment status information
- External calendar systems may not receive course session details
- CRM integration requires understanding booking vs payment status separation
Payment Model Planning:
- Booking system reserves capacity, ecom system processes payments
- Multiple payment models supported (full prepaid, deposits, invoicing)
- Refund processing requires coordination between both systems
Service Type Planning:
- Appointments: Immediate booking and payment
- Classes: Group bookings with participant management
- Courses: Long-term enrollment with session scheduling
- Packages: Unified experience across multiple services
Scaling Considerations:
- Integration complexity increases with service variety
- Payment processing load handled by ecommerce system
- Booking coordination managed by booking system
- Analytics require data from both systems
Documented APIs (That Don't Explain Integration Requirements):
- Standard Booking Flow - Missing payment integration
- Create Booking - No payment processing guidance
- Service Types - Missing integration patterns
- Ecommerce Checkout - No booking integration mention
Completely Undocumented:
- Booking→Ecom Integration: Universal pattern affecting all booking payments
- Multi-Service Bookings:
https://manage.wix.com/_api/bookings-service/v2/multi_service_bookings
- Course Calendar Requirements: Dual API necessity for course functionality
- Async Payment Confirmation: Messaging system architecture
- Status Separation Patterns: Booking vs payment status independence