# About the Events API

The Events API lets you manage calendar entries for a
[schedule](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/schedules/introduction).
Events inherit [default values](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/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](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/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](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/schedules/introduction)
+ [Events View API](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/event-views/introduction)
+ [Participations API](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/participations/introduction)
+ [Bookings APIs](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/introduction)

## 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 [queryEvents()](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/query-events).
+ You can't directly manage `participants` on an event. Use the
  [Participations API](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/participations/introduction)
  to do so.

## Use cases

+ [Manage a calendar](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/sample-flows#manage-a-calendar).
+ [Sync calendars to an external system](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/sample-flows#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](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/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](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/access/about-identities#wix-users)
  to control their access to an event. For more details, see the
  [permissions article](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/permissions#roles-for-events).
  + **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](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/schedules/introduction).
  [Bookings APIs](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/introduction)
  also use this field to indicate if the event is an `APPOINTMENT`, `CLASS`, or `COURSE`.

@package_metadata:@wix/calendar

To use the Events API, install the `@wix/calendar` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/calendar` using the [Wix CLI](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/calendar` or `yarn add @wix/calendar`. |
| Headless sites and apps | Run `npm install @wix/calendar` or `yarn add @wix/calendar`. |

#### Import the package

To import the package in your code:

```js
import { events } from '@wix/calendar'
```

# Recurring Events

Recurring events repeat based on a pattern defined by a `recurrenceRule`.
For example, weekly yoga classes or regular staff working hours. To create a
recurring event, specify a `recurrenceRule` when
[creating an event](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/create-event). 
This event, known as a `MASTER` event, defines the recurrence for the series. Wix
Calendars then automatically generates `INSTANCE` events in the series.

## Recurrence Rule

The `recurrenceRule` sets the repeat pattern for recurring events, with the
following properties:

- `frequency`: The interval unit for recurrence. Currently, only `WEEKLY` frequency is supported.
- `interval`: Determines how often the event recurs. For example, every week or every 2 weeks.
- `days`: Specifies the days of the week the event occurs. For example, `MONDAY`.
- `until` (optional): Sets an end date to stop repeating.

## Instances and Exceptions

Individual occurrences in a recurring series are automatically generated and
have a `recurrenceType` of `INSTANCE`.

If an instance is modified (for example, to adjust the time or location), it
becomes an `EXCEPTION`. Even if the `EXCEPTION` is later updated to revert the
modifications, its `recurrenceType` remains `EXCEPTION`. The event's `id`
remains constant throughout its lifecycle.

However, the ID of an `INSTANCE` event may change. This can happen, for example,
when the relevant `MASTER` event's `recurrenceRule` is modified.

## Update `MASTER` events

Changes made to a `MASTER` event only affect future `INSTANCE` events, while past
instances remain unchanged to preserve historical accuracy. Use
[updateEvent()](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/update-event)
to modify the `MASTER` event.

### Split recurring event

If you want to apply modifications starting from a specific future date that's after
the very next `INSTANCE` event, use
[splitRecurringEvent()](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/split-recurring-event)
first. This splits the original `MASTER` event into 2, shortening the original
and creating a second `MASTER` event. Then, use
[updateEvent()](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/update-event)
on the new `MASTER` event to apply your adjustments.

bulkCancelEvent( )