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. Wix Bookings automatically calculates business opening hours based on the businessSchedule field from the site properties.

The schedule always has the same externalId with the value 4e0579a5-491e-4e70-a872-d097eed6e520. To access the business schedule, call Query Schedules with a filter based on this external ID.

To retrieve events for the business schedule, call Query Events with a query filter specifying externalScheduleId in the query.filter.

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.