/wix-manage

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

curl -X POST 'https://www.wixapis.com/events/v3/events' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <AUTH>' \
  --data-binary '{
    "event": {
      "title": "Summer Gala",
      "location": { "name": "Grand Hall", "type": "VENUE" },
      "dateAndTimeSettings": {
        "startDate": "2026-09-15T19:00:00.000Z",
        "endDate": "2026-09-15T22:00:00.000Z",
        "timeZoneId": "America/New_York"
      },
      "registration": { "initialType": "RSVP" }
    }
  }'

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

What comes back — the created event under event; the id you need for every follow-up call is event.id:

{
  "event": {
    "id": "<EVENT_ID>",
    "title": "Summer Gala",
    "slug": "summer-gala",
    "status": "UPCOMING",
    "location": { "name": "Grand Hall", "type": "VENUE", "locationTbd": false },
    "dateAndTimeSettings": {
      "startDate": "2026-09-15T19:00:00Z", "endDate": "2026-09-15T22:00:00Z",
      "timeZoneId": "America/New_York", "recurrenceStatus": "ONE_TIME"
    },
    "createdDate": "...", "updatedDate": "..."
  }
}

Update, cancel, publish and clone return the same { "event": { ... } }; delete returns { "eventId": "..." }. Some fields are returned only when the request's fields array asks for them: "DETAILS" adds shortDescription, "TEXTS" adds description, "REGISTRATION" adds registration (including rsvp.limit), "URLS" adds eventPageUrl. Without fields, read the result from the top-level fields above and do not treat a missing registration as an error.

Do not add "draft": true unless the user asked for a draft. Draft events require the WIX_EVENTS.READ_DRAFT_EVENTS permission, and without it every follow-up call fails 403 — adding ticket definitions, querying the event, fetching it by slug, even publishing it. The event is created, but nothing can be done with it. Create it published and skip the publish step entirely.

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.

The timeZoneId error reads as though the field is unsupported. It is not — it means the field is missing. Add it; do not remove it.

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.

The API's error text advertises [RSVP,TICKETS,RSVP_AND_TICKETS]. Those do not work — TICKETS is rejected. Use TICKETING.

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.

curl -X POST 'https://www.wixapis.com/events/v3/ticket-definitions' \
  -H 'Content-Type: application/json' -H 'Authorization: <AUTH>' \
  --data-binary '{
    "ticketDefinition": {
      "eventId": "<EVENT_ID>",
      "name": "General Admission",
      "pricingMethod": { "fixedPrice": { "value": "25.00", "currency": "USD" } },
      "feeType": "FEE_ADDED_AT_CHECKOUT",
      "initialLimit": 100
    }
  }'

The response is the definition under ticketDefinition:

{
  "ticketDefinition": {
    "id": "<TICKET_DEFINITION_ID>",
    "eventId": "<EVENT_ID>",
    "revision": "1",
    "name": "General Admission",
    "limited": true, "initialLimit": 100, "actualLimit": 100,
    "pricingMethod": { "fixedPrice": { "value": "25.00", "currency": "USD" } },
    "feeType": "FEE_ADDED_AT_CHECKOUT",
    "saleStatus": "SALE_STARTED"
  }
}

Keep revision — PATCH /events/v3/ticket-definitions/{id} requires the current value, and it increments on every update.

• feeType is required. A free ticket (fixedPrice of "0") takes NO_FEE. A paid ticket takes FEE_ADDED_AT_CHECKOUT (the guest pays the service fee) unless the user asked to absorb it, then FEE_INCLUDED. NO_FEE on a paid ticket is accepted only on sites that do not collect ticket fees. If a paid ticket fails with 400 INVALID_FEE_TYPE, the site is one that does not collect ticket fees: retry that ticket once with NO_FEE.
• 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:

"dateAndTimeSettings": {
  "startDate": "2026-10-20T18:00:00.000Z",
  "endDate": "2026-10-20T19:00:00.000Z",
  "timeZoneId": "America/New_York",
  "recurringEvents": {
    "individualEventDates": [
      { "startDate": "2026-10-20T18:00:00.000Z", "endDate": "2026-10-20T19:00:00.000Z", "timeZoneId": "America/New_York" },
      { "startDate": "2026-10-27T18:00:00.000Z", "endDate": "2026-10-27T19:00:00.000Z", "timeZoneId": "America/New_York" }
    ]
  }
}

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