Technical Step-by-Step Instructions: Configuring Wix Bookings Service Policies (Real-World, API-First)
Description
Below are the recommended steps to successfully configure booking, cancellation, and waitlist policies for Wix Bookings services. This recipe covers policy inheritance, service-specific overrides, and common policy configurations for different business models.
Overview
Wix Bookings policy configuration allows businesses to set rules for:
- Booking policies: When customers can book, how far in advance, booking deadlines
- Cancellation policies: Cancellation deadlines, refund rules, fees
- Waitlist policies: When waitlists are enabled, capacity handling
- Group booking policies: Maximum participants per booking
Policies are standalone entities managed by the Booking Policies API (/bookings/v1/booking-policies), not fields nested on the service:
- Installing Wix Bookings creates a "Default policy" (
default: true) that every new service references. - Each service points at exactly one policy via its
bookingPolicyfield; many services can share a policy. - To change rules site-wide, update the default policy. To give one service different rules, create a separate policy and reference it from that service.
IMPORTANT NOTES
- A default policy exists on any site with Wix Bookings installed — even before any service exists. "Set a cancellation window" is always actionable by updating the default policy.
- Policy updates are PATCH-style: send only the sub-policies you want to change, plus the current
revision(fetched via query/get) inside thebookingPolicyobject. - Policy options are the same across service types (APPOINTMENT, CLASS, COURSE).
Steps
1. Find the Policy to Change
Query existing policies (POST https://www.wixapis.com/bookings/v1/booking-policies/query):
{ "query": { "cursorPaging": { "limit": 100 } } }For a site-wide change, pick the policy with "default": true. For a specific service, read the service first — its embedded bookingPolicy.id names the policy it uses. Save the policy's id and revision.
2. Update the Policy
PATCH https://www.wixapis.com/bookings/v1/booking-policies/<POLICY_ID> with the current revision inside the bookingPolicy object and only the sub-policies you're changing. Example — cancellations allowed up to 24 hours before the session:
{
"bookingPolicy": {
"id": "<POLICY_ID>",
"revision": "<CURRENT_REVISION>",
"cancellationPolicy": {
"enabled": true,
"limitLatestCancellation": true,
"latestCancellationInMinutes": 1440
}
}
}Field map (business rule → policy field):
| Business rule | Sub-policy fields |
|---|---|
| Cancellation deadline | cancellationPolicy.{enabled, limitLatestCancellation, latestCancellationInMinutes} |
| Reschedule deadline | reschedulePolicy.{enabled, limitLatestReschedule, latestRescheduleInMinutes} |
| How far ahead customers can book | limitEarlyBookingPolicy.{enabled, earliestBookingInMinutes} |
| Booking notice / last-minute cutoff | limitLateBookingPolicy.{enabled, latestBookingInMinutes} |
| Booking after session start (courses/classes) | bookAfterStartPolicy.enabled |
| Waitlist | waitlistPolicy.{enabled, capacity, reservationTimeInMinutes} |
| Participants per booking | participantsPolicy.{enabled, maxParticipantsPerBooking} |
3. Per-Service Policies (Optional)
To give one service different rules, create a new policy (POST https://www.wixapis.com/bookings/v1/booking-policies) and point the service at it by updating the service's bookingPolicy reference (see Update Service).
4. Verify Policy Application
Read the service (GET /bookings/v2/services/<SERVICE_ID>) — the response embeds the full resolved bookingPolicy, so you can confirm the effective rules exactly as customers will experience them.
IMPORTANT NOTES
- Revision required: Every policy update needs the current
revisioninsidebookingPolicy; fetch it first, or the PATCH fails. - Partial updates: Send only the sub-policies you're changing; the rest keep their values.
- Enabled flags matter: Each sub-policy has an
enabled(and often alimit*) boolean — setting only the minutes value without enabling the limit has no effect. - Time calculations: Policy deadlines are calculated from the booking's start time, in minutes (24 hours = 1440).
Troubleshooting Common Issues
Policies not applying:
- Policies are separate entities — verify you PATCHed
/bookings/v1/booking-policies/<id>, not fields on the service object (there is noservice.policyfield) - Confirm the service actually references the policy you changed (
service.bookingPolicy.id) - Check the
revisionwas current — a stale revision fails the update
Waitlist not working:
- Verify
waitlistPolicy.enabledistrueandwaitlistPolicy.capacityis set - Confirm the service has capacity configured (
defaultCapacityfor CLASS/COURSE)
Cancellation policies not enforced:
- Set all three fields together:
cancellationPolicy.enabled: true,limitLatestCancellation: true, andlatestCancellationInMinutes— the minutes value alone has no effect without the booleans
Group booking limits not working:
- Confirm
participantsPolicy.enabledistrueandparticipantsPolicy.maxParticipantsPerBookingis set - Check that the booking UI respects the participant limit
API Documentation References
- Query Booking Policies —
POST https://www.wixapis.com/bookings/v1/booking-policies/query - Update Booking Policy —
PATCH https://www.wixapis.com/bookings/v1/booking-policies/{bookingPolicy.id} - Create Booking Policy —
POST https://www.wixapis.com/bookings/v1/booking-policies - Bulk Create Services —
POST https://www.wixapis.com/bookings/v2/bulk/services/create - Update Service —
PATCH https://www.wixapis.com/bookings/v2/services/<SERVICE_ID> - Query Services —
POST https://www.wixapis.com/bookings/v2/services/query