> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # ListEvents # Package: calendar # Namespace: EventsService # Method link: https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/list-events.md ## Permission Scopes: Read Calendar: SCOPE.DC-CALENDAR.READ-PUBLIC Read Calendar - Including PI: SCOPE.DC-CALENDAR.READ-PI ## Introduction Retrieves a list of events by their IDs. --- ## REST API ### Schema ``` Method: listEvents Description: Retrieves a list of events by their GUIDs. URL: https://www.wixapis.com/calendar/v3/events Method: GET # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: eventIds Method parameters: query param name: eventIds | type: array | description: IDs of the events to retrieve. Min: 1 event GUID Max: 100 event GUIDs | required: true query param name: fields | type: array | description: Information about which fields containing personal data to return. Refer to the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md) for more information. Supported values: + `PI_FIELDS`: Returns all fields with personal data. Your app must have `Read Calendars - Including PI` or `Manage Calendars` permission scope. + `OWN_PI_FIELDS`: Returns only fields containing your own personal data. Max: 1 field Default: No personal data is returned. - enum: - PI_FIELDS: Returns all fields with personal data. Your app must have `Read Calendars - Including PI` or `Manage Calendars` permission scope. - OWN_PI_FIELDS: Returns only fields containing your own personal data. query param name: timeZone | type: timeZone | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database) for calculating `adjustedStart` and `adjustedEnd`. For example, `America/New_York` or `UTC`. Default: `timeZone` specified in the business [site properties](https://dev.wix.com/docs/rest/business-management/site-properties/properties/get-site-properties.md). Return type: ListEventsResponse - name: events | type: array | description: Retrieved events matching the provided GUIDs. - name: id | type: string | description: Event GUID. - name: scheduleId | type: string | description: GUID of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) the event belongs to. After creating an event, you can't assign it to a different schedule. - name: externalScheduleId | type: string | description: GUID of the external schedule the event belongs to. For example, if the event belongs to a Bookings staff member, identical to the GUID of the [resource](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members-and-resources/resource-v2/resource-object.md). If the schedule belongs to a Bookings service, identical to the GUID of the [service](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/service-object.md). - name: scheduleName | type: string | description: Schedule name. - name: type | type: string | description: Event type. You can set the event type but you can't update it. Supported values: + `DEFAULT`: A standard event that's not further specified. + `WORKING_HOURS`: The event adds working hours to a schedule. By default not returned in [Query Events](https://dev.wix.com/docs/rest/business-management/calendar/events-v3/query-events.md). To retrieve working hour events, specify `"type": "WORKING_HOURS"` in the query filter. Additional supported values, if Wix Bookings is installed: + `APPOINTMENT`: Bookings appointment event. + `CLASS`: Bookings class event. + `COURSE`: Bookings course event. - name: status | type: Status | description: Event status. Supported values: + `CONFIRMED`: Event is scheduled to happen or has happened. + `CANCELLED`: Event has been canceled. Default: `CONFIRMED` - enum: - CONFIRMED: Event is scheduled to happen or has happened. - CANCELLED: Event has been canceled. - name: title | type: string | description: Event title. Min: 1 character Max: 200 characters - name: start | type: ZonedDate | description: Information about when the event starts. - name: localDate | type: string | description: Local date time in [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2024-01-30T13:30:00`. Wix Calendar APIs ignore seconds. - name: timeZone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database). For example, `America/New_York`. - name: utcDate | type: string | description: UTC date time in [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2024-01-30T13:30:00`. Not available for adjusted date fields. - name: end | type: ZonedDate | description: Information about when the event ends. Maximum allowed date: Year 2100, or up to 100 years from the event's start date (whichever comes first). - name: adjustedStart | type: ZonedDate | description: Information about when the event starts adjusted to the `timeZone` of the business [site properties](https://dev.wix.com/docs/rest/business-management/site-properties/properties/properties-object.md) or a different `timeZone` you provide in the call's request. - name: adjustedEnd | type: ZonedDate | description: Information about when the event ends adjusted to the `timeZone` of the business [site properties](https://dev.wix.com/docs/rest/business-management/site-properties/properties/properties-object.md) or a different `timeZone` you provide in the call's request. - name: timeZone | type: string | description: Time zone the event is associated with in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database). Only regional time zones and UTC are supported. For example, `America/New_York` or `UTC`. Default: `timeZone` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md). - name: allDay | type: boolean | description: Whether the event spans one or more full days. When `true`, `start` and `end` represent full-day boundaries: + `start.localDate`: First day at `00:00:00`. + `end.localDate`: Day after the last day at `00:00:00` (exclusive). Midnight boundaries are interpreted in the event's `timeZone`. Default: `false` - name: recurrenceType | type: RecurrenceType | description: Information about whether the event is a single occurrence or part of a recurring series. Supported values: + `NONE`: The event occurs only once and doesn't repeat. + `MASTER`: Defines the recurrence pattern for a series of recurring events. + `INSTANCE`: A specific occurrence of a recurring event. You can't create an event with `{"recurrenceType": "INSTANCE"}`, instead it's automatically generated based on the recurrence rule. If you update an `INSTANCE` event, `recurrenceType` automatically changes to `EXCEPTION`. + `EXCEPTION`: A modified instance of a recurring event that differs from the recurrence pattern. For example, an event with a different time or location. You can't create an `EXCEPTION` event directly, instead it's set automatically when you update an `INSTANCE` event. Default: `NONE` - enum: - NONE: The event occurs only once and doesn't repeat. - MASTER: Defines the recurrence pattern for a series of recurring events. - INSTANCE: A specific occurrence of a recurring event. You can't create an event with `{"recurrenceType": "INSTANCE"}`, instead it's automatically generated based on the recurrence rule. If you update an `INSTANCE` event, `recurrenceType` automatically changes to `EXCEPTION`. - EXCEPTION: A modified instance of a recurring event that differs from the recurrence pattern. For example, an event with a different time or location. You can't create an `EXCEPTION` event directly, instead it's set automatically when you update an `INSTANCE` event. - name: recurrenceRule | type: RecurrenceRule | description: Recurrence pattern for a series of events. This field is required when creating a `MASTER` event and isn't available for non-recurring events. You can't update the recurrence rule for `INSTANCE` or `EXCEPTION` events. For example, an event that repeats every second Monday until January 7, 2026, at 8:00 AM has the following `recurrenceRule`: - `frequency = WEEKLY` - `interval = 2` - `days = [MONDAY]` - `until = 20260107T08:00:00Z` - name: frequency | type: Frequency | description: Frequency how often the event repeats. Works together with `interval`. Supported values: + `WEEKLY`: The event's recurrence pattern is based on weeks. - enum: UNKNOWN_FREQUENCY, WEEKLY - name: interval | type: integer | description: Interval how often the event repeats. Works together with `frequency`. For example, `frequency` set to `WEEKLY` and `interval` set to `2` means the event repeats every 2 weeks. Min: `1` Max: `4` Default: `1` - name: days | type: array | description: Days of the week when the recurring event takes place. Currently, only a single day is supported. Min: 1 day Max: 1 day - enum: - MONDAY: The recurring event takes place on Mondays. - TUESDAY: The recurring event takes place on Tuesdays. - WEDNESDAY: The recurring event takes place on Wednesday. - THURSDAY: The recurring event takes place on Thursdays. - FRIDAY: The recurring event takes place on Fridays. - SATURDAY: The recurring event takes place on Saturdays. - SUNDAY: The recurring event takes place on Sundays. - name: until | type: ZonedDate | description: Date until when the event repeats. If not specified, the event repeats forever. - name: adjustedUntil | type: ZonedDate | description: Date until when the event repeats adjusted to the `timeZone` of the business [site properties](https://dev.wix.com/docs/rest/business-management/site-properties/properties/properties-object.md) or a different `timeZone` you provide in the call's request. - name: recurringEventId | type: string | description: GUID of the `MASTER` event the event belongs to. Available only for `INSTANCE` and `EXCEPTION` events. - name: transparency | type: Transparency | description: Specifies whether the event blocks time in the schedule it belongs to. Supported values: + `OPAQUE`: The schedule is blocked during the event, preventing other events that involve the same entities (for example, Booking staff members) from being scheduled at the same time. + `TRANSPARENT`: The schedule remains open during the event, allowing other events to be scheduled concurrently. Default: `OPAQUE` - enum: - UNKNOWN_TRANSPARENCY: - OPAQUE: The schedule is blocked during the event, preventing other events that involve the same entities (for example, Booking staff members) from being scheduled at the same time. - TRANSPARENT: The schedule remains open during the event, allowing other events to be scheduled concurrently. - name: location | type: Location | description: Event location. Default: `defaultLocation` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) the event belongs to - name: id | type: string | description: [Location](https://dev.wix.com/docs/rest/business-management/locations/location-object.md) GUID. Available only for `BUSINESS` locations. - name: type | type: Type | description: Location type. Supported values: + `BUSINESS`: The event is held at a business location. + `CUSTOMER`: The event is held at the customer's location, such as their home or office. + `CUSTOM`: The event is held at an address or venue not tied to the business or customer. - enum: - BUSINESS: The event is held at a business location. - CUSTOMER: The event is held at the customer's location, such as their home or office. - CUSTOM: The event is held at an address or venue not tied to the business or customer. - name: name | type: string | description: Location name. For `BUSINESS` locations, it's identical to the [location](https://dev.wix.com/docs/rest/business-management/locations/location-object.md) `name`. Min: 1 character Max: 150 characters - name: address | type: string | description: Location address. For `BUSINESS` locations, it's identical to the [location](https://dev.wix.com/docs/rest/business-management/locations/location-object.md)'s `formattedAddress`. - name: resources | type: array | description: List of [Wix Bookings resources](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members-and-resources/resource-v2/resource-object.md) affected by the event. This could include, for example, the [Wix Bookings staff member](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members-and-resources/staff-member-v1/staff-member-object.md) providing the service or the room where the appointment takes place. Max: 100 resources - name: id | type: string | description: Resource GUID. - name: name | type: string | description: Resource name. - name: type | type: string | description: Resource type. - name: transparency | type: Transparency | description: Specifies whether the event blocks time in the resource's schedule. Supported values: + `OPAQUE`: The schedule is blocked during the event, preventing other events that involve the same resource from being scheduled at the same time. + `TRANSPARENT`: The schedule remains open during the event, allowing other events to be scheduled concurrently. Default: `OPAQUE`. - name: permissionRole | type: Role | description: Permission role associated with the resource. Refer to the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#roles) for more information. - enum: - WRITER: Full read and write access. - COMMENTER: Full read access, write access limited to `event.notes`. - name: totalCapacity | type: integer | description: Maximum number of participants who can participate in the event. Default: `defaultCapacity` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) the event belongs to - name: remainingCapacity | type: integer | description: Number of participants who can still be added to the event. - name: participants | type: Participants | description: Information about the event's participants. Returned only if explicitly requested. For more details, see the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#retrieve-personal-information). - name: total | type: integer | description: Total number of participants. Min: `0` - name: list | type: array | description: Full or partial list of the participants. Max: 50 participants - name: name | type: string | description: Participant name. Min: 1 character Max: 200 characters - name: phone | type: string | description: Participant's phone number. - name: email | type: string | description: Participant's email address. - name: contactId | type: string | description: [Contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/contacts/contact-v4/contact-object.md) GUID of the participant. - name: hasMore | type: boolean | description: Whether there are more participants for the event than listed. + `false`: The list includes all participants. + `true`: The list doesn't include all participants. - name: status | type: Status | description: Participant's status. Supported values: + `CONFIRMED`: All participants are confirmed. + `PENDING_CONFIRMATION`: At least one participant isn't confirmed yet. - enum: - CONFIRMED: All participants are confirmed. - PENDING_CONFIRMATION: At least one participant isn't confirmed yet. - name: conferencingDetails | type: ConferencingDetails | description: Information about the event's online conferencing. Returned only if explicitly requested. For more details, see the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#retrieve-personal-information). Default: `defaultConferencingDetails` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) the event belongs to - name: type | type: Type | description: Conference type. For example, `Zoom`. - enum: UNKNOWN_TYPE, ZOOM, CUSTOM - name: hostUrl | type: string | description: URL used by the host to start the conference. Min: 1 character Max: 2000 characters - name: guestUrl | type: string | description: URL used by a guest to join the conference. Min: 1 character Max: 2000 characters - name: password | type: string | description: Conference password. Min: 1 character Max: 100 characters - name: externalId | type: string | description: Conference GUID in an external system. Min: 1 character Max: 150 characters - name: notes | type: string | description: Additional notes about the event. Returned only if explicitly requested. For more details, see the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#retrieve-personal-information). Min: 1 character Max: 5000 characters - name: inheritedFields | type: array | description: List of fields whose values are inherited. + For single-occurrence events, values are inherited from the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md). + For `INSTANCE` and `EXCEPTION` events, values are inherited from the related `MASTER` event. - enum: - TITLE: `title` is inherited from the schedule or `MASTER` event. - TIME_ZONE: `timeZone` is inherited from the schedule or `MASTER` event. - TIME: `start` and `end` are inherited from the `MASTER` event. - LOCATION: `location` is inherited from the schedule or `MASTER` event. - RESOURCES: `resources` is inherited from the `MASTER` event. - CAPACITY: `capacity` is inherited from the schedule or `MASTER` event. - PARTICIPANTS: `participants` is inherited from the `MASTER` event. - CONFERENCING_DETAILS: `conferencingDetails` is inherited from the schedule or `MASTER` event. - name: appId | type: string | description: GUID of the app that owns the event. Identical to `appId` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) to which the event belongs. For events from Wix apps, the following values apply: - Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` - Wix Services: `"cc552162-24a4-45e0-9695-230c4931ef40"` - Wix Meetings: `"6646a75c-2027-4f49-976c-58f3d713ed0f"`. [Full list of apps created by Wix](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md). - name: permissions | type: array | description: List of permissions associated with the event. Refer to the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#roles) for more information. - name: identity | type: IdentificationData | description: [Wix user](https://dev.wix.com/docs/build-apps/develop-your-app/access/about-identities.md#wix-users) granted the permission. - ONE-OF: - name: wixUserId | type: string | description: GUID of a Wix user. For example, the site owner or a [site collaborator](https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site). - name: role | type: Role | description: Permission role. Supported values: + `WRITER`: Full read and write access. + `COMMENTER`: Full read access, write access limited to `event.notes`. - name: extendedFields | type: ExtendedFields | description: Extensions enabling applications or users to save custom data related to the event. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: revision | type: string | description: Revision number, which increments each time the event is updated. To prevent conflicting changes, the current revision must be passed when updating the event. Ignored when creating an event. - name: createdDate | type: string | description: Date the event was created in `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: updatedDate | type: string | description: Date the event was last updated in `YYYY-MM-DDThh:mm:ss.sssZ` format. ``` ### Examples ### List Events ```curl curl -X GET \ 'https://www.wixapis.com/calendar/v3/events?eventIds=WqKyhiYgLmblyVmHFnjazbmCJKK01ACZM79rgdVqUHjcIrX84YfDON2IdaFegGtRpk1wger3lHBXTvzXqrCCoZSzauJtGzjfam5hcT4q4qCTx3CctxC6D2&eventIds=VYAN5iNZkOn1SQ5LLJVWXxdGqRfcnyxpZ2STCAr7l6RswqhNAvAXfO7o59cEoDfhwVTtXUIhN6JM5bb7MDprhwwf3DPqQ6CBgry0qfF6OfXn1tEEqMcwPA' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.calendar.EventsService.listEvents(eventIds, options) Description: Retrieves a list of events by their GUIDs. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: eventIds Method parameters: param name: eventIds | type: array | description: IDs of the events to retrieve. Min: 1 event GUID Max: 100 event GUIDs | required: true param name: options | type: ListEventsOptions none - name: timeZone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database) for calculating `adjustedStart` and `adjustedEnd`. For example, `America/New_York` or `UTC`. Default: `timeZone` specified in the business [site properties](https://dev.wix.com/docs/rest/business-management/site-properties/properties/get-site-properties.md). - name: fields | type: array | description: Information about which fields containing personal data to return. Refer to the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md) for more information. Supported values: + `PI_FIELDS`: Returns all fields with personal data. Your app must have `Read Calendars - Including PI` or `Manage Calendars` permission scope. + `OWN_PI_FIELDS`: Returns only fields containing your own personal data. Max: 1 field Default: No personal data is returned. - enum: - PI_FIELDS: Returns all fields with personal data. Your app must have `Read Calendars - Including PI` or `Manage Calendars` permission scope. - OWN_PI_FIELDS: Returns only fields containing your own personal data. Return type: PROMISE - name: events | type: array | description: Retrieved events matching the provided GUIDs. - name: _id | type: string | description: Event GUID. - name: scheduleId | type: string | description: GUID of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) the event belongs to. After creating an event, you can't assign it to a different schedule. - name: externalScheduleId | type: string | description: GUID of the external schedule the event belongs to. For example, if the event belongs to a Bookings staff member, identical to the GUID of the [resource](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members-and-resources/resource-v2/resource-object.md). If the schedule belongs to a Bookings service, identical to the GUID of the [service](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/service-object.md). - name: scheduleName | type: string | description: Schedule name. - name: type | type: string | description: Event type. You can set the event type but you can't update it. Supported values: + `DEFAULT`: A standard event that's not further specified. + `WORKING_HOURS`: The event adds working hours to a schedule. By default not returned in [Query Events](https://dev.wix.com/docs/rest/business-management/calendar/events-v3/query-events.md). To retrieve working hour events, specify `"type": "WORKING_HOURS"` in the query filter. Additional supported values, if Wix Bookings is installed: + `APPOINTMENT`: Bookings appointment event. + `CLASS`: Bookings class event. + `COURSE`: Bookings course event. - name: status | type: Status | description: Event status. Supported values: + `CONFIRMED`: Event is scheduled to happen or has happened. + `CANCELLED`: Event has been canceled. Default: `CONFIRMED` - enum: - CONFIRMED: Event is scheduled to happen or has happened. - CANCELLED: Event has been canceled. - name: title | type: string | description: Event title. Min: 1 character Max: 200 characters - name: start | type: ZonedDate | description: Information about when the event starts. - name: localDate | type: string | description: Local date time in [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2024-01-30T13:30:00`. Wix Calendar APIs ignore seconds. - name: timeZone | type: string | description: Time zone in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database). For example, `America/New_York`. - name: utcDate | type: Date | description: UTC date time in [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601). For example, `2024-01-30T13:30:00`. Not available for adjusted date fields. - name: end | type: ZonedDate | description: Information about when the event ends. Maximum allowed date: Year 2100, or up to 100 years from the event's start date (whichever comes first). - name: adjustedStart | type: ZonedDate | description: Information about when the event starts adjusted to the `timeZone` of the business [site properties](https://dev.wix.com/docs/rest/business-management/site-properties/properties/properties-object.md) or a different `timeZone` you provide in the call's request. - name: adjustedEnd | type: ZonedDate | description: Information about when the event ends adjusted to the `timeZone` of the business [site properties](https://dev.wix.com/docs/rest/business-management/site-properties/properties/properties-object.md) or a different `timeZone` you provide in the call's request. - name: timeZone | type: string | description: Time zone the event is associated with in [IANA tz database format](https://en.wikipedia.org/wiki/Tz_database). Only regional time zones and UTC are supported. For example, `America/New_York` or `UTC`. Default: `timeZone` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md). - name: allDay | type: boolean | description: Whether the event spans one or more full days. When `true`, `start` and `end` represent full-day boundaries: + `start.localDate`: First day at `00:00:00`. + `end.localDate`: Day after the last day at `00:00:00` (exclusive). Midnight boundaries are interpreted in the event's `timeZone`. Default: `false` - name: recurrenceType | type: RecurrenceType | description: Information about whether the event is a single occurrence or part of a recurring series. Supported values: + `NONE`: The event occurs only once and doesn't repeat. + `MASTER`: Defines the recurrence pattern for a series of recurring events. + `INSTANCE`: A specific occurrence of a recurring event. You can't create an event with `{"recurrenceType": "INSTANCE"}`, instead it's automatically generated based on the recurrence rule. If you update an `INSTANCE` event, `recurrenceType` automatically changes to `EXCEPTION`. + `EXCEPTION`: A modified instance of a recurring event that differs from the recurrence pattern. For example, an event with a different time or location. You can't create an `EXCEPTION` event directly, instead it's set automatically when you update an `INSTANCE` event. Default: `NONE` - enum: - NONE: The event occurs only once and doesn't repeat. - MASTER: Defines the recurrence pattern for a series of recurring events. - INSTANCE: A specific occurrence of a recurring event. You can't create an event with `{"recurrenceType": "INSTANCE"}`, instead it's automatically generated based on the recurrence rule. If you update an `INSTANCE` event, `recurrenceType` automatically changes to `EXCEPTION`. - EXCEPTION: A modified instance of a recurring event that differs from the recurrence pattern. For example, an event with a different time or location. You can't create an `EXCEPTION` event directly, instead it's set automatically when you update an `INSTANCE` event. - name: recurrenceRule | type: RecurrenceRule | description: Recurrence pattern for a series of events. This field is required when creating a `MASTER` event and isn't available for non-recurring events. You can't update the recurrence rule for `INSTANCE` or `EXCEPTION` events. For example, an event that repeats every second Monday until January 7, 2026, at 8:00 AM has the following `recurrenceRule`: - `frequency = WEEKLY` - `interval = 2` - `days = [MONDAY]` - `until = 20260107T08:00:00Z` - name: frequency | type: Frequency | description: Frequency how often the event repeats. Works together with `interval`. Supported values: + `WEEKLY`: The event's recurrence pattern is based on weeks. - enum: UNKNOWN_FREQUENCY, WEEKLY - name: interval | type: integer | description: Interval how often the event repeats. Works together with `frequency`. For example, `frequency` set to `WEEKLY` and `interval` set to `2` means the event repeats every 2 weeks. Min: `1` Max: `4` Default: `1` - name: days | type: array | description: Days of the week when the recurring event takes place. Currently, only a single day is supported. Min: 1 day Max: 1 day - enum: - MONDAY: The recurring event takes place on Mondays. - TUESDAY: The recurring event takes place on Tuesdays. - WEDNESDAY: The recurring event takes place on Wednesday. - THURSDAY: The recurring event takes place on Thursdays. - FRIDAY: The recurring event takes place on Fridays. - SATURDAY: The recurring event takes place on Saturdays. - SUNDAY: The recurring event takes place on Sundays. - name: until | type: ZonedDate | description: Date until when the event repeats. If not specified, the event repeats forever. - name: adjustedUntil | type: ZonedDate | description: Date until when the event repeats adjusted to the `timeZone` of the business [site properties](https://dev.wix.com/docs/rest/business-management/site-properties/properties/properties-object.md) or a different `timeZone` you provide in the call's request. - name: recurringEventId | type: string | description: GUID of the `MASTER` event the event belongs to. Available only for `INSTANCE` and `EXCEPTION` events. - name: transparency | type: Transparency | description: Specifies whether the event blocks time in the schedule it belongs to. Supported values: + `OPAQUE`: The schedule is blocked during the event, preventing other events that involve the same entities (for example, Booking staff members) from being scheduled at the same time. + `TRANSPARENT`: The schedule remains open during the event, allowing other events to be scheduled concurrently. Default: `OPAQUE` - enum: - UNKNOWN_TRANSPARENCY: - OPAQUE: The schedule is blocked during the event, preventing other events that involve the same entities (for example, Booking staff members) from being scheduled at the same time. - TRANSPARENT: The schedule remains open during the event, allowing other events to be scheduled concurrently. - name: location | type: Location | description: Event location. Default: `defaultLocation` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) the event belongs to - name: _id | type: string | description: [Location](https://dev.wix.com/docs/rest/business-management/locations/location-object.md) GUID. Available only for `BUSINESS` locations. - name: type | type: Type | description: Location type. Supported values: + `BUSINESS`: The event is held at a business location. + `CUSTOMER`: The event is held at the customer's location, such as their home or office. + `CUSTOM`: The event is held at an address or venue not tied to the business or customer. - enum: - BUSINESS: The event is held at a business location. - CUSTOMER: The event is held at the customer's location, such as their home or office. - CUSTOM: The event is held at an address or venue not tied to the business or customer. - name: name | type: string | description: Location name. For `BUSINESS` locations, it's identical to the [location](https://dev.wix.com/docs/rest/business-management/locations/location-object.md) `name`. Min: 1 character Max: 150 characters - name: address | type: string | description: Location address. For `BUSINESS` locations, it's identical to the [location](https://dev.wix.com/docs/rest/business-management/locations/location-object.md)'s `formattedAddress`. - name: resources | type: array | description: List of [Wix Bookings resources](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members-and-resources/resource-v2/resource-object.md) affected by the event. This could include, for example, the [Wix Bookings staff member](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members-and-resources/staff-member-v1/staff-member-object.md) providing the service or the room where the appointment takes place. Max: 100 resources - name: _id | type: string | description: Resource GUID. - name: name | type: string | description: Resource name. - name: type | type: string | description: Resource type. - name: transparency | type: Transparency | description: Specifies whether the event blocks time in the resource's schedule. Supported values: + `OPAQUE`: The schedule is blocked during the event, preventing other events that involve the same resource from being scheduled at the same time. + `TRANSPARENT`: The schedule remains open during the event, allowing other events to be scheduled concurrently. Default: `OPAQUE`. - name: permissionRole | type: Role | description: Permission role associated with the resource. Refer to the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#roles) for more information. - enum: - WRITER: Full read and write access. - COMMENTER: Full read access, write access limited to `event.notes`. - name: totalCapacity | type: integer | description: Maximum number of participants who can participate in the event. Default: `defaultCapacity` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) the event belongs to - name: remainingCapacity | type: integer | description: Number of participants who can still be added to the event. - name: participants | type: Participants | description: Information about the event's participants. Returned only if explicitly requested. For more details, see the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#retrieve-personal-information). - name: total | type: integer | description: Total number of participants. Min: `0` - name: list | type: array | description: Full or partial list of the participants. Max: 50 participants - name: name | type: string | description: Participant name. Min: 1 character Max: 200 characters - name: phone | type: string | description: Participant's phone number. - name: email | type: string | description: Participant's email address. - name: contactId | type: string | description: [Contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/contacts/contact-v4/contact-object.md) GUID of the participant. - name: hasMore | type: boolean | description: Whether there are more participants for the event than listed. + `false`: The list includes all participants. + `true`: The list doesn't include all participants. - name: status | type: Status | description: Participant's status. Supported values: + `CONFIRMED`: All participants are confirmed. + `PENDING_CONFIRMATION`: At least one participant isn't confirmed yet. - enum: - CONFIRMED: All participants are confirmed. - PENDING_CONFIRMATION: At least one participant isn't confirmed yet. - name: conferencingDetails | type: ConferencingDetails | description: Information about the event's online conferencing. Returned only if explicitly requested. For more details, see the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#retrieve-personal-information). Default: `defaultConferencingDetails` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) the event belongs to - name: type | type: Type | description: Conference type. For example, `Zoom`. - enum: UNKNOWN_TYPE, ZOOM, CUSTOM - name: hostUrl | type: string | description: URL used by the host to start the conference. Min: 1 character Max: 2000 characters - name: guestUrl | type: string | description: URL used by a guest to join the conference. Min: 1 character Max: 2000 characters - name: password | type: string | description: Conference password. Min: 1 character Max: 100 characters - name: externalId | type: string | description: Conference GUID in an external system. Min: 1 character Max: 150 characters - name: notes | type: string | description: Additional notes about the event. Returned only if explicitly requested. For more details, see the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#retrieve-personal-information). Min: 1 character Max: 5000 characters - name: inheritedFields | type: array | description: List of fields whose values are inherited. + For single-occurrence events, values are inherited from the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md). + For `INSTANCE` and `EXCEPTION` events, values are inherited from the related `MASTER` event. - enum: - TITLE: `title` is inherited from the schedule or `MASTER` event. - TIME_ZONE: `timeZone` is inherited from the schedule or `MASTER` event. - TIME: `start` and `end` are inherited from the `MASTER` event. - LOCATION: `location` is inherited from the schedule or `MASTER` event. - RESOURCES: `resources` is inherited from the `MASTER` event. - CAPACITY: `capacity` is inherited from the schedule or `MASTER` event. - PARTICIPANTS: `participants` is inherited from the `MASTER` event. - CONFERENCING_DETAILS: `conferencingDetails` is inherited from the schedule or `MASTER` event. - name: appId | type: string | description: GUID of the app that owns the event. Identical to `appId` of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/schedule-object.md) to which the event belongs. For events from Wix apps, the following values apply: - Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` - Wix Services: `"cc552162-24a4-45e0-9695-230c4931ef40"` - Wix Meetings: `"6646a75c-2027-4f49-976c-58f3d713ed0f"`. [Full list of apps created by Wix](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md). - name: permissions | type: array | description: List of permissions associated with the event. Refer to the [permissions article](https://dev.wix.com/docs/rest/business-management/calendar/permissions.md#roles) for more information. - name: identity | type: IdentificationData | description: [Wix user](https://dev.wix.com/docs/build-apps/develop-your-app/access/about-identities.md#wix-users) granted the permission. - ONE-OF: - name: wixUserId | type: string | description: GUID of a Wix user. For example, the site owner or a [site collaborator](https://support.wix.com/en/article/inviting-people-to-contribute-to-your-site). - name: role | type: Role | description: Permission role. Supported values: + `WRITER`: Full read and write access. + `COMMENTER`: Full read access, write access limited to `event.notes`. - name: extendedFields | type: ExtendedFields | description: Extensions enabling applications or users to save custom data related to the event. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: revision | type: string | description: Revision number, which increments each time the event is updated. To prevent conflicting changes, the current revision must be passed when updating the event. Ignored when creating an event. - name: _createdDate | type: Date | description: Date the event was created in `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: _updatedDate | type: Date | description: Date the event was last updated in `YYYY-MM-DDThh:mm:ss.sssZ` format. ``` ### Examples ### listEvents ```javascript import { events } from '@wix/calendar'; async function listEvents(eventIds,options) { const response = await events.listEvents(eventIds,options); }; ``` ### listEvents (with elevated permissions) ```javascript import { events } from '@wix/calendar'; import { auth } from '@wix/essentials'; async function myListEventsMethod(eventIds,options) { const elevatedListEvents = auth.elevate(events.listEvents); const response = await elevatedListEvents(eventIds,options); } ``` ### listEvents (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { events } from '@wix/calendar'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { events }, // Include the auth strategy and host as relevant }); async function listEvents(eventIds,options) { const response = await myWixClient.events.listEvents(eventIds,options); }; ``` ---