How Wix Bookings Uses the Calendar APIs

This article explains how Wix Bookings integrates with the Calendar APIs to manage scheduling, and provides migration guidance for developers moving from deprecated APIs.

Overview

Wix Bookings uses the Calendar APIs to manage all scheduling and availability for businesses. This unified approach handles appointments, classes, courses, and resource scheduling through a single calendar system, replacing the previous deprecated Bookings-specific calendar APIs.

With the Calendar APIs you can:

• Manage schedules via the Schedules API.
• Manage events with the Events API.
• Determine the start date of a schedule's first event and the end date of its last event with the Schedule Time Frames API.
• Manage event participants and their participation status with the Participations API.

For external calendar integration, use the Bookings External Calendar V2 API which remains active under Bookings to connect with providers such as Google, Microsoft, and Apple calendars.

Implementation specifics

Resource and calendar integration

Every bookable item in Wix Bookings connects to the calendar system to manage availability and prevent conflicts. All resources have an event schedule - this is their calendar that shows when they're booked and contains information about all related bookings.

Resources work differently depending on their type:

• Staff member resources have both an event schedule (when they're booked) and a working hour schedule (when they're available to work). You must manage them through the Staff Members API.
• Non-staff resources (like meeting rooms or equipment) have only an event schedule. Their availability depends on their location's business hours.

App ID filtering

When working with schedules in a Wix Bookings context, you need to filter data to show only Bookings-related schedules. Wix Bookings uses a dedicated app ID (13d21c63-b5ec-5912-8397-c3a5ddb27a97) when creating schedules.

Why this matters: The Bookings calendar display filters schedules to show only those with this specific app ID, ensuring proper data isolation. If you're building integrations that display calendar data, you should apply the same filtering to maintain consistency with the Bookings interface.

Business schedule management

Each business has a main schedule that defines its operating hours and availability. The business schedule always uses the externalId value 4e0579a5-491e-4e70-a872-d097eed6e520.

By default, each business has 5 recurring WORKING_HOURS events, 1 for each weekday (Monday through Friday) from 10 AM to 6 PM. These MASTER events set the recurrence pattern that Wix Calendars uses to automatically calculate INSTANCE events. Learn more about recurring events.

To identify the IDs of the 5 MASTER events, retrieve at least 1 of their corresponding INSTANCE events. Call Query Events, specifying a date range that covers at least a full week and a query filter like this:

For each weekday's INSTANCE working hour event that's returned, save its id, recurringEventId, and scheduleId. The recurringEventId is the id of the corresponding MASTER event, which defines the recurrence pattern. All 5 weekday INSTANCE events share a scheduleId, which is the business schedule's id.

To modify working hours:

• Adjust existing hours: Call Update Event with the relevant master event ID to change the recurring pattern. For example, shift hours from 10 AM–6 PM to 9 AM–5 PM.
• Add working hours: Call Create Event to add additional events of "type": "WORKING_HOURS", "recurrenceType": "MASTER", and the relevant recurrenceRule. Specify the business schedule id as the event's scheduleId. For example, add Saturday hours or an evening shift.
• Remove a working day: Call Cancel Event with the master event ID to remove that day from the schedule.
• Block holidays or time off: Choose the appropriate method based on your blocking pattern:
  • Single day: Call Cancel Event to remove the day's INSTANCE event, or Update Event to shorten its hours.
  • Longer period: Call Create Event with the business schedule ID as scheduleId and start and end dates spanning the entire period. For example, 2 weeks of summer vacation. Don't specify recurrenceType, the system creates a one-off blocking event by default.
  • Recurring pattern: Call Create Event with the business schedule ID as scheduleId, "recurrenceType": "MASTER", and the relevant recurrenceRule. The system creates a DEFAULT type event whose instances block availability.

External calendar integration

The Bookings External Calendar V2 API provides integration with external calendar providers such as Google Calendar, Microsoft Calendar, and Apple Calendar. This API enables bidirectional synchronization between Wix Bookings and external calendars. Businesses can import events from external calendars and export Wix Bookings events to external calendars.

Migrate from deprecated Bookings calendar APIs

To migrate from deprecated Bookings Calendar APIs to the new Calendar V3 APIs:

1. Update API methods: Replace all Bookings calendar methods with corresponding Calendar API methods.
2. App ID filtering: Implement app ID filtering using 13d21c63-b5ec-5912-8397-c3a5ddb27a97 for all Bookings-related schedules.
3. Business schedule access: Use the fixed "externalId": "4e0579a5-491e-4e70-a872-d097eed6e520" when managing the business schedule.
4. Event retrieval: To retrieve events for a specific schedule, call Query Events with a query filter specifying the relevant schedule ID in the query.filter.
5. External calendar integration: No changes needed - Continue using the Bookings External Calendar V2 API for external calendar connections and synchronization. This API remains active and is not affected by the calendar API migration.