Create an Event with the Wix Events API

Goal

Create an event on a Wix site — one-off or recurring, RSVP or ticketed, with ticket tiers. To publish, cancel, clone, update or count events that already exist, see Manage Wix Events.

First: pick the right "Events" API

Several unrelated Wix APIs are called "Events". Routing to the wrong one is the most expensive mistake here, because the wrong API answers plausibly for several calls before failing.

A recurring class or course that guests book is Bookings. A recurring event series guests attend is Wix Events.

Prerequisite — the Wix Events app

Every /events/v3 call against a site without it returns 428 WIX_EVENTS_APP_NOT_INSTALLED. Install with appDefId 140603ad-af8d-84a5-2c80-a0f60cb47351 via POST /apps-installer-service/v1/app-instance/install, body {"tenant":{"tenantType":"SITE","id":"<SITE_ID>"},"appInstance":{"appDefId":"<APP_DEF_ID>"}} — appDefId nests under appInstance. See Install Wix Apps.

Create the event

title, location, dateAndTimeSettings and registration.initialType are required. The event is created published (status: "UPCOMING").

Date and time

startDate and endDate are ISO-8601 strings, not {seconds, nanos} objects. The spec types them as string / format: date-time but also points at google.protobuf.Timestamp, whose fields are seconds and nanos. That is the internal form and must not be sent. This applies to every date-time field across the Wix APIs.

Midnight is 00:00 of the next day. 2026-08-18T24:00:00.000Z is not a valid ISO time.

Date to be announced: send dateAndTimeSettings as { "dateAndTimeTbd": true, "dateAndTimeTbdMessage": "Date coming soon" } and nothing else. The message is mandatory — omitting it fails 400 getScheduleTbdMessage must not be a blank.

Location

location.type is VENUE or ONLINE. There is no TBD type — a to-be-announced location is a VENUE with locationTbd: true.

For a street address add address: { "country": "US", "subdivision": "US-NY", "city": "New York", "postalCode": "10001", "streetAddress": { "number": "429", "name": "11th Ave" } } — subdivision is the ISO-3166-2 code; the API fills in formattedAddress and geocode.

Registration type and capacity

initialType must be nested under registration; at the root of event it is treated as omitted. Accepted values are RSVP, TICKETING, EXTERNAL and NONE.

initialType is immutable: an RSVP event can never become TICKETING or vice versa. Choose correctly at creation — "register by RSVP, not tickets" means RSVP.

Guest limit (RSVP events). The cap is registration.rsvp.limit: "registration": { "initialType": "RSVP", "rsvp": { "limit": 30 } }. A limit placed directly on registration is silently ignored — no cap, no error. Add waitlistEnabled: true for a waitlist. Ticketed events cap per tier instead, via initialLimit below.

Description — two different fields

A plain sentence belongs in shortDescription. A string sent to description fails 400 Expected an object — it takes a Ricos { "nodes": [...] } tree, as built in Rich Content. shortDescription is returned only with "fields": ["DETAILS"], description only with ["TEXTS"]; both are stored regardless.

Ticket tiers

For events created with "initialType": "TICKETING". One call per tier — there is no bulk-create, and up to 100 tiers per event.

• feeType is required — FEE_ADDED_AT_CHECKOUT or FEE_INCLUDED.
• value is a string. "value": 10 fails 400 Unexpected value for field value.
• No writable free flag — pricingMethod.free is read-only; a free ticket is a fixedPrice of "0".
• Quantity is initialLimit, not initialQuantity; omit for unlimited. limitPerCheckout is read-only. name max 30 chars.

Recurring events

Wix Events has no recurrence rule — no RRULE, no "weekly" pattern. Calculate every occurrence yourself and list them all (up to 1000). Each occurrence needs its own timeZoneId; omitting it fails with a cryptic ZoneOffset error:

Pick a sensible horizon for "weekly" and say how many occurrences you created. The event returns recurrenceStatus: "RECURRING". Each occurrence is an independent event with its own ID; all share a generated recurringEvents.categoryId, which is how you query the series.

Gotchas & troubleshooting

• An invalid enum value reports as a missing one — <field> value is required rather than "invalid value". If a field you did send is reported as required, suspect the value.
• Error text names internal accessors: getTimeZoneId, getScheduleTbdMessage, endDate.isDefined each map to the plain field of the same name.

Related APIs

• Wix Events V3: REST
• Ticket Definitions V3: REST
• Manage Wix Events — publish, cancel, delete, clone, update, count