About the Events API

The Events API lets you manage calendar entries for a schedule. Events inherit default values from their schedule, ensuring consistency across related events. However, you can override each event's default values as needed.

To set up recurring events, define an event with recurrencePattern - known as the MASTER event. Then, INSTANCE events that hold details for each occurrence are automatically created based on this pattern.

With the Events API, you can:

• Create and update single-occurrence and MASTER events.
• Create EXCEPTION events by updating an INSTANCE event.
• Retrieve events.
• Cancel events.
• Track in real-time when an event is created or modified.

For more in-depth event management, see:

• Schedules API
• Events View API
• Participations API
• Bookings APIs

Before you begin

It’s important to note the following points before starting to code:

• An event must belong to exactly one schedule.
• You can't create instances of recurring events. Instead, Wix Calendars automatically creates INSTANCE events when you set a recurrenceRule in the MASTER event.
• Currently, you can define recurrence patterns based only on weeks. For example, every week or every 3 weeks. You can't define recurrence rules based on days, months, or years yet.
• To schedule a recurring event on multiple days of the week, you must currently define separate MASTER events. For example, if an event recurs on Mondays, Wednesdays, and Fridays, you need to set up 3 distinct MASTER events.
• You can't directly create exceptions for recurring events. When you update an INSTANCE event, Wix Calendars automatically changes its recurrenceType to EXCEPTION.
• By default, WORKING_HOURS events aren't returned in Query Events.
• You can't directly manage participants on an event. Use the Participations API to do so.

Use cases

• Manage a calendar.
• Sync calendars to an external system.

Terminology

• Event: A calendar entry that includes details such as timing, location, and participants. Each event is associated with a schedule and can inherit default values. Events can be standalone or part of a recurring series. They can block time or allow concurrent scheduling on the calendar.
• Recurrence type: Information about whether the event is a single occurrence, defines a recurring series, or is part of a recurring series.
  • NONE: An event that takes place only once. Single-occurrence events don't include a recurrenceRule.
  • MASTER event: Defines the recurrence pattern for a series of recurring events.
  • INSTANCE event: A specific occurrence within a recurring series. You can't directly create an event with {"recurrenceType": "INSTANCE"}, instead it's automatically generated based on the recurrence rule. When you update an INSTANCE, it automatically changes to an EXCEPTION.
  • EXCEPTION event: A modified instance within a recurring series. For example, an event with a different time or location. Exceptions are created automatically when you modify an INSTANCE event.
• Role: You can assign permissions to Wix users to control their access to an event. For more details, see the permissions article.
  • Writer: Can read and modify the event.
  • Commenter: Can read the event and modify the event notes.
• Status: Indicates whether an event can be updated or if it’s permanently CANCELLED.
• Type: Specifies whether the event adds WORKING_HOURS to a schedule. Bookings APIs also use this field to indicate if the event is an APPOINTMENT, CLASS, or COURSE.