# About the Events V3 API

With the Events API you can create and manage events on a site. This API can be used to create sites for events like concerts, sport camps, city tours, weddings, and more. 

The Events API allows you to:  

- [Create](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/create-event) an event by defining some properties, such as location, date and time, and registration type. 
- [Clone](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/clone-event) an existing event while changing some details or none.
- [Update](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/update-event) an event with the latest information about the event.
- [Publish a draft event](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/publish-draft-event) if you initially created an event as a draft.
- [Retrieve](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/get-event) or [query](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/query-events) events.
- Bulk [delete](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/bulk-delete-events-by-filter) or [cancel](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/bulk-cancel-events-by-filter) events by a filter. Save time and effort when managing event by removing or canceling multiple events at once based on specific filters.

## Before you begin

It's important to note the following before starting to code:

- A site must have [Wix Events & Tickets](fallback::https://www.wix.com/app-market/web-solution/events) installed.
- When an event is created as a ticketed event, it can't be updated to an RSVP event and vice versa.
- When there is 1 day left until the event, an automated reminder notification is sent to the guests.


## Event registration types

These registration types define what type of event customers are registering for:

- **Ticketing**: Customers register by buying tickets.  
    You can create and sell tickets, set currency, and handle taxes. For more information, see the [Ticket Definitions API](fallback::https://dev.wix.com/docs/rest/business-solutions/events/ticket-definitions-v3/introduction).  
- **RSVP**: Customers register by responding with an RSVP without buying tickets. Invitees can RSVP whether they're going to an event.  
    If the guest limit is reached, you can open a waitlist. Additionally, a user can set whether guests can see the other guests attending the event.
- **External**: Customers register by either buying tickets or RSVPing on an external platform.  
    You can display events on a Wix site while enabling ticket sales or RSVP management through an external platform.
- **No registration**: Customers don't register. This is for displaying events only.

## Event scheduling and recurrence

When defining an event, the event must have a date and time. The event can be either single or recurring:

- **Single event**: Happens once and can last multiple days, like a 3-day conference.
- **Recurring event**: A series of events that repeat, like a workshop that happens once a week. Once you publish the recurring event, you can manage the dates for each individual separately. 

## Event locations

The event can happen in:

- **Physical location**: The event happens in a specific venue or physical space, like a conference hall or concert venue.
- **Online**: The event happens online through a video conference.


## Defining event registration:

- All events initially have a `registration.type` of either `RSVP` or `TICKETING`, which is the same as the `registration.initialType` property. This `type` can't be updated. 
- To manage event registration externally using another platform, provide an external event registration URL in the `registration.external.url` field. After doing this, the registration type becomes `EXTERNAL`, and directs guests to the specified external URL for registration. The existing guest list, originally managed by the Events API, still exists but no longer is maintained by the API. Make sure to manage the guest list from the external platform.
- To indicate that guests don't need to register for the event, you can set the `registration.registrationDisabled` property to `true`. After doing this, the `registration.type` value becomes `NONE`.

## Use cases

- [Cancel a concert tour and refund money to customers](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/sample-use-cases-and-flows)
- [Send reminders to guests before the event](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/sample-use-cases-and-flows)

## Terminology

- **Event**: A gathering that an individual or a business holds for a group of people.
- **RSVP**: A response from the guest indicating whether they plan to attend the event.
- **Registration**: The process by which individuals sign up to attend an event.  
- **Attendee**: An individual who plans to, or has registered to, participate in an event.    
- **Category**: A classification assigned to events based on their purpose or theme.
- **Organizer**: The person or entity responsible for planning and hosting the event.
- **TBD**: Event locations and dates can be "to be determined" yet the event can still be created and offered.

# Events v3: Supported Filters and Sorting

The following table shows field support for filters and sorting for the Events object:

| Field                                  | Query Filter Operators                                                | Sortable |
|----------------------------------------|-----------------------------------------------------------------------|----------|
| `id`                                   | `$eq`, `$ne`, `$in`, `$hasSome`  | Sortable |
| `title`                                | `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`  | Sortable |
| `slug`                                 | `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`  | Sortable |   
| `updatedDate`                          | `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`  | Sortable |
| `createdDate`                          | `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`  | Sortable |
| `status`                               | `$eq`, `$ne`, `$in`, `$hasSome`                                | Sortable |
| `userId`                               | `$eq`, `$ne`, `$in`, `$hasSome`                                | Sortable |
| `registration.initialType`             | `$eq`                               | Not sortable |
| `dateAndTimeSettings.startDate`        | `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`  | Sortable |
| `dateAndTimeSettings.endDate`          | `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`  | Sortable |


__Related content:__
[API Query Language](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::8158a590-f60c-4606-9fed-16a34e275f3a*fallback::https://dev.wix.com/api/rest/getting-started/api-query-language),
[Events Query endpoint](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/query-events)

# Events v3: Sample Use Cases & Flows

This article presents possible use cases and corresponding sample flows that your app can support. It provides a useful starting point as you plan your app's implementation. 

## Cancel a concert tour and send cancellation emails for customers

This use case demonstrates the automation of event cancellation. For example, when a concert tour is canceled, the Events API allows you to bulk cancel all scheduled concerts simultaneously. Additionally, automated cancellation emails can be sent to notify customers about the tour cancellation, providing essential information and any available alternatives or refunds.

To cancel events and send cancellation emails, follow these steps:

1. [Query Event Guests](fallback::https://dev.wix.com/docs/rest/business-solutions/events/event-guests/query-event-guests) by `eventId` of the events that are going to be cancelled.

1. Retrieve all the email addresses from the `guestDetails` object, and write your code so that the email address can be passed to your marketing tool.

1. On an ongoing basis, listen for the [Event Canceled Webhook](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/event-canceled). 

1. [Bulk Cancel Events by Filter](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/bulk-cancel-events-by-filter). Specify `categoryId` of the recurring events in the filter object to cancel all events.

1. When the webhook is triggered for your event, send the cancellation email from your marketing tool.

## Send reminders to guests before an event

Send timely notifications and important details leading up to the event for your attendees. Organizers can schedule automated reminders to be sent to registered attendees a specific number of days or hours before the event:

- 7 days
- 3 days
- 1 day
- 2 hours
- 1 hour
- 30 minutes

These reminders can include event date, time, location, agenda, and any additional instructions or updates. This use case reduces the likelihood of no-shows, and enhances attendee engagement.

To send reminders, follow these steps:

1. [Query Event Guests](fallback::https://dev.wix.com/docs/rest/business-solutions/events/event-guests/query-event-guests) by `eventId`.

1. Retrieve all the email addresses from the `guestDetails` object, and write your code so that the email addresses can be passed to your marketing tool.

1. On an ongoing basis, listen for [Event Reminder Webhook](fallback::https://dev.wix.com/docs/rest/business-solutions/events/events-v3/event-reminder). 

1. When the webhook is triggered for your event, send the reminder email from your marketing tool.

Query Events