@wix/agent-skills 1.16.0 → 1.16.2

package/skills/wix-manage/references/events/create-wix-event.md

@@ -1,20 +1,19 @@
 ---
 name: "Create an Event with the Wix Events API"
-description: "Creates an event with the Wix Events V3 API — the required request body, ISO-8601 date and time settings, venue/online/TBD location, RSVP vs ticketed registration, guest capacity, and short vs rich-text descriptions. Covers the exact field shapes and the API's misleading validation messages. Use when the user wants to create an event, set its date, location, description or guest limit, or choose between RSVP and ticketing."
+description: "Creates an event with the Wix Events V3 API — the required request body, ISO-8601 date and time settings, venue/online/TBD location, RSVP vs ticketed registration, guest capacity, short vs rich-text descriptions, ticket tiers and pricing, and recurring series. Covers the exact field shapes and the API's misleading validation messages. Use when the user wants to create an event, set its date, location, description, guest limit or ticket prices, or set up a repeating event."
 ---
 
 # Create an Event with the Wix Events API
 
 ## Goal
-Create an event on a Wix site — one-off or recurring, RSVP or ticketed — with the Wix Events
-V3 API. To publish, cancel, clone, count, add tickets or set up a recurring series, see
+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](manage-wix-events.md).
 
 ## First: pick the right "Events" API
 
 Several unrelated Wix APIs are called "Events". Routing to the wrong one is the most expensive
-mistake on this surface, because the wrong API answers plausibly for several calls before
-failing.
+mistake here, because the wrong API answers plausibly for several calls before failing.
 
 | The user means | API | Base path |
 | --- | --- | --- |
@@ -23,21 +22,16 @@ failing.
 | An entry on the marketing plan calendar | Marketing Calendar Event V1 | `/promote/marketing-plan-service/v1/events` |
 | An automation trigger | Triggered Events | `/automations/v1/events/report` |
 
-A recurring *class or course that guests book* is Bookings, not Wix Events. A recurring
-*event series guests attend* is Wix Events.
+A recurring *class or course that guests book* is Bookings. A recurring *event series guests
+attend* is Wix Events.
 
-## Prerequisite — the Wix Events app must be installed
+## Prerequisite — the Wix Events app
 
-Every `/events/v3` call against a site without the app returns:
-
-```
-428  {"message":"Events app not installed for metaSiteId=...",
-      "details":{"applicationError":{"code":"WIX_EVENTS_APP_NOT_INSTALLED"}}}
-```
-
-Install it with appDefId `140603ad-af8d-84a5-2c80-a0f60cb47351` — see
-[Install Wix Apps](../app-installation/install-wix-apps.md). Confirm with the user first unless
-they already asked for the event to be created.
+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](../app-installation/install-wix-apps.md).
 
 ## Create the event
 
@@ -55,122 +49,150 @@ curl -X POST 'https://www.wixapis.com/events/v3/events' \
         "timeZoneId": "America/New_York"
       },
       "registration": { "initialType": "RSVP" }
-    },
-    "draft": true
+    }
   }'
 ```
 
-`title`, `location`, `dateAndTimeSettings` and `registration.initialType` are all required.
-Drop `"draft": true` to create the event already published; a draft has `status: "DRAFT"` and
-is invisible on the site until published with `POST /events/v3/events/{eventId}/publish`
-(empty body), which moves it to `UPCOMING`.
+`title`, `location`, `dateAndTimeSettings` and `registration.initialType` are required. The event
+is created published (`status: "UPCOMING"`).
 
-## Date and time
+> **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.
 
-**`startDate` and `endDate` are ISO-8601 strings, not `{seconds, nanos}` objects.**
+## Date and time
 
-The spec types these fields as `string` / `format: date-time` but also carries a pointer to the
-`google.protobuf.Timestamp` message, whose fields are `seconds` and `nanos`. That message
-describes the *internal* representation and must not be sent — it fails with
-`400 {"message":"Expected a string."}`. This applies to every date-time field across the Wix
-APIs, not only Events.
+**`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.
 
 | Rule | If broken |
 | --- | --- |
-| `startDate` / `endDate` are ISO-8601 strings | `400 Expected a string.` |
+| ISO-8601 strings | `400 Expected a string.` |
 | `endDate` is required | `400 endDate.isDefined must be true, event cannot have negative duration` |
-| `timeZoneId` is required, in [TZ database](https://www.iana.org/time-zones) form (`America/New_York`) | `400 getTimeZoneId is not supported` |
+| `timeZoneId` is required, in [TZ database](https://www.iana.org/time-zones) form | `400 getTimeZoneId is not supported` |
 
-> The `timeZoneId` error reads as though the field is unsupported. It is not — it means the
-> field is **missing**. Add `timeZoneId`; do not remove it.
+> 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 with `400 getScheduleTbdMessage must not be a blank`.
+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`.
+`location.type` is `VENUE` or `ONLINE`. There is no `TBD` type — a to-be-announced location is a
+`VENUE` with `locationTbd: true`.
 
 | Body | Result |
 | --- | --- |
 | `{ "name": "Grand Hall", "type": "VENUE" }` | Accepted |
-| `{ "name": "Zoom", "type": "ONLINE" }` | Accepted |
 | `{ "name": "To be announced", "locationTbd": true }` | Accepted — `type` defaults to `VENUE` |
-| `{ "locationTbd": true }` | `400 Event location is invalid ... Location address must not be a blank` |
-| `{ "name": "TBA", "type": "TBD", "locationTbd": true }` | `400 type enum must be in [VENUE(0), ONLINE(1)]` |
-
-For a real street address, add an `address` object:
+| `{ "locationTbd": true }` | `400 Location address must not be a blank` |
+| `{ "name": "TBA", "type": "TBD" }` | `400 type enum must be in [VENUE(0), ONLINE(1)]` |
 
-```json
-"location": {
-  "name": "Javits Center", "type": "VENUE",
-  "address": {
-    "country": "US", "subdivision": "US-NY", "city": "New York", "postalCode": "10001",
-    "streetAddress": { "number": "429", "name": "11th Ave" }
-  }
-}
-```
-
-`subdivision` is the ISO-3166-2 code (`US-NY`), and the API fills in `formattedAddress` and
-`geocode` on the response. A `VENUE` with no `address` comes back with `locationTbd: true` set
-by the API whether or not you sent it.
+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 and fails with the same error. Accepted values are **`RSVP`**, **`TICKETING`**,
-`EXTERNAL` and `NONE`.
-
-> The API's error text for this field advertises `[RSVP,TICKETS,RSVP_AND_TICKETS]`. Those
-> values do not work — `TICKETS` is rejected. Use `TICKETING`.
+omitted. Accepted values are **`RSVP`**, **`TICKETING`**, `EXTERNAL` and `NONE`.
 
-`initialType` is immutable: an `RSVP` event can never become a `TICKETING` event or vice versa
-(either can later become `EXTERNAL` or `NONE` via `registration.type`). Choose correctly at
-creation time — "people should register by RSVP, not tickets" means `RSVP`.
+> The API's error text advertises `[RSVP,TICKETS,RSVP_AND_TICKETS]`. Those do not work —
+> `TICKETS` is rejected. Use `TICKETING`.
 
-**Guest limit.** For an RSVP event, the cap is `registration.rsvp.limit`:
+`initialType` is immutable: an `RSVP` event can never become `TICKETING` or vice versa. Choose
+correctly at creation — "register by RSVP, not tickets" means `RSVP`.
 
-```json
-"registration": { "initialType": "RSVP", "rsvp": { "limit": 30 } }
-```
-
-A `limit` placed directly on `registration` is **silently ignored** — the event is created with
-no cap and no error. Set `waitlistEnabled: true` alongside it to let guests join a waitlist once
-the limit is reached. For a ticketed event the cap is per ticket type, via `initialLimit` on the
-ticket definition — see [Manage Wix Events](manage-wix-events.md).
+**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
 
 | Field | Type | Use for |
 | --- | --- | --- |
-| `shortDescription` | plain string, max 500 | A one-line description under the event title |
+| `shortDescription` | plain string, max 500 | One line under the event title |
 | `description` | Ricos rich content object | The formatted body on the event page |
 
-A plain sentence belongs in `shortDescription`. Sending a string to `description` fails with
-`400 {"message":"Expected an object"}` — it takes a Ricos `{ "nodes": [...] }` tree, as built in
-[Rich Content](../rich-content/author-ricos-rich-content.md):
+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](../rich-content/author-ricos-rich-content.md). `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.
+
+```bash
+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
+    }
+  }'
+```
+
+| To create | `pricingMethod` |
+| --- | --- |
+| Fixed price | `{ "fixedPrice": { "value": "25.00", "currency": "USD" } }` |
+| Free | `{ "fixedPrice": { "value": "0", "currency": "USD" } }` |
+| Donation, with a minimum | `{ "guestPrice": { "value": "5.00", "currency": "USD" } }` |
+
+- **`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:
 
 ```json
-"description": { "nodes": [ { "type": "PARAGRAPH", "id": "p1", "paragraphData": {},
-  "nodes": [ { "type": "TEXT", "id": "", "nodes": [],
-               "textData": { "text": "Monthly meetup to discuss a new book.", "decorations": [] } } ] } ] }
+"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" }
+    ]
+  }
+}
 ```
 
-`shortDescription` is only returned when the request asks for `"fields": ["DETAILS"]`, and
-`description` only with `"fields": ["TEXTS"]`. Both are stored regardless.
+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.** Sending a value outside an enum returns
-  `<field> value is required` rather than "invalid value". If a field you *did* send is reported
-  as required, suspect the value, not its presence.
-- **Error text names internal accessors, not request fields.** `getTimeZoneId`,
-  `getScheduleTbdMessage` and `endDate.isDefined` each map to the plain field of the same name.
-- `title` is required, min 1 and max 120 characters. There is no separate name field.
+- **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](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3)
-- [Manage Wix Events](manage-wix-events.md) — tickets, publish, cancel, clone, recurring, count
-- [Install Wix Apps](../app-installation/install-wix-apps.md) — the `428` pre-flight
+- **Ticket Definitions V3**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3)
+- [Manage Wix Events](manage-wix-events.md) — publish, cancel, delete, clone, update, count

package/skills/wix-manage/references/events/manage-wix-events.md

@@ -1,19 +1,19 @@
 ---
-name: "Manage Wix Events — Tickets, Publishing, Cloning and Recurring Series"
-description: "Manages existing events with the Wix Events V3 API — ticket definitions and pricing (fixed price, free, donation, multiple tiers), publishing a draft, cancelling, deleting, cloning, updating an event's date or details, counting events, and creating a recurring series. Use when the user wants to add or price tickets, publish or cancel an event, duplicate an event, move an event's date, count their events, or set up a repeating event."
+name: "Manage Wix Events — Publishing, Cancelling, Cloning and Counting"
+description: "Operates on events that already exist with the Wix Events V3 API — publishing a draft, cancelling, deleting, cloning, updating an event's date or details, and counting events. Use when the user wants to publish or cancel an event, duplicate one, move an event's date, or count their events. Creating an event, its tickets or a recurring series is a separate recipe."
 ---
 
-# Manage Wix Events — Tickets, Publishing, Cloning and Recurring Series
+# Manage Wix Events — Publishing, Cancelling, Cloning and Counting
 
 ## Goal
-Operate on events that already exist: sell tickets, publish, cancel, delete, clone, update,
-count, and build recurring series. To create the event in the first place — including its date,
-location, description and guest limit — see [Create an Event](create-wix-event.md).
+Operate on events that already exist. Creating an event — including its date, location,
+description, guest limit, ticket tiers and recurring occurrences — is
+[Create an Event](create-wix-event.md).
 
-## Prerequisite — the Wix Events app must be installed
+## Prerequisite — the Wix Events app
 
 Every endpoint here returns `428 WIX_EVENTS_APP_NOT_INSTALLED` against a site without the app.
-Install it first — do not guess the install path, which is easy to get wrong:
+Install it first — do not guess the install path:
 
 ```bash
 curl -X POST 'https://www.wixapis.com/apps-installer-service/v1/app-instance/install' \
@@ -26,50 +26,7 @@ curl -X POST 'https://www.wixapis.com/apps-installer-service/v1/app-instance/ins
 ```
 
 `appDefId` nests under `appInstance`, not at the root — at the root it fails with
-`400 appInstance must not be empty`. See [Install Wix Apps](../app-installation/install-wix-apps.md)
-for the full flow.
-
-## Ticket definitions
-
-Ticket definitions belong to events created with `"initialType": "TICKETING"`. Tickets are a
-separate API; up to 100 definitions per event.
-
-```bash
-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
-    }
-  }'
-```
-
-| To create | `pricingMethod` |
-| --- | --- |
-| A fixed-price ticket | `{ "fixedPrice": { "value": "25.00", "currency": "USD" } }` |
-| A free ticket | `{ "fixedPrice": { "value": "0", "currency": "USD" } }` |
-| A donation / pay-what-you-want ticket, with a minimum | `{ "guestPrice": { "value": "5.00", "currency": "USD" } }` |
-
-Easy to get wrong:
-
-- **`feeType` is required** — `FEE_ADDED_AT_CHECKOUT` (fee on top of the price) or
-  `FEE_INCLUDED` (fee absorbed into it).
-- **`value` is a string.** `"value": 10` fails with `400 Unexpected value for field value`.
-- **There is no writable `free` flag.** `pricingMethod.free` is read-only, computed from the
-  price; sending `{"free": true}` fails with `value fixedPrice or guestPrice or pricingOptions
-  must not be empty`.
-- **The quantity field is `initialLimit`**, not `initialQuantity`. Omit it for unlimited tickets.
-- `limitPerCheckout` is read-only — it cannot be set on create.
-- `name` is capped at 30 characters, `description` at 500.
-
-**Multiple tiers** — call the endpoint once per tier with the same `eventId`. For "General
-Admission at $20 and VIP at $50", that is two calls, each with its own `name`, `fixedPrice` and
-`initialLimit`. There is no bulk-create for ticket definitions.
+`400 appInstance must not be empty`. See [Install Wix Apps](../app-installation/install-wix-apps.md).
 
 ## Publish, cancel and delete
 
@@ -82,14 +39,20 @@ Admission at $20 and VIP at $50", that is two calls, each with its own `name`, `
 Publish and cancel take an empty body. Publishing is irreversible — a published event cannot
 return to `DRAFT`. Cancelling closes registration but keeps the event; deleting removes it.
 
+> **Draft events need the `WIX_EVENTS.READ_DRAFT_EVENTS` permission.** Without it, publishing a
+> draft fails `403` — as does querying it, fetching it by slug, or adding ticket definitions to
+> it. If you hit that `403`, the event was still created; the way forward is to create events
+> already published rather than as drafts, which needs no publish step at all. See
+> [Create an Event](create-wix-event.md).
+
 ## Clone an event
 
 `POST /events/v3/events/{eventId}/clone` with an empty body copies the registration form,
 notifications, translations and ticket configuration.
 
-> **The clone does not keep the original's date.** Its start date is reset to roughly 14 days
-> from now, and it comes back as a `DRAFT`. If the user wanted a duplicate on a particular date,
-> follow the clone with an update, then publish it.
+> **The clone does not keep the original's date.** Its start date is reset to roughly 14 days from
+> now and it comes back as a `DRAFT`. For a duplicate on a particular date, follow the clone with
+> an update — and note the draft permission above.
 
 ## Update an event
 
@@ -110,9 +73,13 @@ curl -X PATCH 'https://www.wixapis.com/events/v3/events/<EVENT_ID>' \
   }'
 ```
 
-The Events API takes **no field mask and no `revision`** on update — send only the fields you
-are changing. Send `dateAndTimeSettings` complete when moving a date: `startDate`, `endDate` and
-`timeZoneId` together, since the same required-field rules apply as on create.
+The Events API takes **no field mask and no `revision`** on update — send only the fields you are
+changing. A `revision`, if you send one, is ignored rather than rejected.
+
+**When moving a date, send `startDate` and `endDate` together.** `dateAndTimeSettings` is replaced
+wholesale rather than merged, so a patch carrying only `startDate` leaves the event with no end and
+fails `400 event cannot have negative duration` — an error naming neither the missing field nor the
+replacement. `timeZoneId` is optional here, unlike on create; the stored one is kept.
 
 Ticket definitions are the exception — `PATCH /events/v3/ticket-definitions/{ticketDefinition.id}`
 *does* require the current `revision`, which increments on every update.
@@ -126,49 +93,21 @@ Ticket definitions are the exception — `PATCH /events/v3/ticket-definitions/{t
 ```
 
 Query Events returns only published events — **drafts are excluded from both the results and the
-total**. Create with `"draft": false`, or publish first, if the count is meant to include the
-event you just made.
+total**, and including them needs the draft permission above. Create published, or publish first,
+if the count is meant to include the event you just made.
 
 `POST /events/v3/events/count-by-status` exists, but an empty request body returns empty `facets`
 even when the site has events, so it is not the way to answer "how many events do I have".
 
-## Recurring events
-
-Wix Events has **no recurrence rule** — no `RRULE`, no "weekly" pattern. Calculate every
-occurrence date yourself and list them all (up to 1000), alongside the normal top-level
-`startDate` / `endDate` / `timeZoneId`:
-
-```json
-"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" }
-    ]
-  }
-}
-```
-
-For "a weekly event starting next week", generate the dates yourself — pick a sensible horizon
-(a few months) and say how many occurrences you created. The event returns
-`recurrenceStatus: "RECURRING"`. Each occurrence is an independent event with its own ID,
-updatable and deletable on its own; all share a generated `recurringEvents.categoryId`. Query by
-that `categoryId` to retrieve the whole series.
-
 ## Gotchas & troubleshooting
 
-- **An invalid enum value reports as a missing one.** A value outside an enum returns
-  `<field> value is required` rather than "invalid value" — true for `feeType` and
-  `registration.initialType`. If a field you *did* send is reported as required, suspect the
-  value, not its presence.
-- Dates are always ISO-8601 strings, never `{seconds, nanos}` — see
-  [Create an Event](create-wix-event.md).
+- **An invalid enum value reports as a missing one** — a value outside an enum returns
+  `<field> value is required` rather than "invalid value". If a field you *did* send is reported
+  as required, suspect the value, not its presence.
+- Dates are always ISO-8601 strings, never `{seconds, nanos}`, and `timeZoneId` is required
+  whenever `dateAndTimeSettings` is sent — see [Create an Event](create-wix-event.md).
 
 ## Related APIs
 - **Wix Events V3**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3)
-- **Ticket Definitions V3**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3)
 - **Event Guests**: `POST /events/v2/guests/query` — who registered
-- [Create an Event](create-wix-event.md) — the create body, dates, location, capacity
+- [Create an Event](create-wix-event.md) — create body, dates, location, capacity, tickets, recurring

package/skills/wix-manage/references/sites/create-headless-site.md

@@ -50,3 +50,4 @@ To provision headless onto an existing site, pass `"existingMetasite": {}` inste
 After creating the site:
 - Install additional apps using [Install Wix Apps](../app-installation/install-wix-apps.md)
 - Add content (products, services, blog posts, etc.)
+- Use the `appId` as the `client_id` to mint visitor tokens and make buyer-facing API calls — see [Manage OAuth Apps](manage-oauth-apps.md)

package/skills/wix-manage/references/sites/manage-oauth-apps.md

@@ -0,0 +1,154 @@
+---
+name: "Manage OAuth Apps"
+description: Create, read, update, and query OAuth apps for a Wix headless site. Each OAuth app's id is the client_id a frontend uses to mint anonymous visitor tokens and call Wix APIs.
+---
+# Manage OAuth Apps
+
+An OAuth app is a site-level credential holder. Its `id` is the `client_id` (the two terms are interchangeable — Wix uses `appId` in provisioning responses, `clientId` in token requests, and `id` in the OAuth Apps API; they all refer to the same value).
+
+When a headless site is provisioned it gets one OAuth app automatically (see [Create Headless Site](create-headless-site.md)); use this recipe to create additional apps, inspect existing ones, or update their redirect configuration.
+
+> **`client_id` is not a secret** — it is a public identifier safe to embed in frontend code. The visitor token it mints is also non-privileged: it represents an anonymous visitor, not an admin. The `client_secret` is different — shown once in the Headless Settings dashboard, never returned by the API, and rotation is dashboard-only.
+
+---
+
+## Create an OAuth App
+
+**Endpoint**: `POST https://www.wixapis.com/oauth-app/v1/oauth-apps`
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/oauth-app/v1/oauth-apps' \
+  -H 'Authorization: <AUTH>' \
+  -H 'wix-site-id: <metaSiteId>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "oAuthApp": {
+      "name": "My Storefront",
+      "loginUrl": "https://example.com/login",
+      "allowedRedirectUris": ["https://example.com/callback"],
+      "allowedRedirectDomains": ["example.com"]
+    }
+  }'
+```
+
+**Response**:
+```json
+{
+  "oAuthApp": {
+    "id": "<clientId>",
+    "name": "My Storefront",
+    "loginUrl": "https://example.com/login",
+    "allowedRedirectUris": ["https://example.com/callback"],
+    "allowedRedirectDomains": ["example.com"],
+    "createdDate": "2026-08-18T10:00:00Z"
+  }
+}
+```
+
+`id` is the OAuth `client_id`. After creating the app, retrieve the `client_secret` from the Headless Settings dashboard.
+
+---
+
+## Get an OAuth App
+
+**Endpoint**: `GET https://www.wixapis.com/oauth-app/v1/oauth-apps/{id}`
+
+```bash
+curl 'https://www.wixapis.com/oauth-app/v1/oauth-apps/<clientId>' \
+  -H 'Authorization: <AUTH>' \
+  -H 'wix-site-id: <metaSiteId>'
+```
+
+---
+
+## Query OAuth Apps
+
+**Endpoint**: `POST https://www.wixapis.com/oauth-app/v1/oauth-apps/query`
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/oauth-app/v1/oauth-apps/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'wix-site-id: <metaSiteId>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "query": {} }'
+```
+
+Returns all OAuth apps for the site.
+
+---
+
+## Update an OAuth App
+
+**Endpoint**: `PATCH https://www.wixapis.com/oauth-app/v1/oauth-apps/{id}`
+
+Update requires an explicit `mask.paths` — omitting it silently updates nothing.
+
+Updatable fields: `name`, `description`, `loginUrl`, `logoutUrl`, `allowedRedirectUris`, `allowedRedirectDomains`, `technology`.
+
+```bash
+curl -X PATCH \
+  'https://www.wixapis.com/oauth-app/v1/oauth-apps/<clientId>' \
+  -H 'Authorization: <AUTH>' \
+  -H 'wix-site-id: <metaSiteId>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "oAuthApp": {
+      "allowedRedirectUris": ["https://example.com/callback", "https://example.com/auth"]
+    },
+    "mask": { "paths": ["allowedRedirectUris"] }
+  }'
+```
+
+---
+
+## Key Fields
+
+| Field | Notes |
+|---|---|
+| `id` | The OAuth `client_id`. Read-only. |
+| `name` | Required on create. 2–256 chars. |
+| `loginUrl` | External login redirect. Defaults to Wix login if omitted. |
+| `logoutUrl` | Called when the user logs out at Wix. |
+| `allowedRedirectUris` | Exact-match URIs for post-authentication redirect. Max 20. |
+| `allowedRedirectDomains` | Domain-level allow-list for non-auth redirects (e.g. checkout). Max 20. |
+| `applicationType` | `WEB_APP`, `MOBILE`, `OTHER` |
+
+---
+
+## Minting a Visitor Token
+
+Once you have a `client_id`, frontends use it to mint an anonymous visitor token for buyer-facing API calls.
+
+**Endpoint**: `POST https://www.wixapis.com/oauth2/token`
+
+```bash
+# Initial anonymous mint
+curl -X POST 'https://www.wixapis.com/oauth2/token' \
+  -H 'Content-Type: application/json' \
+  -d '{ "clientId": "<clientId>", "grantType": "anonymous" }'
+
+# Response: { "access_token": "...", "refresh_token": "...", "expires_in": 14400 }
+```
+
+```bash
+# Refresh (use this instead of re-minting)
+curl -X POST 'https://www.wixapis.com/oauth2/token' \
+  -H 'Content-Type: application/json' \
+  -d '{ "clientId": "<clientId>", "grantType": "refresh_token", "refreshToken": "<refreshToken>" }'
+```
+
+Use the `access_token` as the `Authorization` header on subsequent API calls.
+
+> **Never re-mint anonymous on every load.** The visitor token is the cart/session identity — a fresh anonymous mint creates a new visitor and silently empties the cart. Persist the `refresh_token` and use it to renew.
+
+---
+
+## API Reference
+
+- [OAuth Apps — Create](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-o-auth-app)
+- [OAuth Apps — Get](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/get-o-auth-app)
+- [OAuth Apps — Query](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/query-o-auth-apps)
+- [OAuth Apps — Update](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-o-auth-app)
+- [Retrieve Tokens — `/oauth2/token` contract, all grant types](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens)