@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-manage/references/marketing/generate-and-publish-marketing-plan.md

@@ -4,6 +4,22 @@ description: "End-to-end flow to generate an AI-powered social media marketing p
 ---
 # RECIPE: Generate a Marketing Plan and Schedule Its Posts
 
+## THE PROTOCOL (read this first — every rule is mandatory)
+
+Walk every marketing-plan request through this conversation, in this order. Skip a step only when the user's own words in this conversation already answered it.
+
+1. **Open with the current state.** Fetch the plan (STEP 3 endpoint) and the marketing settings (`GET .../marketing-settings`). Tell the user what the plan is shaped by and what they can change: goal, marketing tools, content pillars (topics), tone of voice, point of view, business profile, and per-tool cadence. Say which inputs are site-derived and **read-only**: language, business/target locations, industry — those change in the site's Language & Region / SEO business-location settings, never through marketing settings (details in STEP 1).
+2. **Decide the settings with the user.** For each setting they want to change, use their words. If they want help choosing, fetch the selectable values (`GET .../marketing-settings/plan-goal-options`, `GET .../marketing-settings/defaults`) and propose suggestions for them to confirm. Write only values the user gave or confirmed; leave everything else to the site defaults. Never fabricate a goal, tone, or topic list on their behalf, and never put `language`, `targetLocations`, or `businessLocation` in the request or claim the call changed them.
+3. **Save, then offer to generate.** Upsert the confirmed settings (STEP 1, `fieldMask` as a comma-separated string matching exactly what you send), then offer to generate the plan — or, if a plan already exists, to regenerate it so the new settings take effect (settings are read only at generation time; use the keyword-research variant when `topics` changed). Poll until `ACTIVE` (STEPs 2-3).
+4. **Present the plan from the API data only.** Show the returned activities and their post drafts. Never invent activities, dates, or captions and present them as "the plan" — if it isn't in the response, it isn't in the plan (also applies to STEP 5's post generation).
+5. **Show before scheduling.** Scheduling publishes AI-generated drafts. Before Schedule Drafts (STEP 4), show each draft's caption and media (render the image inline, or give its URL) and get explicit approval. Schedule exactly what was approved — never regenerate after approval.
+6. **Diff the schedule response.** Only drafts for Publisher-connected channels are scheduled; the rest silently stay `DRAFT`. Compare the returned `SCHEDULED` ids against the ids you sent, and tell the user which drafts didn't schedule and which channel needs connecting (STEP 4).
+7. **Respect cutoffs and gates.** Skip `TWITTER` drafts dated after July 31, 2026. `FAILED_PRECONDITION` on Schedule Drafts means the plan lacks the premium scheduling feature: say so once and stop; it is not a transient error to retry.
+
+The rest of this recipe is the reference for executing each step.
+
+---
+
 This recipe generates a site's AI marketing plan — a schedule of marketing activities (social campaigns, blog posts, emails) from today through the end of next month — and schedules the social posts it generates. Generation is **asynchronous and non-deterministic**: you fire it, poll until it's ready, then act on the results.
 
 Base URL for all endpoints: `https://www.wixapis.com/promote/marketing-plan-service/v1`.
@@ -20,7 +36,7 @@ For a first-time plan, configure marketing settings **before** generating (STEP
 
 **API Endpoint:** `POST https://www.wixapis.com/promote/marketing-plan-service/v1/marketing-settings`
 
-Both `marketingSettings` and `fieldMask` are **required**. `fieldMask` lists the paths to write, and **every path in `fieldMask` must be present** in `marketingSettings` (otherwise the call fails with `INVALID_FIELD_MASK_ERROR`).
+Both `marketingSettings` and `fieldMask` are **required**. `fieldMask` is a **single comma-separated string** of the paths to write (proto3 field-mask form) — **not a JSON array**. Sending it as an array (`["settings.marketingPlanGoal", …]`) fails with `400` `"Failed to parse request message"`. Every path in `fieldMask` must also be present in `marketingSettings`, or the call fails with `INVALID_FIELD_MASK_ERROR`.
 
 **Language and location cannot be set here.** If the request targets a language or a place ("posts in Spanish", "customers near Berlin"), those are site-derived, read-only fields on marketing settings — never put `language`, `targetLocations`, or `businessLocation` in the request, and never tell the user this call changed them. Set the fields that do belong here (goal, tone, audience description), and direct the user to the site-level settings for the rest — see **What you can't set here** below.
 
@@ -39,15 +55,7 @@ Both `marketingSettings` and `fieldMask` are **required**. `fieldMask` lists the
       "socialMarketing": { "frequency": { "interval": "WEEK", "count": 3 } }
     }
   },
-  "fieldMask": [
-    "settings.marketingPlanGoal",
-    "settings.marketingTools",
-    "settings.topics",
-    "settings.toneOfVoice",
-    "settings.pointOfView",
-    "settings.businessProfile",
-    "overrides.socialMarketing.frequency"
-  ]
+  "fieldMask": "settings.marketingPlanGoal,settings.marketingTools,settings.topics,settings.toneOfVoice,settings.pointOfView,settings.businessProfile,overrides.socialMarketing.frequency"
 }
 ```
 
@@ -189,6 +197,7 @@ For activities that have no `items` yet, generate their posts, then schedule the
 | Symptom | Cause | Fix |
 | --- | --- | --- |
 | Plan `status: FAILED`, or `ACTIVE` with no posts | Site not published, or `SOCIAL_MARKETING` not enabled in settings | Publish the site; ensure `settings.marketingTools` includes `SOCIAL_MARKETING`, then regenerate (STEP 2) |
+| `400` `"Failed to parse request message"` on Upsert Marketing Settings | `fieldMask` sent as a JSON array (or `{ "paths": [...] }`) instead of a comma-separated string | Send `fieldMask` as a single comma-separated string, e.g. `"settings.marketingPlanGoal,settings.toneOfVoice"` |
 | `INVALID_FIELD_MASK_ERROR` on Upsert Marketing Settings | A `fieldMask` path is missing from `marketingSettings` | Include every `fieldMask` path in the `marketingSettings` body |
 | Language, region, or location "won't change" via Upsert Marketing Settings | Those fields are read-only here (site-derived) | Change them in the site's Language & Region / SEO business-location settings, then regenerate |
 | `FAILED_PRECONDITION` on Schedule Drafts | Plan lacks the schedule-posts premium feature | Advise upgrading the social media marketing plan |

package/skills/wix-manage/references/marketing/marketing-dashboard-navigation.md

@@ -0,0 +1,52 @@
+---
+name: "Marketing Dashboard Navigation"
+description: "Builds direct links to Wix marketing dashboard pages on manage.wix.com — the social posts hub (drafts, scheduled and published posts across connected channels), post design templates, saved designs, and the email marketing pages (campaigns list, campaign templates, campaign analytics). Pairs each main marketing entity (social post item, connected social account, marketing-plan post, email campaign) with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. 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."
+---
+
+# Marketing Dashboard Navigation
+
+Build direct links into the marketing pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+Marketing pages are split across **two apps** with two URL namespaces:
+
+- **Social Media Marketing** (`f27ff649-0249-4a0c-9438-841cbbfd2514`) — social posts, design templates. Routes under `social-marketing-web/`.
+- **Email Marketing** (`135c3d92-0fea-1f9d-2ba5-2a1dfb04297e`) — email campaigns. Routes under `email-marketing/`.
+
+Older links (`social-marketing`, `social-marketing/my-posts`, `shoutout`) redirect to the current routes.
+
+## Social Posts Pages (Social Media Marketing)
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Social posts hub | `social-marketing-web` | Draft, scheduled, and published social posts across connected channels; create a new post |
+| Design templates | `social-marketing-web/design-templates` | Post design template gallery |
+| My designs | `social-marketing-web/my-designs` | Saved post designs |
+
+Posts created or scheduled via the Publisher API (see [Create and Publish a Social Media Post](./create-and-publish-social-post.md)) and posts generated from an AI marketing plan (see [Generate a Marketing Plan](./generate-and-publish-marketing-plan.md)) all appear on the social posts hub.
+
+## Email Marketing Pages (Email Marketing)
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Email marketing home | `email-marketing` | Email marketing hub |
+| My campaigns | `email-marketing/my-campaigns` | All email campaigns (sent, scheduled, drafts) |
+| Campaign templates | `email-marketing/template-list` | Start a campaign from a template |
+| Campaign analytics | `email-marketing/analytics` | Campaign statistics |
+
+## Pairing Entities with Their Read APIs
+
+Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header.
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Social post (item) | Publisher API Item — created via `POST /social-publisher/v1/items`, published/scheduled via `POST /social-publisher/v1/publish-by-id` | `social-marketing-web` |
+| Connected social account | `GET /social-publisher/v1/accounts?channelName={CHANNEL}` | `social-marketing-web` |
+| Marketing-plan post | `GET /promote/marketing-plan-service/v1/marketing-plan?timeframe.startDate=...&timeframe.endDate=...` · `POST /promote/marketing-plan-service/v1/marketing-activity-posts` | `social-marketing-web` (scheduled posts land on the hub) |
+| Email campaign | `GET /email-marketing/v1/campaigns` · `GET /email-marketing/v1/campaigns/{campaignId}` | `email-marketing/my-campaigns` |
+
+Example — after scheduling a social post, hand back the hub link:
+
+```
+Scheduled your Instagram post for tomorrow 9:00.
+See it here: https://manage.wix.com/dashboard/{metaSiteId}/social-marketing-web
+```

package/skills/wix-manage/references/pricing-plans/create-and-update-pricing-plans.md

@@ -26,7 +26,87 @@ Wix Pricing Plans includes Plans that allows Wix users to build a customized mem
 Before proceeding to further steps I must read the following [documentation](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/introduction) on how to form request to pricing plans API.
 
 ### 1. Create a pricing plan
-Creating a pricing plan can be done by using [create plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan) endpoint.
+Create plans with the [Create Plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan) endpoint: `POST https://www.wixapis.com/pricing-plans/v3/plans`.
+
+Prerequisites: the site must have the Wix Pricing Plans app installed, and a site currency must be
+set — Create Plan returns `404 CURRENCY_MISSING` when the currency isn't set in site settings.
+
+#### Required request fields
+
+Send all of these on every create request. Two of them are easy to miss, so check them before
+sending:
+
+| Field | Notes |
+| --- | --- |
+| `plan.status` | Set to `"ACTIVE"`. **The generated Create Plan method schema does not list this field, but the server requires it.** Omitting it returns `400` with `plan.status: value is required` (`REQUIRED_FIELD`). The code examples on the Create Plan article all include it. |
+| `plan.visibility` | `"PUBLIC"` or `"PRIVATE"`. |
+| `plan.pricingVariants[].id` | **You must generate this GUID yourself — it is not server-assigned.** This is unusual for a create call, and it's the most common cause of a failed first attempt. Omitting it returns `400` with `plan.pricingVariants[0].id: is not a valid GUID` and `must not be empty`. Generate a fresh UUID per variant. |
+| `plan.pricingVariants[].name` | Variant name, e.g. `"Monthly"` or the plan name for a single-variant plan. |
+| `plan.pricingVariants[].billingTerms.startType` | `"ON_PURCHASE"` or `"CUSTOM"`. |
+| `plan.pricingVariants[].billingTerms.endType` | `"UNTIL_CANCELLED"` or `"CYCLES_COMPLETED"`. With `CYCLES_COMPLETED`, also send `billingTerms.cyclesCompletedDetails.billingCycleCount`. |
+| `plan.pricingVariants[].pricingStrategies[]` | Exactly one strategy. Use `flatRate.amount` as a decimal **string**, e.g. `"0"` or `"5.99"`. |
+
+`pricingVariants` is currently limited to one variant per plan.
+
+#### Minimal free plan
+
+This is the complete minimal body for a free plan — copy it and change the names and the variant
+GUID:
+
+```javascript
+async function() {
+  return await wix.request({
+    method: 'POST',
+    url: 'https://www.wixapis.com/pricing-plans/v3/plans',
+    body: {
+      plan: {
+        name: 'Free Tier',
+        visibility: 'PUBLIC',
+        status: 'ACTIVE',
+        buyable: true,
+        buyerCanCancel: true,
+        pricingVariants: [
+          {
+            id: '7a3f1e2d-4b5c-6d7e-8f9a-0b1c2d3e4f5a', // generate a fresh GUID
+            name: 'Free Tier',
+            pricingStrategies: [{ flatRate: { amount: '0' } }],
+            billingTerms: {
+              startType: 'ON_PURCHASE',
+              endType: 'UNTIL_CANCELLED'
+            }
+          }
+        ]
+      }
+    }
+  });
+}
+```
+
+Do **not** add a `billingCycle` to a free plan: a free plan can't be recurring, and the server
+rejects that combination with `400 FREE_PRICING_VARIANT_IS_NOT_RECURRING`.
+
+#### Other plan types
+
+Same required fields; only `billingTerms` and the `flatRate.amount` change.
+
+| Plan type | `billingTerms` |
+| --- | --- |
+| Free, open-ended | Omit `billingCycle`; `endType: "UNTIL_CANCELLED"`. `flatRate.amount: "0"`. |
+| One-time payment, fixed duration | `billingCycle` = the duration (e.g. `{ period: 'MONTH', count: 1 }`), `endType: "CYCLES_COMPLETED"`, `cyclesCompletedDetails.billingCycleCount: 1`. |
+| Recurring, until cancelled | `billingCycle` = the recurrence (e.g. `{ period: 'MONTH', count: 1 }`), `endType: "UNTIL_CANCELLED"`. |
+
+A `billingCycle` can't be shorter than 7 days, and total plan duration can't exceed 10 years
+(`400 VALID_BILLING_CYCLE` / `400 VALID_PLAN_DURATION`).
+
+Two more optional fields worth knowing:
+
+- **Purchase caps.** In V3 these are `plan.purchaseLimits`, an array of
+  `{ type, maxCount }`. `type` is one of `PER_MEMBER_LIFETIME`, `PER_MEMBER_ACTIVE`,
+  `TOTAL_ACTIVE`, `TOTAL_SOLD`. To make a plan available only once per member, send
+  `purchaseLimits: [{ type: 'PER_MEMBER_LIFETIME', maxCount: 1 }]`. Some Create Plan examples still
+  use the V2-era `maxPurchasesPerBuyer` field; `purchaseLimits` is the V3 equivalent.
+- **Free trials.** `pricingVariants[].freeTrialDays` only applies to recurring *paid* plans — using
+  it on a free plan returns `400 FREE_TRIAL_IS_APPLICABLE`.
 
 ### 2. Attach integrating app entity to pricing plans
 
@@ -69,6 +149,24 @@ Each item in the request for this endpoint must adhere to these rules:
 - `itemSetId` must set to the created pool definition benefit item set id.
 - `externalId` must be set to the integrating app entity id, example: booking service id or blog post id.
 
+### 3. Stop offering a plan — archive it, don't delete it
+
+When the user asks to archive, retire, or stop offering a plan, **archive** it so existing
+subscribers and order history are preserved. Archiving is an Update Plan call — there is no
+separate archive endpoint, and Delete Plan is not the same thing:
+
+```bash
+curl -X PATCH \
+  'https://www.wixapis.com/pricing-plans/v3/plans/<PLAN_ID>' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "plan": { "id": "<PLAN_ID>", "revision": "<CURRENT_REVISION>", "archived": true } }'
+```
+
+Carry the plan's current `revision` or the update is rejected. `archived` is not listed in the
+generated Plan object reference, so it cannot be found by reading the schema — reach for it
+directly rather than searching for an archive method or falling back to Delete Plan.
+
 ## Pricing plans REST API Documentation Reference
 - [Create plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan)
 - [Get plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/get-plan)

package/skills/wix-manage/references/pricing-plans/pricing-plans-dashboard-navigation.md

@@ -0,0 +1,45 @@
+---
+name: "Pricing Plans Dashboard Navigation"
+description: "Builds direct links to Wix Pricing Plans dashboard pages on manage.wix.com — plans list, create a plan, edit a plan, record a manual order, and settings. Pairs each main Pricing Plans entity (plan, order) with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. 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."
+---
+
+# Pricing Plans Dashboard Navigation
+
+Build direct links into the Wix Pricing Plans pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+All Wix Pricing Plans (app ID `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`) pages live under:
+
+```
+https://manage.wix.com/dashboard/{metaSiteId}/pricing-plans/{route}
+```
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Plans list | `pricing-plans` | All pricing plans; purchases (orders/subscriptions) are a tab of this page |
+| Create plan | `pricing-plans/new` | New plan form |
+| Edit plan | `pricing-plans/edit` | A specific plan — reached from the plans list (no documented ID path segment) |
+| New manual order | `pricing-plans/new-order` | Record a manual (offline) plan order for a member |
+| Settings | `pricing-plans/settings` | Pricing Plans settings |
+
+There is no separate route for the purchases list — it is a tab of the main `pricing-plans` page.
+
+Older `membership...` links (`membership`, `paid-plans`, `membership/setup`, `membership/orders/new`, `membership-settings`) redirect to the current routes.
+
+## Pairing Entities with Their Read APIs
+
+Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header.
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Plan | `POST /pricing-plans/v3/plans/query` · `GET /pricing-plans/v3/plans/{planId}` | `pricing-plans` (list) or `pricing-plans/edit` (opened from the list) |
+| Order (subscription/purchase) | `GET /pricing-plans/v2/orders` · `GET /pricing-plans/v2/orders/{id}` | `pricing-plans` (purchases tab) |
+| Settings | Pricing Plans Settings API (Get Pricing Plans Settings) | `pricing-plans/settings` |
+
+Example — after creating a plan, hand back the plans page:
+
+```
+Created "Gold Membership".
+Manage it here: https://manage.wix.com/dashboard/{metaSiteId}/pricing-plans
+```

package/skills/wix-manage/references/restaurants/restaurants-dashboard-navigation.md

@@ -0,0 +1,68 @@
+---
+name: "Restaurants Dashboard Navigation"
+description: "Builds direct links to Wix Restaurants dashboard pages on manage.wix.com — menus, menu items, the online orders board, online-ordering fulfillment settings (pickup, delivery, dine-in), the reservations list, floor plans, and reservation experience settings. Pairs each main Restaurants entity (menu, section, item, order, reservation) with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. 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."
+---
+
+# Restaurants Dashboard Navigation
+
+Build direct links into the restaurant pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+Restaurant pages are split across **three apps** with three URL namespaces:
+
+- **Wix Restaurants Menus** (`b278a256-2757-4f19-9313-c05c783bec92`) — menus, sections, items. Routes under `wix-restaurants-menus-new/`.
+- **Wix Restaurants Orders** (`9a5d83fd-8570-482e-81ab-cfa88942ee60`) — online orders board and online-ordering settings. Routes under `wix-restaurants-orders-new/`.
+- **Wix Table Reservations** (`f9c07de2-5341-40c6-b096-8eb39de391fb`) — reservations, floor plans, reservation experiences. Routes under `wix-table-reservations/`.
+
+Older links (`restaurants/menus-management`, `restaurants/table-reservations`, `restaurants-orders-prep-board`, `olo-settings/...`) redirect to the current routes.
+
+## Menus Pages (Wix Restaurants Menus)
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Menus | `wix-restaurants-menus-new` | All menus (and their sections) |
+| Edit menu | `wix-restaurants-menus-new/menu/{menuId}` | A specific menu |
+| Items | `wix-restaurants-menus-new/items` | All menu items |
+| Menu printing | `wix-restaurants-menus-new/menus-printing` | Print-ready menu export |
+
+## Orders Pages (Wix Restaurants Orders)
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Orders board | `wix-restaurants-orders-new` | Incoming online orders (prep board) |
+| Online orders settings | `wix-restaurants-orders-new/settings` | Online-ordering settings hub |
+
+Fulfillment and ordering sub-settings live at `wix-restaurants-orders-new/settings/{subpage}`: `pickup`, `delivery`, `pickup-delivery`, `dine-in`, `closure-dates`, `scheduling-page`, `service-fee`, `printing`, `doordash`.
+
+## Reservations Pages (Wix Table Reservations)
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Reservations list | `wix-table-reservations/table-reservations` | All table reservations |
+| Floor plan view | `wix-table-reservations/floor-plan-view` | Live floor-plan view of reservations |
+| Floor plan editor | `wix-table-reservations/floor-plan` | Table layout (floor plan) |
+| Create experience | `wix-table-reservations/create-experience` | New reservation experience |
+| Experience settings | `wix-table-reservations/experience` | A reservation experience (seating rules, policies) |
+
+Experience sub-settings live at `wix-table-reservations/experience/{subpage}`: `details`, `schedule`, `reservation-form`, `reservation-settings`, `table-assignment`, `polices`.
+
+## Pairing Entities with Their Read APIs
+
+Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header.
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Menu | `POST /restaurants/menus-menu/v1/menus/query` · `GET /restaurants/menus-menu/v1/menus` | `wix-restaurants-menus-new/menu/{menuId}` (edit) or `wix-restaurants-menus-new` (list) |
+| Section | `POST /restaurants/menus-section/v1/sections/query` | `wix-restaurants-menus-new` (sections are managed inside their menu) |
+| Item | `POST /restaurants/menus-item/v1/items/query` | `wix-restaurants-menus-new/items` |
+| Order | `POST /ecom/v1/orders/search` · `GET /ecom/v1/orders/{orderId}` | `wix-restaurants-orders-new` (board) or `ecom-platform/order-details/{orderId}` |
+| Reservation | `POST /table-reservations/reservations/v1/reservations/query` · `GET /table-reservations/reservations/v1/reservations/{reservationId}` | `wix-table-reservations/table-reservations` |
+| Reservation location (settings) | `POST /table-reservations/reservation-locations/v1/reservation-locations/query` | `wix-table-reservations/experience` |
+
+Restaurant online orders are eCommerce orders (their `lineItems[].catalogReference.appId` is `9a5d83fd-8570-482e-81ab-cfa88942ee60`), so they can also be read and linked through the eCommerce orders pages.
+
+Example — after creating a menu, hand back its edit link:
+
+```
+Created "Dinner Menu".
+Manage it here: https://manage.wix.com/dashboard/{metaSiteId}/wix-restaurants-menus-new/menu/{menuId}
+```

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