Introduction

With the Wix Events v2 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 Wix Events v2 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 initially 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.

  • 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.

When 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 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 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 do not need to register for the event, you can set the registration.registrationDisabled property to true. After doing this, the registration.type value becomes NONE.

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.
Was this helpful?
Yes
No

Setup

To use the WixEventsV2 API, install the @wix/events package using npm or Yarn:

Copy
1
npm install @wix/events

or

Copy
1
yarn add @wix/events

Then import { wixEventsV2 } from @wix/events:

Copy
1
import { wixEventsV2 } from '@wix/events'
Was this helpful?
Yes
No
bulkCancelEventsByFilter( )

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:
Manage Events - all permissions
Manage Events
Learn more about permission scopes.
Copy
function bulkCancelEventsByFilter(options: BulkCancelEventsByFilterOptions): Promise<void>
Method Parameters
optionsBulkCancelEventsByFilterOptions
Optional fields.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
countEventsByStatus( )

Counts events by status.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Events - all read permissions
Manage Bookings Services and Settings
Manage Events - all permissions
Read Events
Manage Guest List
Manage Events
Learn more about permission scopes.
Copy
function countEventsByStatus(options: CountEventsByStatusOptions): Promise<CountEventsByStatusResponse>
Method Parameters
optionsCountEventsByStatusOptions
Optional fields.
Returns
Return Type:Promise<CountEventsByStatusResponse>
Was this helpful?
Yes
No
createEvent( )

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:
Manage Events - all permissions
Manage Events
Learn more about permission scopes.
Copy
function createEvent(event: V3Event, options: CreateEventOptions): Promise<V3Event>
Method Parameters
eventV3EventRequired
Event data.
optionsCreateEventOptions
Optional fields.
Returns
Return Type:Promise<V3Event>
Was this helpful?
Yes
No
findEvent( )

Finds an event by ID or URL slug.

Unlike the getEvent function, which returns a "not found" error, findEvent() returns an empty response when an event is not found.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Events - all read permissions
Manage Bookings Services and Settings
Manage Events - all permissions
Read Events
Manage Guest List
Manage Events
Learn more about permission scopes.
Copy
function findEvent(options: FindEventOptions): Promise<FindEventResponse>
Method Parameters
optionsFindEventOptions
Optional fields.
Returns
Return Type:Promise<FindEventResponse>
Was this helpful?
Yes
No
getEvent( )

Retrieves an event by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Events - all read permissions
Manage Bookings Services and Settings
Manage Events - all permissions
Read Events
Manage Guest List
Manage Events
Learn more about permission scopes.
Copy
function getEvent(eventId: string, options: GetEventOptions): Promise<V3Event>
Method Parameters
eventIdstringRequired
Event ID.
optionsGetEventOptions
Optional fields.
Returns
Return Type:Promise<V3Event>
Was this helpful?
Yes
No
getEventBySlug( )

Retrieves an event by the slug URL.

The slug is the end of an event URL that refers to a specific event. For example, if an events' URL is https://example.com/events/event/{my-event-slug}, the slug is my-event-slug.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Events - all read permissions
Manage Bookings Services and Settings
Manage Events - all permissions
Read Events
Manage Guest List
Manage Events
Learn more about permission scopes.
Copy
function getEventBySlug(slug: string, options: GetEventBySlugOptions): Promise<GetEventBySlugResponse>
Method Parameters
slugstringRequired
URL slug.
optionsGetEventBySlugOptions
Optional fields.
Returns
Return Type:Promise<GetEventBySlugResponse>
Was this helpful?
Yes
No
queryEvents( )

Creates a query to retrieve a list of events.

The queryEvents() function builds a query to retrieve a list of events and returns a EventsQueryBuilder object.

The returned object contains the query definition, which is typically used to run the query using the find() function.

You can refine the query by chaining EventsQueryBuilder functions onto the query. EventsQueryBuilder functions enable you to sort, filter, and control the results queryEvents() returns.

queryEvents() runs with these EventsQueryBuilder defaults, which you can override:

The functions that are chained to queryEvents() are applied in the order they're called. For example, if you apply ascending('title') and then descending('status'), the results are sorted first by the title, and then, if there are multiple results with the same title, the items are sorted by status.

PROPERTYSUPPORTED FILTERS & SORTING
_ideq(),ne(),in(),ascending(),descending()
dateAndTimeSettings.startDateeq(),ne(),lt(),le(),gt(),ge(),in(),ascending(),descending()
dateAndTimeSettings.endDateeq(),ne(),lt(),le(),gt(),ge(),in(),ascending(),descending()
titleeq(),ne(),in(),ascending(),descending()
slugeq(),ne(),in(),ascending(),descending()
_createdDateeq(),ne(),lt(),le(),gt(),ge(),in(),ascending(),descending()
_updatedDateeq(),ne(),lt(),le(),gt(),ge(),in(),ascending(),descending()
statuseq(),ne(),in()
registration.initialTypeeq()
userIdeq(),ne(),in()

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Events - all read permissions
Manage Bookings Services and Settings
Manage Events - all permissions
Read Events
Manage Guest List
Manage Events
Learn more about permission scopes.
Copy
function queryEvents(options: QueryEventsOptions): EventsQueryBuilder
Method Parameters
optionsQueryEventsOptions
Optional fields.
Returns
Return Type:EventsQueryBuilder
Was this helpful?
Yes
No