Work with Calendar APIs to Schedule and Manage Bookings

Wix Bookings scheduling involves 2 groups of APIs. The Wix Bookings APIs manage availability and external calendar connections.

The Calendar APIs let you read and update calendar events and schedules directly. Most use cases only need read access, since Bookings manages these automatically when you create or update services, staff, resources, or bookings.

Wix Bookings APIs

Use these APIs to manage scheduling in the Bookings product.

Calendar APIs

Use these APIs to read or update the calendar data that Bookings writes to.

How Bookings uses the Calendar APIs

This section describes the key integration points between Wix Bookings and the Calendar APIs, including how resources map to schedules, how to filter calendar data to Bookings context, and how the business schedule works.

Resources and calendar integration

Each Wix Bookings service has an associated Calendar schedule. When an appointment booking is confirmed, Wix Bookings creates a calendar event on that schedule and on the schedules of any assigned staff members or resources, preventing double-booking.

Resources work differently depending on their type:

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

Business schedule

Each business has a main schedule that defines its operating hours, identified by the external ID 4e0579a5-491e-4e70-a872-d097eed6e520.

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

Find working hour event IDs

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

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

Modify working hours

• Adjust existing hours: Call Update Event with the master event ID to change the recurring pattern.
• Add working hours: Call Create Event with "type": "WORKING_HOURS", "recurrenceType": "MASTER", the relevant recurrenceRule, and the business schedule ID as scheduleId.
• Remove a working day: Call Cancel Event with the master event ID.
• Block time off:
  • Single day: Call Cancel Event to remove the 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 period. The system creates a one-off blocking event by default.
  • Recurring pattern: Call Create Event with "recurrenceType": "MASTER" and the relevant recurrenceRule. The system creates a DEFAULT type event whose instances block availability.

Filter by app ID

When querying schedules in a Wix Bookings context, filter by the Bookings app ID (13d21c63-b5ec-5912-8397-c3a5ddb27a97) to return only Bookings-related schedules. The Bookings calendar display applies this filter, so your integrations should use it too.

Time zones

Wix Bookings uses the IANA Time Zone Database for all scheduling calculations. See About Time Zones for details on how to return slots in a customer's local time zone and how time zone changes affect existing sessions.

See also

• Bookings Time Slots V2 API
• About Time Zones
• Architecture and Data Flow