@wix/agent-skills 1.15.1 → 1.16.0

package/skills/wix-manage/references/restaurants/wix-restaurants-setup.md

@@ -1,6 +1,6 @@
 ---
 name: "Wix Restaurants Setup"
-description: Configures restaurant menus, sections, and items using Menus API. Covers menu structure (Menu → Section → Item), modifiers, pricing, availability schedules, and ordering settings.
+description: Configures restaurant menus, sections, and items using Menus API. Covers menu structure (Menu → Section → Item), the two-step item modifier / modifier group flow, pricing, availability schedules, and ordering settings.
 ---
 # Wix Restaurants Setup API Reference
 
@@ -16,6 +16,7 @@ This recipe covers setting up and configuring Wix Restaurants using the REST API
 - **Menus API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/create-menu)
 - **Menu Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/create-item)
 - **Menu Sections API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/create-section)
+- **Item Modifiers API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifiers/create-modifier)
 - **Item Modifier Groups API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifier-groups/create-modifier-group)
 - **Item Variants API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-variants/bulk-create-variants)
 
@@ -70,32 +71,8 @@ Wix Restaurants uses a hierarchical structure:
 }
 ```
 
-Create multiple sections:
-```json
-// Section 1: Appetizers
-{
-  "section": {
-    "name": "Appetizers",
-    "sortOrder": 1
-  }
-}
-
-// Section 2: Main Courses
-{
-  "section": {
-    "name": "Main Courses",
-    "sortOrder": 2
-  }
-}
-
-// Section 3: Desserts
-{
-  "section": {
-    "name": "Desserts",
-    "sortOrder": 3
-  }
-}
-```
+Repeat per section, incrementing `sortOrder`, or create them all at once with the bulk endpoint
+in Step 7.
 
 ## Step 3: Create Menu Items
 
@@ -115,6 +92,9 @@ Create multiple sections:
 }
 ```
 
+`modifierGroups` holds objects referencing existing modifier groups —
+`[{ "id": "<MODIFIER_GROUP_ID>" }]`. Leave it empty until the groups exist (Step 5).
+
 ## Step 4: Add Items to Sections
 
 **Endpoint**: `PATCH https://www.wixapis.com/restaurants/menus-section/v1/sections/{sectionId}`
@@ -133,86 +113,103 @@ Each section update requires the latest section `revision`.
 
 ## Step 5: Configure Item Options and Modifiers
 
-Create modifiers for customization (e.g., cooking temperature, add-ons):
+A modifier group (e.g. "Cooking Temperature", "Toppings") holds a set of individual choices and
+the selection rule that governs them. **The choices are separate entities** — a modifier group
+does not contain inline options. Creating a group therefore takes two calls, in this order:
 
-**Endpoint**: `POST https://www.wixapis.com/restaurants/item-modifier-group/v1/modifier-groups`
+1. Create one **item modifier** per choice (Item Modifiers API) and keep each returned `id`.
+2. Create the **modifier group** (Item Modifier Groups API), referencing those IDs.
+
+Do both calls; a group created without step 1 comes back with an empty `modifiers` array and no
+choices are saved.
+
+### Step 5a: Create each item modifier
+
+**Endpoint**: `POST https://www.wixapis.com/restaurants/item-modifiers/v1/modifiers`
+
+Only `modifier.name` is required.
 
 ```json
 {
   "modifier": {
-    "name": "Cooking Temperature",
-    "required": true,
-    "minSelections": 1,
-    "maxSelections": 1,
-    "options": [
-      {
-        "name": "Rare",
-        "price": {
-          "amount": "0",
-          "currency": "USD"
-        }
-      },
-      {
-        "name": "Medium Rare",
-        "price": {
-          "amount": "0",
-          "currency": "USD"
-        }
-      },
-      {
-        "name": "Medium",
-        "price": {
-          "amount": "0",
-          "currency": "USD"
-        }
-      },
-      {
-        "name": "Well Done",
-        "price": {
-          "amount": "0",
-          "currency": "USD"
-        }
-      }
-    ]
+    "name": "Extra Cheese",
+    "type": "MODIFIER"
   }
 }
 ```
 
-Add-on modifier with pricing:
+The response returns the new `modifier.id`. Repeat per choice, collecting the IDs.
+
+### Step 5b: Create the modifier group
+
+**Endpoint**: `POST https://www.wixapis.com/restaurants/item-modifier-group/v1/modifier-groups`
+
+The request body's top-level field is **`modifierGroup`**. Sending `modifier` instead is rejected
+with `400 modifierGroup must not be empty` (`violatedRule: REQUIRED_FIELD`).
+
+Required: `modifierGroup` and `modifierGroup.name`.
+
 ```json
 {
-  "modifier": {
-    "name": "Add-ons",
-    "required": false,
-    "minSelections": 0,
-    "maxSelections": 5,
-    "options": [
+  "modifierGroup": {
+    "name": "Toppings",
+    "modifiers": [
       {
-        "name": "Extra Cheese",
-        "price": {
-          "amount": "2.00",
-          "currency": "USD"
-        }
+        "id": "<ITEM_MODIFIER_ID_1>",
+        "additionalChargeInfo": { "additionalCharge": "2.00" }
       },
       {
-        "name": "Bacon",
-        "price": {
-          "amount": "3.00",
-          "currency": "USD"
-        }
-      },
-      {
-        "name": "Avocado",
-        "price": {
-          "amount": "2.50",
-          "currency": "USD"
-        }
+        "id": "<ITEM_MODIFIER_ID_2>",
+        "additionalChargeInfo": { "additionalCharge": "0.00" }
       }
-    ]
+    ],
+    "rule": {
+      "required": false,
+      "minSelections": 0,
+      "maxSelections": 5
+    }
+  }
+}
+```
+
+For a mandatory single-choice group (e.g. cooking temperature) use the same shape with
+`"rule": { "required": true, "minSelections": 1, "maxSelections": 1 }`.
+
+**Field reference** for `modifierGroup`:
+
+| Field | Notes |
+|-------|-------|
+| `name` | Required. The group's display name. |
+| `modifiers[].id` | ID of an existing item modifier from Step 5a — not a name. Up to 500. |
+| `modifiers[].additionalChargeInfo.additionalCharge` | That choice's surcharge, a decimal string (`"2.00"`). No `currency` field — the site currency is used. |
+| `modifiers[].preSelected` | Optional boolean; selects the choice by default. |
+| `rule.required` | Whether the customer must choose. Named `required`, not `mandatory`. |
+| `rule.minSelections` / `rule.maxSelections` | Integers bounding how many choices are allowed. |
+
+There is no `options` field and no per-option `price` object.
+
+### Step 5c: Attach the group to an item
+
+A modifier group only reaches customers once an item references it. The item's `modifierGroups`
+is an array of **objects carrying an `id`**, not bare ID strings.
+
+**Endpoint**: `PATCH https://www.wixapis.com/restaurants/menus-item/v1/items/{itemId}`
+
+```json
+{
+  "item": {
+    "id": "<ITEM_ID>",
+    "revision": "<ITEM_REVISION>",
+    "modifierGroups": [{ "id": "<MODIFIER_GROUP_ID>" }]
   }
 }
 ```
 
+To create modifier groups in bulk, use
+`POST https://www.wixapis.com/restaurants/menus/v1/bulk/modifier-groups/create` and
+`POST https://www.wixapis.com/restaurants/menus/v1/bulk/modifiers/create`; the per-entity body
+shape is the same.
+
 ## Step 6: Set Menu Structure (Attach Sections to Menu)
 
 Attach section IDs to a menu. This call requires the latest menu `revision`.
@@ -265,39 +262,18 @@ Use query APIs for retrieval and UI display flows.
 }
 ```
 
-## Query Menus
-
-**Endpoint**: `GET https://www.wixapis.com/restaurants/menus-menu/v1/menus`
-
-**Response**:
-```json
-{
-  "menus": [
-    {
-      "id": "menu-1",
-      "name": "Breakfast Menu",
-      "visible": true,
-      "sections": [...]
-    },
-    {
-      "id": "menu-2",
-      "name": "Lunch Menu",
-      "visible": true,
-      "sections": [...]
-    }
-  ]
-}
-```
-
 ## Recommended Setup Order
 
 For complex restaurant menus, use this order to avoid dependency issues:
 
 1. Create variants (sizes/options) if needed.
-2. Create items (single or bulk).
-3. Create sections (single or bulk).
-4. Update each section with `itemIds`.
-5. Update menu with `sectionIds`.
+2. Create item modifiers, then group them into modifier groups (Step 5) if the items need
+   customization options.
+3. Create items (single or bulk).
+4. Create sections (single or bulk).
+5. Update each section with `itemIds`.
+6. Update menu with `sectionIds`.
+7. Update items with `modifierGroups` to attach the groups from step 2.
 
 ## Item Labels
 
@@ -311,15 +287,6 @@ Common dietary labels:
 - `spicy`
 - `chef-recommendation`
 
-## Best Practices
-
-1. **High-Quality Images**: Use appetizing food photography
-2. **Clear Descriptions**: Include ingredients and preparation methods
-3. **Accurate Pricing**: Keep prices up-to-date
-4. **Stock Management**: Update availability in real-time
-5. **Modifier Organization**: Group related customizations logically
-6. **Menu Structure**: Organize sections in logical dining order
-
 ## Error Handling
 
 | Error | Cause | Solution |
@@ -327,6 +294,8 @@ Common dietary labels:
 | `MENU_NOT_FOUND` | Invalid menu ID | Verify menu exists |
 | `ITEM_NOT_FOUND` | Invalid item ID | Verify item exists |
 | `INVALID_PRICE` | Negative price | Use positive amounts |
+| `400 modifierGroup must not be empty` | Request body wrapped the group in `modifier` instead of `modifierGroup` | Use `modifierGroup` as the top-level field (Step 5b) |
+| Group created but `modifiers` is `[]` | Choices were sent inline (e.g. an `options` array) instead of as item modifier IDs | Create item modifiers first, then reference their IDs in `modifiers[].id` (Step 5a → 5b) |
 
 ## Related Documentation
 

package/skills/wix-manage/references/site-properties/change-payment-currency-site-properties.md

@@ -1,21 +1,23 @@
 ---
-name: "RECIPE: Change a Site's Payment (Store) Currency via Site Properties API"
-description: "Updates the site-level payment currency (store billing currency) using Site Properties API, including the required request body shape and field mask."
+name: "RECIPE: Change a Site's Regional Properties (Currency, Time Zone, Language) via Site Properties API"
+description: "Updates the site-level payment currency (store billing currency) using Site Properties API, including the required request body shape and field mask. Covers the site time zone and primary language through the same call, whose field mask names top-level properties."
 ---
 
-# RECIPE: Change a Site's Payment (Store) Currency via Site Properties API
+# RECIPE: Change a Site's Regional Properties via Site Properties API
 
 ## Goal
-Update a Wix site's **payment currency** (the ISO-4217 currency code used to bill customers) programmatically.
+Update a Wix site's **regional properties** — payment currency, time zone, or primary language — programmatically.
 
 ## When to use
 - You need to switch a site's store/payment currency (for example, from `USD` to `EUR`).
+- You need to change a site's time zone or primary language.
 - You want to automate regional/business setup for sites.
 
 ## Important notes before you start
-- The `paymentCurrency` field is part of **Site Properties** (often shown in the dashboard under regional/business info).
+- These fields are part of **Site Properties** (often shown in the dashboard under regional/business info).
 - A successful update increments the Site Properties `version`.
 - Use a **field mask** (`fields.paths`) to indicate which fields you're updating.
+- **Field mask paths are top-level property names.** The read response also contains a `locale` object, but it is not the write surface — see Gotchas.
 
 ## Step 1 — (Optional) Read current site properties version
 This is useful to understand the current snapshot version and other regional fields.
@@ -25,8 +27,14 @@ curl -X GET 'https://www.wixapis.com/site-properties/v4/properties' \
   -H 'Authorization: <AUTH>'
 ```
 
-## Step 2 — Update the payment currency
-Use the `PATCH /site-properties/v4/properties` endpoint: put the new currency under `properties.paymentCurrency` and include a `fields.paths` mask.
+## Step 2 — Update the properties you need
+Use the `PATCH /site-properties/v4/properties` endpoint: put the new values under `properties` and name each one in a `fields.paths` mask.
+
+| Property | Field name | Value format |
+|---|---|---|
+| Payment currency | `paymentCurrency` | 3-letter ISO-4217 code — `USD`, `EUR`, `GBP` |
+| Time zone | `timeZone` | IANA time zone name — `America/New_York`, `Europe/Rome` |
+| Primary language | `language` | 2-letter ISO 639-1 code — `en`, `es`, `it` |
 
 ```bash
 curl -X PATCH 'https://www.wixapis.com/site-properties/v4/properties' \
@@ -42,18 +50,49 @@ curl -X PATCH 'https://www.wixapis.com/site-properties/v4/properties' \
   }'
 ```
 
+Time zone, same shape:
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/site-properties/v4/properties' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  --data-binary '{
+    "properties": {
+      "timeZone": "America/New_York"
+    },
+    "fields": {
+      "paths": ["timeZone"]
+    }
+  }'
+```
+
+To update several properties at once, include each one in `properties` and name each in `paths`:
+
+```bash
+--data-binary '{
+    "properties": { "timeZone": "Europe/Rome", "language": "en" },
+    "fields": { "paths": ["timeZone", "language"] }
+  }'
+```
+
 ### Expected response
-A successful call returns an updated Site Properties snapshot version, for example:
+A successful call returns only the updated Site Properties snapshot version — it does **not** echo the properties back:
 
 ```json
 { "version": "123" }
 ```
 
+To confirm the new value, re-read with the Step 1 `GET`.
+
 ## Gotchas & troubleshooting
-- **Always send a field mask**: omitting `fields.paths` will fail with `400` and `"Illegal request - No updates on request body"`.
+- **Always send a field mask**: omitting `fields.paths` fails with `400` and `"Illegal request - No updates on request body"`.
+- **Do not nest the mask path under `locale`.** The `GET` response contains a `locale` object (`languageCode`, `country`), which makes a path like `locale.timezone` look plausible — it is rejected with `400` and `"Illegal request - Unknown field in field mask - locale.timezone"`. Time zone and language are the top-level `timeZone` and `language` fields.
+- **`locale.languageCode` is a read-only projection** and can differ from the top-level `language` value. Set `language`; read `language` back to verify.
 - Currency must be a **3-letter ISO-4217** code (for example, `USD`, `CAD`, `EUR`, `GBP`).
+- There is no separate per-field endpoint for currency, time zone, or language — all three go through this one call.
 
 ## Related APIs
 - **Site Properties API**: [REST](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/introduction)
+- **Get Site Properties** (full read shape): [REST](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties)
 - Stores Currency Converter (conversion utilities, not for setting the site currency):
   - `POST https://www.wixapis.com/currency_converter/v1/currencies/amounts/{from}/convert/{to}`

package/skills/wix-manage/references/site-properties/site-properties-dashboard-navigation.md

@@ -0,0 +1,31 @@
+---
+name: "Site Settings Dashboard Navigation"
+description: "Builds direct links to the site-settings dashboard pages on manage.wix.com — the settings hub, website settings, and language & region. Pairs site properties with the Site Properties read API. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
+---
+
+# Site Settings Dashboard Navigation
+
+Build direct links into the settings pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Settings hub | `settings` | All site settings sections (business info, payments, etc.) |
+| Website settings | `settings/website-settings` | Site name, favicon, social sharing |
+| Language & region | `settings/language-and-region` | Language, currency, time zone |
+
+Older `manage-website...` links redirect to the current routes.
+
+## Pairing Entities with Their Read APIs
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Site properties (business info, locale, currency) | `GET /site-properties/v4/properties` | `settings` (hub) or `settings/language-and-region` |
+
+Example — after changing the payment currency:
+
+```
+Payment currency set to EUR.
+Review your regional settings: https://manage.wix.com/dashboard/{metaSiteId}/settings/language-and-region
+```

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

@@ -0,0 +1,52 @@
+---
+name: "Create Headless Site"
+description: Creates a Wix Headless site (headless business) with one account-level API call — site, Wix Business Solution apps, and a configured OAuth client.
+---
+# Create Headless Site
+
+Headless sites are not created from templates. One account-level call creates the site, installs the requested Wix Business Solution apps, and creates and configures the site's OAuth client.
+
+> Do NOT use the [Create Site from Template](create-site-from-template.md) API for headless sites — it only tags the site's namespace and skips the headless setup entirely.
+
+## Prerequisites
+
+- Wix account with site creation permissions
+- Account-level API access
+
+## Provision a Headless Business
+
+**Endpoint**: `POST https://www.wixapis.com/headless-business-setup/v1/headless-business/provision`
+
+**Request Body**:
+```json
+{
+  "newMetasite": {
+    "namingStrategy": { "metaSiteName": "My Headless Business" },
+    "seedOptions": [
+      { "businessSolution": "STORES", "clearTemplateContent": true, "seedDemoContent": false }
+    ]
+  },
+  "synchronousSteps": ["SET_METASITE_NAME", "CONFIGURE_HEADLESS_APP"]
+}
+```
+
+- `namingStrategy` — exactly one of: `metaSiteName` (exact display name), `llmPromptBasedName: {}` (name derived from the top-level `prompt` field), or `defaultName: {}`
+- `seedOptions` — Wix Business Solution apps to install at creation: `STORES`, `BLOG`, `BOOKINGS`, `EVENTS`, `PORTFOLIO`, `PRICING_PLANS`. Each entry takes `clearTemplateContent` (remove sample content) and `seedDemoContent` (seed demo content). Empty installs none
+- `synchronousSteps` — steps to complete before the call returns: `SET_METASITE_NAME`, `CONFIGURE_HEADLESS_APP`, `SEED_CONTENT`. Omitted steps run asynchronously. Include `CONFIGURE_HEADLESS_APP` when the OAuth client must be usable immediately
+
+**Response**:
+```json
+{ "metaSiteId": "<SITE_ID>", "appId": "<OAUTH_CLIENT_ID>" }
+```
+
+`appId` is the site's OAuth client ID — do NOT create a separate OAuth app.
+
+## Existing Sites
+
+To provision headless onto an existing site, pass `"existingMetasite": {}` instead of `newMetasite`. This is a site-level call in the context of that site.
+
+## Next Steps
+
+After creating the site:
+- Install additional apps using [Install Wix Apps](../app-installation/install-wix-apps.md)
+- Add content (products, services, blog posts, etc.)

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

@@ -1,6 +1,6 @@
 ---
 name: "Create Site from Template"
-description: Creates new Wix sites from templates using account-level APIs. Covers template search, site creation, headless site setup, OAuth app creation, and publishing.
+description: Creates new Wix sites from templates using account-level APIs. Covers template search, site creation, and publishing. Not for headless sites.
 ---
 # Create Site from Template
 
@@ -108,23 +108,10 @@ The `siteName` must follow these rules:
 
 If `siteName` is not provided, one is generated automatically.
 
-### For Headless Sites
-
-Add `"namespace": "HEADLESS"` to the request body:
-
-```json
-{
-  "originTemplateId": "<TEMPLATE_ID>",
-  "siteName": "my-headless-site",
-  "namespace": "HEADLESS"
-}
-```
-
 **Response** includes the new site's `metaSiteId`.
 
 ### IMPORTANT NOTES:
-- Only mention headless if user specifically requests it
-- If user doesn't ask for headless, do NOT include the `namespace` field
+- This API creates regular Wix sites. Do NOT use it for headless sites (even with a `namespace` field) — use [Create Headless Site](create-headless-site.md) instead
 
 ---
 
@@ -151,16 +138,6 @@ curl -X POST \
 
 ---
 
-## Step 5: For Headless Sites - Create OAuth App
-
-If the site was created as headless, you MUST create an OAuth app for authentication.
-
-See [Create OAuth App](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-oauth-app) documentation.
-
-This is a site-level call in the context of the newly created site.
-
----
-
 ## Common Template IDs
 
 For quick access without searching: