@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-manage/references/analytics/query-site-analytics.md

@@ -0,0 +1,298 @@
+---
+name: "Query Site Analytics"
+description: Retrieve a Wix site's analytics through the Semantic Model API. Covers listing semantic models, inspecting a model's schema (measures, dimensions, parameters), and querying model data with a required time interval, filters, sorting, paging, and human-readable formatting.
+---
+# Query Site Analytics
+
+This article shows how to read a site's analytics with the **Semantic Model API**. A semantic model describes one analytics subject area (such as site traffic, revenue, etc.) and defines the **measures**, **dimensions**, and **parameters** you can query.
+
+## Prerequisites
+
+1. The app/caller has the **Site Analytics – read** permission scope (`SCOPE.DC-ANALYTICS-AND-REPORTS.READ-SITE-ANALYTICS`).
+2. A site context is available (the request is authorized against a specific site).
+
+## Required APIs
+
+- **Semantic Model API**: [REST](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/introduction)
+- **Site Properties API** (for the site's time zone): [REST](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties)
+
+Base path: `https://www.wixapis.com/analytics/semantic-model/v3`
+
+| Step | Method | Endpoint |
+|---|---|---|
+| List models | `GET` | `/semantic-models` |
+| Get model schema | `GET` | `/semantic-models/{semanticModelId}` |
+| Query model data | `POST` | `/semantic-models/query-data` |
+
+## Decision flow
+
+Always follow **List → Get → Query**. You cannot construct a valid query without first discovering the model's field names from `Get Semantic Model`.
+
+1. **List Semantic Models** — discover which subject areas exist and their IDs.
+2. **Get Semantic Model** — inspect a model's `measures`, `dimensions`, and `parameters` to find the exact `name` values to query and their supported filters/sorting.
+3. **Query Semantic Model Data** — request specific field names for a time `interval`, with optional filters, sorting, paging, and formatting.
+
+**Run each step as its own separate API call, and stop to read the result before starting the next step.** The inputs to each step do not exist until the previous step returns:
+
+- You cannot set `semanticModelId` until **List** returns it. **Never fabricate or guess a model ID** — it must be a GUID copied verbatim from a `List Semantic Models` result. A plausible-looking GUID that List did not return will fail (`SEMANTIC_MODEL_NOT_FOUND`).
+- You cannot set `fields`, `filters[].field`, or `sort.fieldName` until you have read the schema from **Get**.
+
+Choosing the model and the field names is a **reasoning** step you perform by reading the returned JSON — not something to automate with string matching. Do **not** chain List, Get, and Query into a single script/execution.
+
+❌ **Don't do this** — one execution that lists, gets, and queries in a single pass, picking fields by pattern-matching their names:
+
+```js
+const models = await wix.request(/* list */);
+const model  = models.find(m => /traffic/.test(m.slug));       // guessing the model
+const schema = await wix.request(/* get model.id */);
+const dim    = schema.dimensions.find(d => /url|path/i.test(d.name)); // guessing the field
+await wix.request(/* query with guessed fields */);
+```
+
+This guesses field names, ignores each field's `dependencies` (so those fields come back silently empty), and never lets you actually verify the model or schema.
+
+✅ **Do this** — three separate calls, reading each result before composing the next:
+
+1. Call **List**. Read the returned models; pick the `id` whose subject area matches the request.
+2. Call **Get** with that `id`. Read `measures`/`dimensions`/`parameters`; choose the exact `name`s you need and note each field's `dependencies`.
+3. Call **Query** with the field names you chose.
+
+## Before you begin (sharp edges)
+
+- **`interval` is required on every query.** There is no way to query without a date range — omitting it fails.
+- **`start`/`end` are absolute UTC instants — not wall-clock in `interval.timezone`.** The trailing `Z` is respected as a real point in time; `interval.timezone` does not reinterpret it, it aligns the range to local day boundaries (and materially changes the result — the same UTC window returned different totals under `UTC` vs `Asia/Jerusalem` vs `America/Los_Angeles` in testing). So to capture a **local calendar range**, send the UTC instants that equal **local midnight** in the site's time zone — *not* `...T00:00:00.000Z`. Example — all of January 2026 for a `America/New_York` site (EST, UTC−5): `start: "2026-01-01T05:00:00.000Z"`, `end: "2026-02-01T05:00:00.000Z"`. Using `...T00:00:00.000Z` would actually start the range at 7 pm on Dec 31 local and misalign every day boundary.
+- **`interval` is start-inclusive, end-exclusive (`[start, end)`).** `start` is included, `end` is not — set `end` to the local-midnight instant of the day *after* the last day you want (e.g. for all of January, `end` is Feb 1 local midnight, in UTC).
+- **Convert local midnight → UTC per date, and watch DST.** Compute each boundary as local-midnight-in-UTC using the site's offset **for that specific date** — the offset changes with daylight saving. `America/New_York` is UTC−4 in summer (June local midnight = `04:00:00.000Z`) but UTC−5 in winter (January local midnight = `05:00:00.000Z`), so a range spanning a DST switch has *different* offsets at its two ends. Don't hardcode one offset across a range.
+- **Set `interval.timezone` to the site's time zone to match the Wix dashboard.** Analytics in the Wix business manager are bucketed by the site's time zone. If `interval.timezone` is omitted it defaults to **UTC**, so day boundaries shift and your numbers won't match what the owner sees in the dashboard (and the same goes for using a different time zone). Get the site's IANA time zone from `properties.timeZone` via [Get Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties) (`GET https://www.wixapis.com/site-properties/v4/properties`) and pass it through.
+- **Field names must come from `Get Semantic Model`.** The `fields`, `filters[].field`, and `sort.fieldName` values must exactly match a `name` returned by the model schema (e.g. `traffic.sessions_count`). Do not guess field names.
+- **The field-name prefix is NOT the model slug.** Do not build names as `<slug>.<field>`. A model's fields often use a different prefix — e.g. the model with slug `crm-people-subscribers` exposes its measure as `people.contacts_count`, not `people_subscribers.contacts_count`. Copy the exact `name` strings from `Get Semantic Model`; inferring the prefix from the slug produces a field the model doesn't have.
+- **Read the COMPLETE schema — never sample or truncate it.** When inspecting a model in Step 2, read the full `measures` and `dimensions` lists; do not cap them with `.slice(0, N)` or otherwise return only the first few. Lists are often long and alphabetical, so a cutoff silently hides exactly the field you need (e.g. on `traffic`, a `.slice(0, 25)` drops `traffic.referrer_category_name`, `traffic.referrer_source_name`, and `traffic.visitor_type`). Choosing from a partial list re-introduces guessing — the agent assumes a missing field doesn't exist or fabricates a name. The same applies to a field's full `dependencies` array and to the model list from `List Semantic Models`.
+- **A wrong field name can fail loudly OR fail silently — assume neither.** A `fields`/`filters[].field`/`sort.fieldName` value that isn't a valid model field either (a) rejects the query with a `4XX` error and a self-explanatory string code (e.g. `fieldIsInvalid`), sometimes listing the model's **available field names**, or (b) is **silently dropped** — the query returns `200` and that field just doesn't appear in `results[].fields` (same as a missing dependency). In testing, an unknown field in `fields` was silently omitted, not errored. Never rely on an error to catch a bad field. (See *Handling wrong fields* below.)
+- **Field dependencies.** A field returns data only if at least one of the field names in its `dependencies` array is also included in the same query; otherwise it's **silently omitted** from results (no error). For example, a measure may only return data when a specific dimension is also requested.
+- **Sorting a nullable measure — set `sort.nullsLast: true`.** `nullsLast` defaults to `false` and only affects **descending** (`DESC`) order. If a measure can return null and you sort it `DESC`, the null rows sort *first* — so a "top N" query surfaces nulls before your real values. Set `nullsLast: true` to push nulls to the end.
+- **Result cap: 1,000 rows per query.** `results` is capped at 1,000 rows — paginate with `paging.offset` for larger datasets.
+- **Formatting is opt-in.** Set `formattingEnabled: true` to also receive a human-readable `formattedValue` per cell (e.g. `1500` → `"$1,500.00"` or `1.5K`). Raw typed values are always returned.
+- **Totals are opt-in.** Set `totalsIncluded: true` to get a `totals` row summing numeric fields across the **full (unpaginated)** result set.
+- **Unique fields are not additive.** For `unique` measures (e.g. unique visitors), query the exact time range you want in a **single request** — never sum values from separate date-range queries. Uniques are deduplicated within each queried range, so adding per-range results double-counts anyone who appears in more than one range and overstates the true total.
+
+## Step 1: List semantic models
+
+```bash
+curl -X GET \
+  'https://www.wixapis.com/analytics/semantic-model/v3/semantic-models' \
+  -H 'Authorization: <AUTH>'
+```
+
+Response:
+
+```json
+{
+  "semanticModels": [
+    { "id": "cad7fd34-2c8b-4dda-8296-3f9d47fb484d", "slug": "traffic", "description": "Site traffic", "keywords": ["sessions", "views"] }
+  ]
+}
+```
+
+Pick the model whose subject area matches the request, and keep its `id`.
+
+## Step 2: Get the model schema
+
+```bash
+curl -X GET \
+  'https://www.wixapis.com/analytics/semantic-model/v3/semantic-models/cad7fd34-2c8b-4dda-8296-3f9d47fb484d' \
+  -H 'Authorization: <AUTH>'
+```
+
+Response shape:
+
+```json
+{
+  "semanticModel": {
+    "id": "string<GUID>",
+    "slug": "string",
+    "description": "string",
+    "keywords": ["string"],
+    "measures": [ "Field" ],
+    "dimensions": [ "Field" ],
+    "parameters": [ "Field" ]
+  }
+}
+```
+
+Each `Field` (in `measures`, `dimensions`, and `parameters`):
+
+| Property | Meaning |
+|---|---|
+| `name` | The exact value to use in `fields`, `filters[].field`, and `sort.fieldName`. |
+| `type` | `STRING`, `NUMBER`, `BOOLEAN`, `DATE`, `DATE_TIME`, `OBJECT`, or `ARRAY`. |
+| `filters` | Supported filter `prefixes` (`IS`/`NOT`) and `conditions` (e.g. `EQUAL`, `RANGE_II`, `CONTAINS_ANY`). |
+| `sortable` | Whether the field can be used in `sort`. |
+| `enumerations` | Allowed values, for enumerated fields. |
+| `dependencies` | Other field names this field needs present in the query to return data (see sharp edges). |
+| `groupSlug` | Fields sharing a `groupSlug` are logically related. |
+| `description` | Human-readable description of the field. |
+
+- **Measures** are quantitative fields you aggregate (revenue, page views, order count).
+- **Dimensions** are categorical fields you group by (traffic source, country, product name).
+- **Parameters** are optional inputs that customize query behavior (currency, date granularity).
+
+## Step 3: Query the model data
+
+`POST /semantic-models/query-data` (body requires `Content-Type: application/json`).
+
+Required body fields: `semanticModelId`, `interval`, `fields`.
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/analytics/semantic-model/v3/semantic-models/query-data' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "semanticModelId": "cad7fd34-2c8b-4dda-8296-3f9d47fb484d",
+  "interval": {
+    "start": "2024-06-01T04:00:00.000Z",
+    "end": "2025-06-01T04:00:00.000Z",
+    "timezone": "America/New_York"
+  },
+  "fields": [
+    "traffic.referrer_category_name",
+    "traffic.sessions_count",
+    "traffic.views_count"
+  ],
+  "filters": [
+    {
+      "field": "traffic.sessions_count",
+      "condition": "GREATER_THAN",
+      "values": ["100"]
+    }
+  ],
+  "sort": {
+    "fieldName": "traffic.sessions_count",
+    "order": "DESC",
+    "nullsLast": true
+  },
+  "paging": {
+    "limit": 50,
+    "offset": 0
+  },
+  "formattingEnabled": true,
+  "totalsIncluded": true
+}'
+```
+
+> The `interval` above uses `04:00:00.000Z`, not `00:00:00.000Z`: June is EDT (UTC−4) in `America/New_York`, so `04:00Z` is local midnight. `start`/`end` are absolute UTC instants — set them to local-midnight-in-UTC for the site's time zone, and recompute the offset per date (DST). See the interval sharp edges above.
+
+### Request fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `semanticModelId` | Yes | GUID from List/Get. |
+| `interval` | Yes | `{ start, end }` absolute UTC ISO instants (trailing `Z`), plus `timezone`. `start`/`end` are real points in time, not wall-clock in `timezone` — to capture a local calendar range set them to local-midnight-in-UTC for the site's time zone (offset varies with DST). Range is start-inclusive, end-exclusive (`[start, end)`) — set `end` to the local midnight after the last day you want. Set `timezone` to the site's IANA time zone (see Time zone section) so results align to the Wix dashboard; defaults to UTC when omitted. |
+| `fields` | Yes | Up to 60 field `name`s from the model schema. |
+| `filters` | No | Array of `{ field, values[], condition, prefix }`. `condition` defaults to `EQUAL`, `prefix` defaults to `IS`. For `RANGE_*` conditions provide exactly 2 values. |
+| `sort` | No | `{ fieldName, order, nullsLast }`. `order` defaults to `ASC`; field must be `sortable`. `nullsLast` (default `false`) applies only to `DESC` order — set it to `true` when the sorted measure can contain nulls, otherwise nulls sort before real values. |
+| `paging` | No | `{ limit, offset }`. Defaults: `limit` 50, `offset` 0. |
+| `formattingEnabled` | No | Default `false`. Adds `formattedValue` per cell. |
+| `totalsIncluded` | No | Default `false`. Adds a `totals` row. |
+
+### Response shape
+
+```json
+{
+  "results": [
+    {
+      "fields": {
+        "traffic.referrer_category_name": { "stringValue": "Search", "formattedValue": "Search" },
+        "traffic.sessions_count": { "numericValue": 1500, "formattedValue": "1.5K" }
+      }
+    }
+  ],
+  "pagingMetadata": { "count": 5, "offset": 0 },
+  "totals": { "fields": { "traffic.sessions_count": { "numericValue": 9000 } } }
+}
+```
+
+Each cell in `results[].fields` is a typed value — one of `numericValue`, `stringValue`, `booleanValue`, `timestampValue`, `arrayValue`, or `objectValue` — plus `formattedValue` when `formattingEnabled` is `true`. `totals` is present only when `totalsIncluded` is `true`.
+
+## Time zone (match the Wix dashboard)
+
+Analytics shown in the Wix business manager are aggregated by the **site's time zone**. To return numbers that match what the site owner sees, pass that time zone in `interval.timezone` on every query. **When `timezone` is omitted, the API defaults to UTC** — which shifts day boundaries and produces totals that don't line up with the dashboard (the same applies to any non-site time zone).
+
+Two independent things both matter, and both use the time zone:
+
+1. **`interval.timezone`** aligns aggregation to the site's local day boundaries. It is not cosmetic — the same `start`/`end` return different totals under different time zones.
+2. **`start`/`end` themselves are absolute UTC instants.** To line them up with local calendar days you must send local-midnight-in-UTC — i.e. add the site's UTC offset **for that date** (DST-aware). For `America/New_York`: local midnight is `05:00:00.000Z` in winter (UTC−5) and `04:00:00.000Z` in summer (UTC−4). Sending `...T00:00:00.000Z` with a non-UTC `timezone` starts the range partway through the previous local day and skews the result.
+
+Get the site's time zone from **Get Site Properties**:
+
+```bash
+curl -X GET \
+  'https://www.wixapis.com/site-properties/v4/properties?fields.paths=timeZone' \
+  -H 'Authorization: <AUTH>'
+```
+
+The IANA time zone string is returned in `properties.timeZone`:
+
+```json
+{
+  "properties": {
+    "timeZone": "America/New_York"
+  }
+}
+```
+
+Use that value as `interval.timezone` in `Query Semantic Model Data`. The Site Properties `timeZone` reflects the site's primary business address and requires the `SITE_SETTINGS.VIEW` permission.
+
+## Pagination
+
+To retrieve more than 1,000 rows, page through with `offset`:
+
+1. Request page 1 with `paging: { limit: 1000, offset: 0 }`.
+2. Increment `offset` by the page size until `pagingMetadata.count` is less than the requested `limit`.
+
+## Handling wrong fields
+
+A field can be "wrong" in three ways — guard against each:
+
+1. **Rejected (`4XX`).** The query fails with a self-explanatory string code (e.g. `fieldIsInvalid`) and, when provided, the model's valid field names. Recovery: read them, pick the correct `name`, and re-query — do **not** retry the rejected name or invent a new one. If no field list is returned, fall back to `Get Semantic Model` (Step 2) and re-read the schema.
+
+2. **Silently omitted (`200`).** The query succeeds but a requested field is **absent from every `results[].fields` entry** (and from `totals`). This happens for unknown field names *and* for fields whose `dependencies` weren't included — **no error is raised.** So **after every query, verify that each name in `fields` actually appears in the results.** If one is missing: re-check its exact `name` via `Get Semantic Model`, add any required `dependencies`, and re-query. Treat a silently-missing field as a failure, not as empty data.
+
+3. **Valid but semantically wrong.** The name exists, so you get `200` and real-looking numbers — but it answers the wrong question (e.g. using `traffic.page_url` instead of `traffic.page_url_from` for per-page traffic, or a field whose `description` says *"Do not use it ever"*). This is the most dangerous case because nothing looks broken. Prevent it in **Step 2**: choose fields by reading each field's `description`, honor "do not use" notes, and never pick by name pattern alone. (This is why List → Get → Query are separate steps — see *Decision flow*.)
+
+Cases 1 and 2 are caught **after** the query by validating the response; case 3 is prevented **before** the query by reading field descriptions when you choose fields.
+
+## Answer from the site's own models — don't ask or call external sources
+
+Analytics questions are answered from the site's **semantic models**, discovered via `List Semantic Models`. This includes data that originates from a third party — e.g. **Google Search / Search Console** metrics (impressions, clicks, CTR, average position, top queries and pages) — which Wix ingests and often enriches with its own site data. So: **do not ask the user whether a source is connected, and do not call the external provider (e.g. Google) directly** — find the matching model and query it. If a query returns no data for the requested period, report that there's no data (the source may not be connected) rather than asking the user to connect first.
+
+## Common Errors
+
+| HTTP | Code | Meaning |
+|---|---|---|
+| 4XX | `fieldIsInvalid` | A `fields`/`filters[].field`/`sort.fieldName` value doesn't exist in the model, and this query rejected it (some invalid fields are instead silently dropped from a `200` — see *Handling wrong fields*). When present, the error lists the model's **available field names** — pick the correct one and re-query. |
+| 401 | `NO_ACCOUNT_IDENTITY` / `UNAUTHENTICATED` | Caller isn't authenticated; provide valid credentials. |
+| 404 | `SEMANTIC_MODEL_NOT_FOUND` | The `semanticModelId` doesn't exist for this site. |
+
+Error codes are self-explanatory strings (e.g. `fieldIsInvalid`) — read the code and the fields it returns rather than parsing a fixed body shape. Note: not every invalid field errors; some are silently omitted from a `200` response, so also validate the response (see *Handling wrong fields*).
+
+Silent gap (no error): a requested field returns no data because none of its `dependencies` were included in the query — add a dependency field and re-query.
+
+## Best Practices
+
+1. Always run **List → Get → Query** as three separate calls; read each result before composing the next, and never hardcode or pattern-match field names — read them from `Get Semantic Model`.
+2. Pass the site's time zone (`properties.timeZone` from Get Site Properties) in `interval.timezone` **and** set `start`/`end` to local-midnight-in-UTC for that zone (DST-aware) so results match the Wix dashboard. `start`/`end` are absolute instants, not wall-clock.
+3. Include a field's `dependencies` in the query, or expect that field to be silently dropped.
+4. After each query, validate the response — confirm every requested field appears in `results[].fields`. A wrong field either errors (`4XX`, e.g. `fieldIsInvalid`) or is silently dropped from a `200`; a missing field means an unknown name or a missing dependency. Fix and re-query rather than trusting the partial result. Choose fields by reading their `description` (honoring "do not use" notes), never by name pattern.
+5. Use `formattingEnabled: true` for anything shown directly to a user; keep raw values for calculations.
+6. Use `totalsIncluded: true` to get period totals alongside a paged breakdown in a single call.
+7. Keep `fields` minimal (projection) and paginate large result sets with `offset`.
+
+## Related Documentation
+
+- [Semantic Model API: Introduction](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/introduction)
+- [Semantic Model API: Sample Flows](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/sample-flows)
+- [List Semantic Models](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/list-semantic-models)
+- [Get Semantic Model](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/get-semantic-model)
+- [Query Semantic Model Data](https://dev.wix.com/docs/api-reference/business-management/analytics/semantic-models/query-semantic-model-data)
+- [Get Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties) (source of the site's `timeZone`)

package/skills/wix-manage/references/app-installation/install-wix-apps.md

@@ -99,6 +99,7 @@ Some common apps:
 | Wix Bookings | `13d21c63-b5ec-5912-8397-c3a5ddb27a97` |
 | Wix Blog | `14bcded7-0066-7c35-14d7-466cb3f09103` |
 | Wix Events | `140603ad-af8d-84a5-2c80-a0f60cb47351` |
+| Wix Multilingual | `14d84998-ae09-1abf-c6fc-3f3cace5bf19` |
 | Wix Pricing Plans | `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3` |
 | Wix CMS | `e593b0bd-b783-45b8-97c2-873d42aacaf4` |
 
@@ -114,6 +115,8 @@ Some common apps:
 ### App Not Installed Error
 If you receive an error indicating a required app is not installed, use this recipe to install it before proceeding.
 
+If Locale Settings or Locales APIs return `428 MULTILINGUAL_NOT_INSTALLED`, install **Wix Multilingual** using appDefId `14d84998-ae09-1abf-c6fc-3f3cace5bf19`, then retry enabling multilingual mode or creating locales. Confirm with the user before installing unless they already explicitly asked you to install Wix Multilingual.
+
 ---
 
 ## Next Steps

package/skills/wix-manage/references/bookings/create-and-update-booking-services.md

@@ -33,7 +33,7 @@ A Bookings service defines a time based offering and includes the following cons
 - When creating an APPOINTMENT service and specifying `staffMemberIds`, ensure you are using the staff member's resourceId, not their primary staff member id.
 - Service Images - the service may have several images - `service.media.mainMedia` - presented in the services list, `service.media.coverMedia` - presented in the service page and `service.media.items` - array of images presented as a gallery in the service page for site visitors.
 - In order to add a media (image) to a service, it should first be defined in Wix Media Manager - search existing ([REST](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/search-files)) or new ([REST](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/bulk-import-file))
-- You should only set the image id (for example `item.id` -> `service.media.mainMedia.id`) there is no need to set the entire object.
+- Set only the image **id**, but nest it inside the media item's `image` object: `service.media.mainMedia.image.id` (likewise `service.media.coverMedia.image.id` and `service.media.items[].image.id`). The `id` is the binding field; `url` and dimensions are descriptive and need not be set. ⚠️ Setting the id directly on the media item (`service.media.mainMedia.id`, without the `image` wrapper) returns HTTP 200 but **silently drops** it — the image reads back empty (`image.id: ""`). Because it's a silent 200, a success status is not proof: always nest under `.image` and confirm with a re-query.
 
 ### Service Type Selection Guide
 

package/skills/wix-manage/references/bookings/create-booking-service-from-prompt.md

@@ -1,13 +1,13 @@
 ---
 name: "Create Booking Service from Prompt"
-description: "Create a booking service from a user prompt — e.g. 'create a yoga class for $50', 'set up consultations for $75', 'add a personal training appointment', 'create a 6-week photography workshop'. Determines the service type (APPOINTMENT, CLASS, or COURSE) and delegates to the type-specific recipe."
+description: "Create a booking service from a user prompt — e.g. 'create a yoga class for $50', 'set up consultations for $75', 'add a personal training appointment', 'create a 6-week photography workshop', 'create a hidden free test course with 8 online sessions'. Determines the service type (APPOINTMENT, CLASS, or COURSE) and delegates to the type-specific recipe. For COURSE services with session dates/counts, follow the course recipe's separate Calendar bulkCreateEvents step; Services V2 alone does not create bookable course sessions."
 ---
 
 # Create Booking Service from Natural Language Prompt
 
 ## When to Use
 
-- User describes a service they want to create using natural language (e.g., "create a yoga class for $50", "set up consultation sessions", "add a personal training appointment")
+- User describes a service they want to create using natural language (e.g., "create a yoga class for $50", "set up consultation sessions", "add a personal training appointment", "create a hidden free test course with 8 online sessions")
 - The intent is autonomous creation — fill in reasonable defaults rather than asking the user for every field
 
 ## Step 1: Determine Service Type
@@ -16,7 +16,7 @@ description: "Create a booking service from a user prompt — e.g. 'create a yog
 |---|---|---|
 | consultation, appointment, meeting, 1-on-1, one-on-one, session | `APPOINTMENT` | [Create Appointment Service](./create-appointment-service.md) |
 | class, yoga, pilates, group session, group workout, bootcamp class | `CLASS` | [Create Class Service](./create-class-service.md) |
-| workshop, program, course, training program, multi-session | `COURSE` | [Create Course Service](./create-course-service.md) |
+| workshop, program, course, training program, multi-session, fixed series, 8 sessions | `COURSE` | [Create Course Service](./create-course-service.md) |
 | (unclear or unspecified) | `APPOINTMENT` | [Create Appointment Service](./create-appointment-service.md) |
 
 ## Step 2: Follow the Type-Specific Recipe
@@ -26,5 +26,6 @@ Once the service type is determined, follow the corresponding recipe linked abov
 1. Gathering business context (staff where required, categories, duplicate check)
 2. Applying type-specific defaults (pricing, capacity, duration, staff assignment)
 3. Creating the service via `bulkCreateServices`
-4. Navigating to the service form for user review
-5. Providing a summary of what was created and assumptions made
+4. For COURSE services with session dates/counts, creating separate Calendar events via `bulkCreateEvents` on the returned `service.schedule.id`
+5. Navigating to the service form for user review
+6. Providing a summary of what was created and assumptions made

package/skills/wix-manage/references/bookings/create-course-service.md

@@ -1,6 +1,6 @@
 ---
 name: "Create Course Service"
-description: "Create a course booking service — e.g. 'create a 6-week photography workshop', 'set up a training program', 'add a bootcamp course for $300', 'create a teacher training course'. Handles group capacity, full-course pricing, and fixed series defaults via bulkCreateServices API. Staff assignment is not used for courses."
+description: "Create a course booking service — e.g. 'create a 6-week photography workshop', 'set up a training program', 'add a bootcamp course for $300', 'create a hidden free test course with 8 sessions'. Handles group capacity, full-course pricing, bulkCreateServices, and separate course session events via bulkCreateEvents. Staff assignment is not used for courses."
 ---
 
 # Create Course Service from Prompt
@@ -8,6 +8,7 @@ description: "Create a course booking service — e.g. 'create a 6-week photogra
 ## When to Use
 
 - User wants to create a multi-session course: "create a training program", "set up a 6-week workshop", "add a bootcamp course", "create a teacher training course"
+- User wants a free or hidden test COURSE with specific session dates/counts, such as "create a hidden free test course with 8 online sessions"
 - The service type is COURSE — a fixed series with pre-defined start and end dates
 - Customers must book the entire course (all sessions), unlike CLASS where they can pick individual sessions
 - For general service creation where the type is ambiguous, see [Create Booking Service from Prompt](./create-booking-service-from-prompt.md)
@@ -91,6 +92,8 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/categories' \
 
 **CRITICAL: COURSE services do NOT use `staffMemberIds` or `sessionDurations`.** These fields are ignored. Use `defaultCapacity` instead.
 
+Do not put session dates under `course.sessions`, `CourseSession`, or any similar nested field in the Services V2 create/update payload. Services V2 creates the course service and returns a `service.schedule.id`; it does not create bookable course sessions from nested `course` data. A course with no Calendar events can be created successfully but appear as ended or unavailable on the service page.
+
 **Paid course:**
 
 ```bash
@@ -148,23 +151,44 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 
 - Do **NOT** include `staffMemberIds` — it is ignored for COURSE services
 - Do **NOT** include `schedule.availabilityConstraints.sessionDurations` — not used for COURSE
+- Do **NOT** include `course.sessions` or inferred `CourseSession` objects in the service payload — accepted or ignored nested course data does not make sessions bookable
 - `defaultCapacity` is **required** — sets max participants for the entire course
 - Customers must book the **entire course** (all sessions), not individual sessions
 - After creation, course sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
+- If the user asked you to create the course and gave the session count/times, the job is not complete after `bulkCreateServices`; continue by creating the Calendar events, then verify the service has future events before telling the user it is ready
 
 Save the `serviceId` from the response: `results[0].item.service.id`
+Save the `service.schedule.id` from the response for the follow-up `bulkCreateEvents` request.
+
+---
+
+## Step 4: Create Course Session Events
+
+If the user specified session dates, times, or a session count, create the course events immediately after the service exists:
+
+1. Read `results[0].item.schedule.id` from the service create response.
+2. Query or create the resource/staff member that should appear on the course events and use its `resourceId`.
+3. Call `bulkCreateEvents` (`POST https://www.wixapis.com/calendar/v3/bulk/events/create`) with one event per course session.
+4. For each event, set:
+   - `event.scheduleId` to the course service's `service.schedule.id`
+   - `event.type` to `COURSE`
+   - `event.resources` to at least one resource object using a valid `resourceId`
+   - start/end fields for the session time
+5. Query the service/calendar events afterward to confirm future events exist before saying the course is bookable.
+
+If the session details are missing, create only the service and clearly tell the user that the course still needs session events before it can be booked.
 
 ---
 
-## Step 4: Summary Message
+## Step 5: Summary Message
 
 Provide a summary including:
 
 1. **What was created** — service name, total course price, capacity
 2. **Assumptions made** — list defaults used (e.g., "I set the capacity to 10 participants since you didn't specify")
 3. **Pricing clarification** — note that the price is for the entire course, not per session
-4. **Schedule note** — remind the user that course sessions (dates and times) still need to be set up
-5. **Next steps** — "Click Save to finalize, then set up the course schedule"
+4. **Schedule status** — say whether course session events were created and verified; do not say the course is bookable if only the service exists
+5. **Next steps** — if events were not created, tell the user to provide session dates/times or set up the course schedule
 6. **Offer to adjust** — "Want me to change the price, capacity, or description?"
 
 **Example:**
@@ -178,7 +202,7 @@ Provide a summary including:
 >
 > I assumed a capacity of 10 since you didn't specify. The price of $300 covers the entire course — customers pay once for all sessions. You can review and adjust the details in the service form.
 >
-> **Next step:** You'll need to set up the course schedule (specific session dates and times) in the service form.
+> **Next step:** You'll need to set up the course schedule (specific session dates and times) before customers can book it.
 
 ---
 
@@ -187,6 +211,7 @@ Provide a summary including:
 | Error | Cause | Action |
 |---|---|---|
 | 400 "INVALID_PAYMENT_OPTIONS" | Payment misconfigured | Free: `inPerson: true`, `online: false`. Paid: price > 0 |
+| Course page says "Ended", "Beendet", or "This service is not available" after service creation | Service exists but no future course events were created on `service.schedule.id` | Create course events via Calendar Events `bulkCreateEvents`, then verify future events exist |
 | 403 | Permission denied | Inform user they lack permission |
 
 ---