How To Code Events

⚠️ Reading rule — always append .md?apiView=SDK to every doc link below. The Wix docs render two views of the same page. The bare / REST view shows id; the ?apiView=SDK view shows _id — and the SDK is what your frontend calls. Reading the REST view by mistake is the most common source of the event.id-is-undefined bug. If a field name surprises you, you’re probably reading the REST view — re-open it with ?apiView=SDK. Discover any shape not pinned here with SearchWixSDKDocumentation, not by guessing a URL.

The modules and the client (read this first)

No app-id constant is needed in frontend code — the only id the client needs is the public clientId (non-Astro only; see below). Ticketed checkout hands off to Wix’s hosted checkout via the Redirects API, so there is no on-site cart and no catalogReference.

• The events query/get namespace is wixEventsV2 (despite the name, this is the current Events V3 module from @wix/events). Import wixEventsV2, orders, ticketReservations, rsvpV2 from @wix/events.
• ⚠️ CRITICAL: read ticket tiers with orders.queryAvailableTickets, NOT ticketDefinitions(V2).queryTicketDefinitions. The ticketDefinitions* namespaces are the management API (TicketDefinitionManagement, a manage scope) — the anonymous visitor is 403-denied on every one of them (queryTicketDefinitions, queryTicketDefinitionsV2, listTicketDefinitions), so a storefront that reads tiers that way gets an empty picker. Do NOT work around it with auth.elevate() — that’s the wrong axis (an app/admin permission elevation), it’s SSR-only (useless on a non-Astro SPA), and it’s unnecessary: the visitor-public storefront read is orders.queryAvailableTickets({ filter: { eventId }, limit }) → { definitions } (visitor-public — works for the anonymous visitor on Astro and SPA). The event read (queryEvents/getEventBySlug) is visitor-public too — no elevation anywhere in this recipe.
• Never use the deprecated orders.createReservation — reserve with ticketReservations.createTicketReservation.
• Never complete a paid purchase with orders.checkout (inline payment) — that path leaves orders unpaid without a payment integration. The supported headless completion is the hosted redirect (below).

Auth / client — framework split:

• Astro (Wix-managed): authentication is ambient. Call the modules directly — from server components for the SSR reads (listing/detail) and from browser islands for the visitor-session writes (reserve / redirect / rsvp) via the @wix/astro visitor client — no createClient, no OAuthStrategy, no clientId. Nothing here needs elevation (every read and write runs as the visitor — “no elevation anywhere”); a public-env clientId read in .astro SSR is undefined at server render → 500, so don’t build an OAuthStrategy client there.
• Non-Astro (Vite/React/Vue/static): build one manual visitor client and reuse it:

  jsCopy

  import { createClient, OAuthStrategy } from '@wix/sdk';
  import { wixEventsV2, orders, ticketReservations, rsvpV2 } from '@wix/events';
  import { redirects } from '@wix/redirects';
  
  const client = createClient({
    modules: { wixEventsV2, orders, ticketReservations, rsvpV2, redirects },
    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
  });

  The clientId is public, not a secret. A mis-wired public env var inlines as undefined and 400s every call.

The shapes you read (field cheat-sheet)

⚠️ CRITICAL: entity ids are _id, NOT id. event._id, tier._id. event.id is undefined in SDK code — a surprise id/undefined means you’re reading the REST doc view; re-open it with ?apiView=SDK.

Filtering by event format/track (talk/workshop/social) — if the site groups events by a format, the seed models it as Event Categories (setup-events.md STEP 4). Read the assigned category off the event and filter client-side — two gotchas:

• Request CATEGORIES as the 2nd positional arg, not inside the flat query: queryEvents({ filter, sort, paging }, { fields: ['CATEGORIES'] }) and getEventBySlug(slug, { fields: ['CATEGORIES'] }). (fields lives on the options arg, not on EventQuery.)
• categories is NOT on the typed Event (an SDK type gap — the CATEGORIES enum and EventCategory/EventCategories types ship, but Event omits the property, so a direct event.categories read fails tsc/astro check). Read it through a cast: const cats = (event as any).categories?.categories ?? [] — each entry is { _id, name }; map cats[].name → your format enum.
• Do NOT call the management categories endpoints (/events/v1/categories*, listEventsByCategory) from the frontend — they’re admin-scope; the visitor read is just the cast CATEGORIES field on the event.

The registration features (build the ones the site needs)

Each section is a self-contained feature — implement only what the site uses. Branch on the event’s registration.initialType: TICKETING → ticket picker (tiers + quantities → reserve → redirect); RSVP → the built-in name+email form → createRsvp. Never render an RSVP event with a ticket picker (or a ticketed event with an RSVP form).

Listing events (upcoming only, and the _id rule)

Doc: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/query-events.md?apiView=SDK (opens in a new tab)

• ⚠️ CRITICAL: queryEvents takes the query object FLAT as its first arg — queryEvents({ filter, sort, paging }), NOT queryEvents({ query: { … } }). The signature is queryEvents(query, options) where query is { filter, sort, paging }. Wrapping it in an extra { query: … } (the REST body shape, and the .queryServices({ query }) builder shape from other verticals) is not rejected — the SDK silently ignores the unrecognized query key, so paging never applies, limit defaults to 0, and you get events: [] with no error. This is the #1 “my listing is empty even though events are published” trap. (The flat form returns the events; the nested form returns zero.)
• ⚠️ paging.limit MUST be > 0. Even with the flat shape, queryEvents defaults paging.limit to 0, which returns zero events. Always set a positive limit.
• The result array is result.events (not .items).
• Filter to upcoming/published and never list or link a past event — a past event isn’t purchasable/registerable (the seed uses future dates). Filter by status (above) or by a future startDate.
• Read event._id / event.slug / event.title. A single-event site collapses the listing — lead the home page straight into the one event’s detail. Still drive that homepage from the listing query (take the first/only result), never a hardcoded lone slug — so a second event the owner adds later automatically brings the listing back instead of staying invisible.

One event by slug + its ticket tiers

Docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/get-event-by-slug.md?apiView=SDK (opens in a new tab) · https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/query-available-tickets.md?apiView=SDK (opens in a new tab)

• Request REGISTRATION in fields so event.registration.initialType is populated — that’s the value you branch on.
• Per tier read tier._id, tier.name, tier.price.value (a string) + tier.price.currency, tier.free, and tier.saleStatus (gate the picker on SALE_STARTED).
• ⚠️ The confirmation page (post-checkout) reads the event by ID, and the return envelope DIFFERS from getEventBySlug. After the hosted checkout redirects back to your postFlowUrl (carrying ?eventId=…), look the event up with wixEventsV2.getEvent(eventId, { fields: ['TEXTS', 'URLS'] }) — this returns the Event object DIRECTLY (unwrapped): read event.title / event.slug, not { event }. This is the one read that isn’t wrapped (getEventBySlug is { event }); assume the wrapper and the page crashes. Use this exact call — don’t inspect the installed .d.ts to rediscover it.

Ticketed checkout — reserve → redirect (the exact sequence)

Two steps, both as the visitor. Use as-is — the payload shapes are easy to get subtly wrong.

Docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/ticket-reservations/create-ticket-reservation.md?apiView=SDK (opens in a new tab) · https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md?apiView=SDK (opens in a new tab)

• ⚠️ CRITICAL: don’t hand-build the checkout URL. {base}/event-details/{slug}/ticket-form?reservationId=… 404s on a headless site (there’s no Wix-hosted event page). The Redirects API mints a checkout URL on Wix’s own domain — eventsCheckout: { reservationId, eventSlug } → redirectSession.fullUrl is the only path that works headless.
• ⚠️ CRITICAL: the redirect call must run in the VISITOR (headless-OAuth) context — never elevated/admin. createRedirectSession embeds the headless app’s clientId; an admin/elevated token fails with “client Id does not correspond to a headless oauth app.” On Astro the browser island calls it (ambient visitor client), never a server endpoint; on non-Astro it’s the OAuthStrategy client. Don’t elevate it.
• ⚠️ CRITICAL: origin MUST be the published https:// host — from window.location.origin, never a server-derived new URL(request.url).origin. The Headless redirect allowlist registers the https:// host and treats http://<same host> as a different, unlisted origin; an http:// postFlowUrl makes the return (“Continue Browsing”) 403 with “… isn’t listed as an allowed redirect domain.” Pass window.location.origin from the client. Doc: https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains (opens in a new tab).
• ⚠️ Handle the paid-ticket precondition softly. Reserving a paid ticket as a visitor fails with 403 "No payment method configured" until the site has a premium plan and a configured payment method (a dashboard step the seed already flagged). This is the real gate — not a permissions bug, and not something elevation should paper over (elevating just creates an unpayable INITIATED order). Catch the error; if its message matches /payment method|not configured|premium/i, show “Ticket sales aren’t switched on yet — the organizer needs to connect a payment method.” Free / RSVP events are unaffected.
• Wrap both calls in try/catch (sold out, sale ended, no payment method) and surface a friendly message; don’t crash the page.

Free RSVP — the built-in form

Doc: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/create-rsvp.md?apiView=SDK (opens in a new tab)

• ⚠️ CRITICAL: use the rsvpV2 module, NOT rsvp. The legacy rsvp.createRsvp posts to /events/v1/rsvp and 400s with "rsvp.firstName/lastName/email must not be empty" even when you pass those fields — that v1 surface expects a different form-response body. Import rsvpV2 from @wix/events and call rsvpV2.createRsvp(rsvp) with the rsvp object directly as the first arg (not wrapped in { rsvp: … }, which is the elevated/@wix/essentials style). The flat { eventId, firstName, lastName, email, status } object is correct for rsvpV2 and works for the anonymous visitor.
• The RSVP registration form is built-in (firstName, lastName, email) — add exactly those fields; don’t fetch a form schema or hand-build extra fields.
• Wrap in try/catch — a duplicate email or closed registration rejects; surface a friendly message.

Rendering & mounting

• Date: event.dateAndTimeSettings.formatted.dateAndTime (already human-formatted) — request the DETAILS field to populate it.
• Image: event.mainImage is a Wix media ref — render it via the media helper (@wix/sdk media.getScaledToFillImageUrl / getImageUrl); never hand-build a static.wixstatic.com URL (→ 403).
• Price: tier.price.value (string) + tier.price.currency (the event’s stored currency — format from it, don’t assume USD).
• Mount the ticket picker / RSVP form in a client:only="react" island (Astro) — they run visitor-session SDK calls and redirect. SSR only the read pages (listing/detail) for SEO.

SEO on item pages (Astro, Wix-managed)

An event detail page is a Wix item page: its <title>/description/OG/canonical come from what the owner sets in the dashboard. On the Astro (Wix-managed) frontend, wire it per the canonical guide — Add SEO Support to Item Pages (opens in a new tab) — which covers the three steps: export wixMetadata (registers the route → sitemap + dashboard SEO editor), call loadSEOTagsServiceConfig(...), and render <SEO.Tags> (from @wix/seo; deps + @wix/essentials ≥ 1.0.10 are in the guide’s “Before you begin”).

For an event page use:

• wixMetadata from WIX_APPS.events.eventPageMetadata — referenced directly in the export (module scope). Route param slug → identifiers.slug.
• itemType: seoTags.ItemType.EVENTS_PAGE.

Fold loadSEOTagsServiceConfig into the same Promise.all as the ambient getEventBySlug read, with .catch(() => null) (it needs only the slug — still a visitor-safe ambient call), so a SEO hiccup falls back to the layout’s default title. Optional: render an Event schema.org JSON-LD <script> from the fetched event (see the guide’s structured-data step).

Out of scope

Assigned seating / seat maps (display + reserve flat ticket definitions only); coupons & gift cards at checkout (Wix’s hosted checkout handles those — don’t build a discount UI); on-site order management / cancel / refund (handled by the hosted flow + the buyer’s email); manual orders.checkout inline payment (use the hosted redirect).

Conclusion

A correct Events V3 registration frontend:

• imports wixEventsV2 / orders / ticketReservations / rsvpV2 from @wix/events plus redirects from @wix/redirects — and never inline orders.checkout or the legacy rsvp (v1 → 400) module;
• uses event._id / tier._id (never .id) and reads the flat fields (event.slug, registration.initialType, tier.price.value);
• lists with queryEvents({ filter, sort, paging }) FLAT (never { query: { … } } — that silently returns events: []) and paging.limit > 0, filtered to upcoming/published events, never past ones;
• reads ticket tiers with the visitor-public orders.queryAvailableTickets({ filter: { eventId }, limit }) (→ definitions) — never the management ticketDefinitions* query (visitor 403s) and never auth.elevate() (wrong axis, SSR-only); no elevation anywhere;
• branches on registration.initialType: TICKETING → reserve (createTicketReservation → reservation._id) → createRedirectSession({ eventsCheckout }) → redirectSession.fullUrl; RSVP → rsvpV2.createRsvp with the built-in firstName/lastName/email and an inline confirmation;
• runs the reserve/redirect/rsvp client-side as the visitor (no server route, no elevation), uses window.location.origin (the https:// host) for the callbacks, and fails soft on the 403 "No payment method configured" paid-ticket precondition.