About Events v3
With the Events API you can create and manage events on your site. This API can be used to create sites for concerts, sport camps, city tours, weddings, and so on.
The Events API allows you to:
- Create/clone an event. Create an event by defining some properties, such as location, date and time, registration type, etc. In case you have several similar events, you don't have to create a new one each time. You can quickly clone an existing event and refine it by changing some of the properties.
- Update event with the newest information about the event.
- Publish draft event if you firstly created an event as a draft.
- List events by category to have a full list of events that belong to the same category.
- Get/Query events to get information about each individual event that matches a filter.
- Bulk delete/cancel events by filter. Save time and effort when managing event by removing/canceling multiple events at once based on specific filters.
More about events
The main defining characteristics for events are:
-
Registration types. These registration types define what type of event they are registering for:
- Ticketing: Customers register by buying tickets.
You can create and sell tickets, set currency, handle taxes. For more information, see the Ticket Definitions API. - 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, user can set whether guests can see other guests attending the event. - External: Customers register by either buying tickets or RSVPing on an external platform.
You can display events on your site, while enabling ticket sales or RSVP management through an external platform. - No registration: Customers do not register. This is for displaying events only.
- Ticketing: Customers register by buying tickets.
-
Date and time. 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.
-
Location. 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.
Before you begin
It’s important to note the following points before starting to code:
- Install the Wix Events & Tickets app from Wix App Market.
- When an event is created as a ticketed event, it cannot 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 your customer.
When defining event registration:
- All events initially have a
registration.type
of eitherRSVP
orTICKETING
, which is the same as theregistration.initialType
property (this property remains unchanged). - 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 becomesEXTERNAL
, 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 do not need to register for the event, you can set the
registration.registrationDisabled
property totrue
. After doing this, theregistration.type
value becomesNONE
.
Use cases
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: To be determined.
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, Events Query endpoint
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:
-
Query Event Guests by
eventId
of the events that are going to be cancelled. -
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. -
On an ongoing basis, listen for the Event Canceled Webhook.
-
Bulk Cancel Events by Filter. Specify
categoryId
of the recurring events in the filter object to cancel all events. -
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:
-
Query Event Guests by
eventId
. -
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. -
On an ongoing basis, listen for Event Reminder Webhook.
-
When the webhook is triggered for your event, send the reminder email from your marketing tool.
Event ID.
Event location.
Event date and time settings.
Event title.
Short description that appears under the event title.
Note: This field is returned only when the DETAILS fieldset is included in the request.
Detailed description of an event. You can enter the description using rich text format (add various types of markups, such as underlines, italics, bolding, color codes, bullet lists, and links by using HTML formatting tags).
Note: This field is returned only when the TEXTS fieldset is included in the request.
Main event image.
Note: This field is returned only when the DETAILS fieldset is included in the request.
Unique identifier of the event page. The naming is the same as the event title written in kebab case. For example, if your event title is "Leather Crafting 101", then the slug is "leather-crafting-101".
Date and time when the event was created.
Date and time when the event was updated.
Event status. Possible values:
- UPCOMING: Event is published and scheduled to start.
- STARTED: Event has started.
- ENDED: Event has ended.
- CANCELED: Event is canceled.
- DRAFT: Event is not published.
RSVP or ticketing registration details.
Note: This field is returned only when the REGISTRATION fieldset is included in the request.
URLs that allow you to add an event to the Google calendar, or to download an ICS calendar file.
Note: This field is returned only when the DETAILS fieldset is included in the request.
Event page URL components.
Note: This field is returned only when the URLS fieldset is included in the request.
Event registration form.
Note: This field is returned only when the FORM fieldset is included in the request.
Summary of RSVP or ticket sales.
Note: This field is returned only when the DASHBOARD fieldset is included in the request and you have the "WIX_EVENTS.READ_EVENT_DASHBOARD" permissions.
Instance ID of the site where the event is hosted.
Guest list configuration.
ID of the user who created the event.
Online conferencing details.
Note: This field is returned only when the ONLINE_CONFERENCING_SESSION fieldset is included in the request and you have the "WIX_EVENTS.READ_ONLINE_CONFERENCING" permissions.
SEO settings.
Note: This field is returned only when the SEO_SETTINGS fieldset is included in the request.
Assigned contacts label key.
Event schedule details.
Note: This field is returned only when the AGENDA fieldset is included in the request.
Visual settings for event.
Creates an event.
The event includes a default registration form in the selected language, which consists of input fields for first name, last name, and email. See Registration Form for more information.
You can create the event as a draft by setting the draft
value to true
. Otherwise, the event is published right away.
The event is automatically set up to send daily summary reports of new guests to your business email.
Permission Scopes
For app development, you must have one of the following permission scopes:Clones an event, including the registration form, notifications, multilingual translations and ticket configuration from the original event.
The new event's date is automatically set to 14 days from the original event date.
If an event with the same title already exists, the new event's title gets a sequence number. For example, if you clone an event named "Leather Crafting 101", the new event's title is "Leather Crafting 101 (1)".
You can change the required entity field values while cloning an event.
Permission Scopes
For app development, you must have one of the following permission scopes:Updates an event.
Permission Scopes
For app development, you must have one of the following permission scopes:Publishes a draft event to your live site. Once published, the event's status changes from DRAFT
to UPCOMING
.
It's impossible to revert the DRAFT
status after publishing. The only option is to clone the event, then delete the original one.
Permission Scopes
For app development, you must have one of the following permission scopes:Cancels an event.
After cancellation, registration for an event is closed. To reuse the event, clone and publish it again.
If event cancellation notifications are enabled, canceling an event automatically triggers the sending of cancellation emails and/or push notifications to registered guests.
Permission Scopes
For app development, you must have one of the following permission scopes:Cancels multiple events that meet the given criteria.
After cancellation, registration for an event is closed. To reuse the event, clone and publish it again.
If event cancellation notifications are enabled, canceling an event automatically triggers the sending of cancellation emails and/or push notifications to registered guests.
Permission Scopes
For app development, you must have one of the following permission scopes:Retrieves an event by ID.
Permission Scopes
For app development, you must have one of the following permission scopes:Permanently deletes an event.
You can retrieve the deleted event through a GDPR access request.
Permission Scopes
For app development, you must have one of the following permission scopes:Permanently deletes multiple events that meet the given criteria.
You can retrieve the deleted events through a GDPR access request.
Permission Scopes
For app development, you must have one of the following permission scopes:Retrieves a list of events, given the provided paging, filtering, and sorting. Query Events runs with these defaults, which you can override:
createdDate
is sorted inASC
orderpaging.limit
is100
paging.offset
is0
For field support for filters and sorting, see Events v3: Supported Filters and Sorting. To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.
Permission Scopes
For app development, you must have one of the following permission scopes:Counts events by status. To learn about working with query endpoints, see API Query Language, Sorting and Paging, and Field Projection.
Permission Scopes
For app development, you must have one of the following permission scopes:Retrieves an event by the slug URL.
Permission Scopes
For app development, you must have one of the following permission scopes:Triggered when an event is started.
Permission Scopes
For app development, you must have one of the following permission scopes:Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.events.v3.event.
Event name. Expected event_started.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
Triggered when a certain amount of time is left until the event. In total there are 6 reminders:
- 7 days
- 3 days
- 1 day
- 2 hours
- 1 hour
- 30 minutes
Permission Scopes
For app development, you must have one of the following permission scopes:Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.events.v3.event.
Event name. Expected event_reminder.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
Triggered when an event has ended.
Permission Scopes
For app development, you must have one of the following permission scopes:Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.events.v3.event.
Event name. Expected event_ended.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
Triggered when either draft or published event is created.
Permission Scopes
For app development, you must have one of the following permission scopes:Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.events.v3.event.
Event name. Expected created.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
Triggered when an event is published.
Permission Scopes
For app development, you must have one of the following permission scopes:Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.events.v3.event.
Event name. Expected event_published.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
Triggered when an event is updated.
Permission Scopes
For app development, you must have one of the following permission scopes:Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.events.v3.event.
Event name. Expected updated.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
Permission Scopes
For app development, you must have one of the following permission scopes:Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.events.v3.event.
Event name. Expected event_canceled.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
Triggered when an event is deleted.
Permission Scopes
For app development, you must have one of the following permission scopes:Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.events.v3.event.
Event name. Expected deleted.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.