@wix/agent-skills 1.31.0 → 1.31.2

package/skills/wix-manage/references/stores/add-store-pages-to-site.md

@@ -4,6 +4,9 @@ description: Adds missing checkout and cart pages to a site when Stores app is i
 ---
 # Add Store Pages to Site
 
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 This recipe demonstrates how to add checkout and cart pages to a Wix site when the Stores app is installed but pages are missing.
 
 ## Overview

package/skills/wix-manage/references/stores/change-store-currency.md

@@ -5,6 +5,9 @@ description: "Changes the store's payment currency through Site Properties and e
 
 # Change Store Currency
 
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 Use the [Change a Site's Regional Properties (Currency, Time Zone, Language) via Site Properties API](../site-properties/change-payment-currency-site-properties.md) recipe to set the requested payment currency and read it back. Confirm the change with the user before updating it.
 
 Catalog product responses may temporarily show the previous currency after carts and checkout use the new one. Allow time for propagation, then recheck.

package/skills/wix-manage/references/stores/create-product-catalog-v3.md

@@ -5,6 +5,9 @@ description: Mandatory first recipe for every Wix Stores Catalog V3 create-produ
 
 # Create Product (Catalog V3)
 
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 Use this recipe for one or multiple Catalog V3 products. Catalog V1 remains supported through [Create Product (Catalog V1)](create-product-catalog-v1.md).
 
 > [!IMPORTANT]

package/skills/wix-manage/references/stores/find-products-query-and-search-catalog-v3.md

@@ -5,6 +5,9 @@ description: Find, search, query, and list products from a Wix Store using Catal
 
 # RECIPE: Business Recipe – Find Products in a Wix Store (Query and Search, Catalog V3)
 
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 Find products in a Wix store using the Catalog V3 Search Products and Query Products APIs.
 
 ## Article: How to Find Products

package/skills/wix-manage/references/stores/update-product-with-options.md

@@ -1,6 +1,6 @@
 ---
 name: "Update Product with Options (Catalog V3)"
-description: Modifies existing products and variants using Catalog V3 Products API. Covers adding/removing option choices, variant-specific pricing, product visibility (hide, unhide, or show a product in the storefront — a product-level `visible` update, never a delete), and revision-based updates to prevent conflicts.
+description: "Start here for existing Catalog V3 product updates, including digital products that fail at add-to-cart with ITEM_NOT_FOUND_IN_CATALOG. Includes name lookup, Get Product, and PATCH in one flow, plus importing a supplied PDF and attaching it to the existing variant. Covers options, variant prices and SKUs, product visibility (hide/unhide through `visible`, never delete), description edits that preserve Rich Content, and revision-based updates. Read another recipe only for a field or operation this flow does not cover."
 ---
 **RECIPE**: Business Recipe - Updating a Wix Store Product (Catalog V3)
 
@@ -14,7 +14,8 @@ Every Catalog V3 product update is revision-based:
 - Use [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product) to retrieve the current product, its `product.revision`, and its existing variants. Search Products and Query Products responses do not include `variantsInfo.variants`, so a variant or price update assembled from a search result sends an empty variants array and is rejected. Re-read the product before every variant-level update.
 - Include `product.id` and the current `product.revision` in every [Update Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/update-product) PATCH body.
 - Update Product is a partial update: only `product`, `product.id`, and `product.revision` are required, and top-level fields you omit (for example `name`, `ribbon`, `brand`) are left unchanged. The full-array overwrite rule applies only to the repeated fields `options`, `modifiers`, and `variantsInfo.variants`.
-- For simple text/HTML description updates, prefer `plainDescription`. Use `description` only when sending a Rich Content object.
+- Get Product returns a default set of fields. When an update keeps or carries over existing projected data, request that data in `fields` before building the PATCH. For any edit that keeps part of the existing product description, request `DESCRIPTION`; a read without it has no Rich Content document to preserve.
+- For description changes, see [Update Description](#update-description): replacing the whole description uses `plainDescription`; editing any existing content uses the Rich Content `description` field.
 
 ### Find the product by name
 
@@ -24,12 +25,16 @@ curl -X POST "https://www.wixapis.com/stores/v3/products/search" \
   -H "Authorization: <AUTH>" \
   -d '{
     "search": {
-      "expression": "Product name"
+      "search": {
+        "expression": "Product name",
+        "fields": ["name"],
+        "fuzzy": false
+      }
     }
   }'
 ```
 
-For product-name lookup, prefer Search Products before retrieving the product by ID. Search only resolves the product ID; it does not replace the Get Product call.
+Read `products` from the search response. Prefer an exact name match; otherwise select a clear, unambiguous match, such as a name differing only in capitalization. If no result clearly identifies the requested product, or multiple products could match, ask the user which product they mean. Use the selected `products[].id` in Get Product; search only resolves the ID.
 
 ### Get the current revision
 
@@ -38,6 +43,15 @@ curl -X GET "https://www.wixapis.com/stores/v3/products/{productId}" \
   -H "Authorization: <AUTH>"
 ```
 
+To edit an existing description, request its Rich Content document in the same read:
+
+```bash
+curl -X GET "https://www.wixapis.com/stores/v3/products/{productId}?fields=DESCRIPTION" \
+  -H "Authorization: <AUTH>"
+```
+
+`product.description` is returned only when `DESCRIPTION` is requested. Request every other projected field that you need to carry over with its documented `fields` value as well.
+
 ## Common Update Patterns
 
 ### Hide or Show a Product
@@ -66,9 +80,16 @@ Visibility behaviour to report back accurately:
 - For a product **with** options, product and variant visibility are independent: setting `product.visible` to `false` leaves each `variantsInfo.variants[].visible` as it was.
 - Point-of-sale visibility is a separate field, `visibleInPos`. Only change it when the user asks about POS. It is always `false` for `productType: DIGITAL`.
 
-### Update Description Only
+### Update Description
+
+Choose the flow from the user's request:
+
+- "Set the description to X", "replace the description", or "write a new description": **Replace the Description**.
+- "Add", "append", "prepend", "insert", "fix a typo", or "remove" existing text: **Edit the Existing Description**. Any request that keeps part of the current description is an edit.
+
+#### Replace the Description
 
-For a normal user request like "set the product description to X", use `plainDescription` with valid HTML. The API converts it to rich content.
+For a request like "set the product description to X", use `plainDescription` with valid HTML. The API converts it to rich content.
 
 Do not send a plain string in `description`. `description` is a Rich Content object.
 
@@ -85,7 +106,7 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
-Use `description` only when you intentionally need to send Rich Content:
+For a full replacement with node types beyond the paragraph below, read [Author Ricos Rich Content](../rich-content/author-ricos-rich-content.md). Existing-document edits use the read-modify-write flow below:
 
 ```bash
 curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
@@ -123,6 +144,77 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
+Both fields replace the whole description. To keep any existing content, use **Edit the Existing Description**.
+
+#### Edit the Existing Description
+
+For prepend, append, and text removal, execute the documented calls directly: the examples in this recipe and the request/response contract below provide the fields this flow needs. Reuse this contract rather than rediscovering the Search, Get, and Update schemas. Consult further API documentation when the request requires a field or node type not covered here, or when a documented call fails. Read [Author Ricos Rich Content](../rich-content/author-ricos-rich-content.md) when creating other node types.
+
+| Call | Request | Response fields used next |
+|---|---|---|
+| Search Products, when given a name | Use [Find the product by name](#find-the-product-by-name); `search.search` contains `expression`, `fields: ["name"]`, and `fuzzy: false`. | `products[]` contains `id` and `name`; select the product using the name-matching guidance above. |
+| Get Product | `GET https://www.wixapis.com/stores/v3/products/{productId}?fields=DESCRIPTION` | `product.id`, `product.revision`, and the full `product.description`. |
+| Update Product | `PATCH https://www.wixapis.com/stores/v3/products/{productId}` with `{ product: { id, revision, description }, fields: ["DESCRIPTION"] }`, using the read ID/revision and complete edited document. | `product.description` verifies the edit; `product.revision` is the new revision. |
+
+The request-level `fields` array projects response data; it is separate from `search.search.fields`, which selects the fields searched. A description-only PATCH needs only the three product fields shown above; variant, option, price, and physical-property fields belong to other update flows.
+
+Use a single read-modify-write operation: locate the product, read its description and revision, make the requested change in memory, then PATCH once and verify the response.
+
+1. Read [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product) with `?fields=DESCRIPTION`. Its response wraps the document as `product.description` and the current revision as `product.revision`. If the description is missing or has no `nodes`, stop and ask before replacing it.
+2. Copy the complete returned `product.description`, including node IDs, decorations, `metadata`, and `documentStyle`, **before locating any nodes to edit**. Traverse the copy and keep references to its nodes; edit that same copy and send it in the PATCH. For prepend/append, insert one new `PARAGRAPH` at the beginning/end of its `nodes`. For a wording change, modify only the matching `TEXT` node's `textData.text`.
+3. For removal, trim only the requested substring from the matching TEXT run and keep its decorations. When the whole run or node is targeted, remove that entry from its parent `nodes` array. If text spans runs, trim the matching portion of each run. Preserve all other nodes, spacer paragraphs, and document properties. If the requested change is already present, report that state and finish without a write.
+4. Check the in-memory PATCH document before sending: the targeted text has the requested value and untouched content matches the read document. Then send [Update Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/update-product) to `PATCH https://www.wixapis.com/stores/v3/products/{productId}` with `product.id`, the read revision, the full edited `product.description`, and top-level `fields: ["DESCRIPTION"]`. Leave other product fields out of this description-only update; `plainDescription` is for whole-description replacements.
+5. Verify `product.description` in the PATCH response: the requested change is present and untouched nodes, decorations, and document properties remain. Confirm completion from that response and finish. A successful PATCH has already performed the edit; verification does not require another PATCH. If the response is incomplete, read once with `?fields=DESCRIPTION` to verify. If a revision conflict rejects the write, read the latest document and reapply the requested change only if it is still needed.
+
+For a prepend, build the complete PATCH body from the Get Product response (`getResponse` below). For an append, use `push` instead of `unshift`:
+
+```javascript
+const product = getResponse.product;
+const description = structuredClone(product.description);
+description.nodes.unshift({
+  type: "PARAGRAPH",
+  nodes: [{
+    type: "TEXT",
+    textData: { text: "New text.", decorations: [] }
+  }],
+  paragraphData: { textStyle: { textAlignment: "AUTO" } }
+});
+const patchBody = {
+  product: { id: product.id, revision: product.revision, description },
+  fields: ["DESCRIPTION"]
+};
+```
+
+Send `patchBody` as the JSON body of the PATCH above. The copy retains the returned document's other properties and existing nodes, including links and buttons; the response's `product.description` includes the edited document because the request projects `DESCRIPTION`.
+
+For example, remove only `read ` from a TEXT run containing `read the guide`, retaining its BOLD and LINK decorations and siblings. Locate the run in the cloned document, including nested nodes, rather than assuming a paragraph/run index. This example handles a phrase within one TEXT run; a phrase spanning runs uses the per-run trimming in step 3, with all run references taken from the copy.
+
+```javascript
+const product = getResponse.product;
+const description = structuredClone(product.description);
+const target = "read the guide";
+const replacement = "the guide";
+const matches = [];
+function locate(node) {
+  if (node.type === "TEXT" && node.textData.text.includes(target)) matches.push(node.textData);
+  for (const child of node.nodes ?? []) locate(child);
+}
+locate(description);
+if (matches.length !== 1) throw new Error("Clarify which text occurrence to edit");
+const textData = matches[0];
+const originalText = textData.text;
+const start = originalText.indexOf(target);
+if (start !== originalText.lastIndexOf(target)) throw new Error("Clarify which text occurrence to edit");
+textData.text = originalText.slice(0, start) + replacement + originalText.slice(start + target.length);
+if (textData.text === originalText || textData.text.includes(target)) {
+  throw new Error("The PATCH document must contain the requested edit before writing");
+}
+const patchBody = {
+  product: { id: product.id, revision: product.revision, description },
+  fields: ["DESCRIPTION"]
+};
+```
+
 ### Update Options and Variants
 
 When adding or changing options and variants, send the full option definitions and one variant for each option-choice combination. Use `optionChoiceNames` to reference choices.
@@ -339,8 +431,11 @@ its `id`, its `choices` (by `optionChoiceIds` — or `optionChoiceNames`, see *G
 
 ```bash
 # A choice image + a variant's sale price, one PATCH. Both arrays are complete and keep their ids —
-# this exact shape is the one that succeeds; the two shortcuts (choices by name only, or a variant
-# without its choices/price) each 400.
+
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+# keep the option and choice IDs when rebuilding the options array, and each variant
+# with its choices and price. Omitting those identities or required variant fields can reject the update.
 curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   -H "Content-Type: application/json" -H "Authorization: <AUTH>" \
   -d '{ "product": { "id": "{productId}", "revision": "{currentRevision}",
@@ -357,9 +452,67 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
             "choices": [ { "optionChoiceIds": { "optionId": "{optionId}", "choiceId": "{choiceId2}" } } ] } ] } } }'
 ```
 
+### Prepare a Price or SKU Update
+
+For an existing product's price or SKU, use the name lookup above, then Get Product. Request `?fields=VARIANT_OPTION_CHOICE_NAMES&fields=MERCHANT_DATA&fields=PRODUCT_CHOICES_MEDIA_REFERENCES&fields=PRODUCT_CHOICES_DISPLAY_IMAGE` so the same read supplies variant choice names, permitted cost data, and choice media to preserve. The response is `{ product: { id, revision, options, variantsInfo: { variants } } }`; search results cannot supply the variants.
+
+Build the complete writable options and variants from that response, then change only the requested field. **Every variants PATCH also includes the complete `options` array**, even for an SKU-only change; for a product without options, send `options: []`. Omitting options caused `428 MISSING_OPTIONS_ON_UPDATE_VARIANTS`. A variant retains its `id`, `choices`, price, and other writable fields. The example below copies the writable fields used by these flows and strips calculated monetary values; inventory status and variant media are read-only and are not part of this update.
+
+```javascript
+const product = getResponse.product;
+const pick = (source, keys) => Object.fromEntries(keys
+  .filter(key => source[key] !== undefined)
+  .map(key => [key, structuredClone(source[key])]));
+const amountOnly = value => ({ amount: value.amount });
+const options = (product.options ?? []).map(option => ({
+  ...pick(option, ["id", "name", "optionRenderType"]),
+  choicesSettings: { choices: option.choicesSettings.choices.map(choice =>
+    pick(choice, ["choiceId", "name", "choiceType", "colorCode", "media", "displayImage"])) }
+}));
+const variants = product.variantsInfo.variants.map(variant => {
+  const copy = pick(variant, ["id", "visible", "sku", "barcode", "physicalProperties"]);
+  copy.choices = (variant.choices ?? []).map(choice => ({
+    optionChoiceNames: pick(choice.optionChoiceNames, ["optionName", "choiceName", "renderType"])
+  }));
+  copy.price = { actualPrice: amountOnly(variant.price.actualPrice) };
+  if (variant.price.compareAtPrice) copy.price.compareAtPrice = amountOnly(variant.price.compareAtPrice);
+  if (variant.revenueDetails?.cost) copy.revenueDetails = { cost: amountOnly(variant.revenueDetails.cost) };
+  if (variant.digitalProperties) {
+    copy.digitalProperties = variant.digitalProperties.digitalFile
+      ? { digitalFile: { id: variant.digitalProperties.digitalFile.id } } : {};
+  }
+  if (copy.physicalProperties?.pricePerUnit) delete copy.physicalProperties.pricePerUnit.value;
+  return copy;
+});
+const variantPatchProduct = {
+  id: product.id, revision: product.revision, options,
+  variantsInfo: { variants }
+};
+```
+
+For the single-variant product case (a user asking to change a simple product's price), use the prepared body above:
+
+```javascript
+if (variants.length !== 1) throw new Error("Clarify which variants should receive the price change");
+variants[0].price.actualPrice.amount = "25"; // requested price
+const pricePatchBody = { product: variantPatchProduct };
+```
+
+For a named option choice such as `Size = Large`, use its returned choice names to select one variant, then change its SKU:
+
+```javascript
+const matches = variants.filter(variant => variant.choices.some(choice =>
+  choice.optionChoiceNames.optionName === "Size" && choice.optionChoiceNames.choiceName === "Large"));
+if (matches.length !== 1) throw new Error("Clarify which variant should receive the SKU change");
+matches[0].sku = "MUG-L-001"; // requested SKU
+const skuPatchBody = { product: variantPatchProduct };
+```
+
+Send the selected body to `PATCH https://www.wixapis.com/stores/v3/products/{productId}` in the same ExecuteWixAPI invocation as the name lookup and Get Product. Its response is `{ product: { id, revision, variantsInfo: { variants } } }`; verify the changed variant by its retained ID and confirm from that response. These examples provide the request fields and response paths for price and SKU changes; proceed directly after reading this recipe. Discover further schemas only for fields not covered here or a documented call that fails.
+
 ### Update Variant Price Only
 
-Read `{existingVariantId}` off the Get Product response; a Search or Query Products result does not carry it.
+Read `{existingVariantId}` off the Get Product response; a Search or Query Products result does not carry it. The curl below is for a single-variant product without options. For an optioned product, use the complete options/variants body in **Prepare a Price or SKU Update**.
 
 ```bash
 curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
@@ -369,10 +522,12 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
     "product": {
       "id": "{productId}",
       "revision": "{currentRevision}",
+      "options": [],
       "variantsInfo": {
         "variants": [
           {
             "id": "{existingVariantId}",
+            "choices": [],
             "price": {
               "actualPrice": {
                 "amount": "29.99"
@@ -387,7 +542,23 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
 
 ### Attach a Digital File
 
-A `DIGITAL` product is **sellable** only when its variant carries both a digital file and stock. Upload the file first ([Upload Media to Wix](../media/upload-media-to-wix.md) → Generate Upload URL, then `PUT` the bytes), then send its `file.id` on the variant — `digitalProperties` is a variant field, never a product field.
+For an existing digital product rejected at add-to-cart with `ITEM_NOT_FOUND_IN_CATALOG`, use this repair flow. For a supplied external PDF URL, the table below is the complete request/response contract; execute it directly after reading this recipe. Use its linked method URLs as source citations. Further schema discovery is needed only for a field not covered here or a documented call that fails.
+
+First locate the existing product with the name lookup above, then Get Product for its revision and variants. If the requested product is absent or ambiguous, ask for the correct product or site and stop before uploading media. Repairing an existing product does not authorize creating a replacement.
+
+A `DIGITAL` product is sellable only when its variant has both a digital file and stock. For a product already in stock, keep that stock unchanged and attach only the missing file. `digitalProperties` belongs to the variant.
+
+| Call | Request | Response fields used next |
+|---|---|---|
+| [Search Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products) | Use the `search.search` name lookup above. | `products[].id` and `name` select the existing product. |
+| [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product) | `GET https://www.wixapis.com/stores/v3/products/{productId}?fields=VARIANT_OPTION_CHOICE_NAMES&fields=MERCHANT_DATA&fields=PRODUCT_CHOICES_MEDIA_REFERENCES&fields=PRODUCT_CHOICES_DISPLAY_IMAGE` | `product.id`, `revision`, `productType`, `options`, and `variantsInfo.variants` supply the complete writable state. |
+| [Import File](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file) | `POST https://www.wixapis.com/site-media/v1/files/import` with `{ "url": "{suppliedPdfUrl}", "mimeType": "application/pdf", "displayName": "download.pdf", "private": true }` | `file.id` and `file.operationStatus`. Import the exact supplied URL once; retain this ID. |
+| [Get File Descriptor](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/get-file-descriptor), only while PENDING | `GET https://www.wixapis.com/site-media/v1/files/get-file-by-id?fileId={fileId}` | `file.operationStatus`: wait for `READY`, stop on `FAILED`. The response is wrapped in `file`. |
+| [Update Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/update-product) | `PATCH https://www.wixapis.com/stores/v3/products/{productId}` with `{ product: { id, revision, options, variantsInfo: { variants } } }` | `product.variantsInfo.variants[].digitalProperties.digitalFile.id` confirms the attachment on the retained variant ID. |
+
+Chain these requests in one ExecuteWixAPI invocation; with `wix.request`, the REST response body is in `response.data`. Private import keeps the stored download private. For a local file rather than a supplied URL, read [Upload Media to Wix](../media/upload-media-to-wix.md) and use its Generate Upload URL flow instead.
+
+Prepare the complete options/variants body as in **Prepare a Price or SKU Update**, retain every variant ID, choice and price, and set the requested variant's `digitalProperties.digitalFile.id` to the imported file ID. For one existing variant with no options:
 
 ```bash
 curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
@@ -397,22 +568,21 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
     "product": {
       "id": "{productId}",
       "revision": "{currentRevision}",
+      "options": [],
       "variantsInfo": {
-        "variants": [
-          {
-            "id": "{existingVariantId}",
-            "price": { "actualPrice": { "amount": "9.99" } },
-            "visible": true,
-            "inventoryItem": { "inStock": true },
-            "digitalProperties": { "digitalFile": { "id": "{fileId}" } }
-          }
-        ]
+        "variants": [{
+          "id": "{existingVariantId}",
+          "choices": [],
+          "price": { "actualPrice": { "amount": "{existingPrice}" } },
+          "visible": true,
+          "digitalProperties": { "digitalFile": { "id": "{fileId}" } }
+        }]
       }
     }
   }'
 ```
 
-Confirm from `product.variantsInfo.variants[].digitalProperties.digitalFile` in the response.
+Copy any other writable variant fields from the read product using the preparation example. Chain the product lookup, read, selected upload path, and one PATCH in one ExecuteWixAPI invocation. Confirm from `product.variantsInfo.variants[].digitalProperties.digitalFile.id` in the PATCH response; no extra product read is needed when that response supplies it.
 
 ## Important Notes
 
@@ -439,4 +609,4 @@ Confirm from `product.variantsInfo.variants[].digitalProperties.digitalFile` in
 | `Missing option choices` or `INVALID_DEFAULT_VARIANT` | Product has options but at least one variant has no matching choices | Rebuild `variantsInfo.variants` so every variant includes choices for all product options |
 | `DIGITAL_PRODUCT_CANNOT_BE_VISIBLE_IN_POS` | Sent `visibleInPos: true` on a digital product | Digital products can't be visible in POS; leave `visibleInPos` out of the body |
 | `ITEM_NOT_FOUND_IN_CATALOG` at add-to-cart, product exists | A `DIGITAL` variant has no `digitalProperties.digitalFile` | Attach a file — see [Attach a Digital File](#attach-a-digital-file) |
-| `exceeds available inventory` at add-to-cart, product exists | The variant has no stock (`DIGITAL` products included) | Set `inventoryItem.inStock: true` on the variant |
+| `exceeds available inventory` at add-to-cart, product exists | The variant has no stock (`DIGITAL` products included) | Update its stock through the Inventory API; inventory is separate from an Update Product PATCH |

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

@@ -1,243 +0,0 @@
----
-name: "Create Appointment Service"
-description: "Create an appointment booking service — e.g. 'set up consultations', 'create a 1-on-1 session', 'add a personal training appointment', 'create a meeting service for $25'. Handles staff assignment (required), session duration, pricing, and 1-on-1 capacity defaults via bulkCreateServices API."
----
-
-# Create Appointment Service from Prompt
-
-## When to Use
-
-- User wants to create an appointment-based service: "set up consultations", "create a 1-on-1 session", "add a personal training appointment", "create a meeting service"
-- The service type is APPOINTMENT — customer picks an available time slot during staff working hours
-- For general service creation where the type is ambiguous, see [Create Booking Service from Prompt](./create-booking-service-from-prompt.md)
-
-## Prerequisites
-
-- For full API field definitions, validation rules, and troubleshooting, see [Create and Update Booking Services](./create-and-update-booking-services.md)
-
----
-
-## Step 1: Gather Business Context
-
-Run these queries to collect site data for informed defaults.
-
-### 1a. Query Staff Members (CRITICAL for Appointments)
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v1/staff-members/query' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "query": {},
-    "fields": ["RESOURCE_DETAILS"]
-  }'
-```
-
-Save each staff member's `resourceId` (not `id`). Note which one has `default: true`.
-
-**APPOINTMENT services REQUIRE at least one staff member.** If no staff members exist, create one first using [Bookings Staff Setup](./bookings-staff-setup.md).
-
-### 1b. Query Service Categories
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "query": {} }'
-```
-
-### 1c. Query Existing Services (Duplicate Check)
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v2/services/query' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "query": { "paging": { "limit": 100 } } }'
-```
-
-Warn the user if a service with a similar name already exists.
-
----
-
-## Step 2: Apply Appointment Defaults
-
-For any fields the user did not explicitly specify:
-
-| Field | Default | Notes |
-|---|---|---|
-| Duration | 60 minutes | Set via `schedule.availabilityConstraints.sessionDurations` |
-| Capacity | 1 | Appointments are typically 1-on-1 |
-| Staff | Auto-assign | Use `default: true` staff, or first available |
-| Online booking | Enabled | `onlineBooking.enabled: true` |
-
-### Pricing (if not specified)
-
-- If user specifies a price → `rateType: "FIXED"`
-- If user says "free" → `rateType: "NO_FEE"`, `options.inPerson: true`, `options.online: false`
-- If no price mentioned → infer from context (consultations ~$50-100, sessions ~$30-60) or default to free
-
-### Staff Assignment
-
-- **1 staff member** → auto-assign using their `resourceId`
-- **Multiple staff members** → use the one with `default: true`, or the first one
-- **No staff members** → create one first using [Bookings Staff Setup](./bookings-staff-setup.md), then proceed
-
-### Category
-
-- If categories exist → assign the most relevant one
-- If no categories exist → create a "General" category:
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v2/categories' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "category": { "name": "General" } }'
-```
-
-### Service Name & Description
-
-- Use the user's wording for the service name
-- Generate a brief, professional description (1-2 sentences)
-
----
-
-## Step 3: Create the Appointment Service
-
-**Paid appointment:**
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "returnEntity": true,
-    "services": [{
-      "name": "<SERVICE_NAME>",
-      "description": "<GENERATED_DESCRIPTION>",
-      "type": "APPOINTMENT",
-
-      "onlineBooking": { "enabled": true },
-      "staffMemberIds": ["<RESOURCE_ID>"],
-      "schedule": {
-        "availabilityConstraints": {
-          "sessionDurations": [<DURATION_MINUTES>]
-        }
-      },
-      "payment": {
-        "rateType": "FIXED",
-        "options": { "online": true, "inPerson": false },
-        "fixed": {
-          "price": { "value": "<PRICE>" }
-        }
-      },
-      "category": {
-        "id": "<CATEGORY_ID>"
-      }
-    }]
-  }'
-```
-
-**Free appointment:**
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "returnEntity": true,
-    "services": [{
-      "name": "<SERVICE_NAME>",
-      "description": "<GENERATED_DESCRIPTION>",
-      "type": "APPOINTMENT",
-
-      "onlineBooking": { "enabled": true },
-      "staffMemberIds": ["<RESOURCE_ID>"],
-      "schedule": {
-        "availabilityConstraints": {
-          "sessionDurations": [<DURATION_MINUTES>]
-        }
-      },
-      "payment": {
-        "rateType": "NO_FEE",
-        "options": { "online": false, "inPerson": true }
-      },
-      "category": {
-        "id": "<CATEGORY_ID>"
-      }
-    }]
-  }'
-```
-
-### APPOINTMENT-Specific Reminders
-
-- `staffMemberIds` is **required** — uses `resourceId` values, not staff member `id`
-- `schedule.availabilityConstraints.sessionDurations` sets the appointment length
-- Availability is based on the assigned staff member's working hours schedule
-
-Save the `serviceId` from the response: `results[0].item.id` (the created service is directly under `item` — there is no `item.service`). This requires `returnEntity: true` on the request; without it the response carries only `results[0].itemMetadata.id`.
-
----
-
-## Step 4: Summary Message
-
-Provide a summary including:
-
-1. **What was created** — service name, price, duration, assigned staff member
-2. **Assumptions made** — list defaults used (e.g., "I set the duration to 60 minutes since you didn't specify")
-3. **Next steps** — "Click Save to finalize, then set up your availability"
-4. **Offer to adjust** — "Want me to change the price, duration, or staff assignment?"
-
-**Example:**
-
-> I created **"Strategy Consultation"**:
->
-> - **Type**: Appointment (1-on-1)
-> - **Price**: $75 per session
-> - **Duration**: 60 minutes
-> - **Staff**: Assigned to Sarah Johnson
-> - **Category**: Consulting
->
-> I assumed a 60-minute duration since you didn't specify. You can review and adjust the details in the service form.
-
----
-
-## Error Handling
-
-| Error | Cause | Action |
-|---|---|---|
-| 400 "staffMemberIds required" | No staff assigned | Query staff; if none exist, create one via [Bookings Staff Setup](./bookings-staff-setup.md) |
-| 400 "INVALID_PAYMENT_OPTIONS" | Payment misconfigured | Free: `inPerson: true`, `online: false`. Paid: price > 0 |
-| 403 | Permission denied | Inform user they lack permission |
-
----
-
-## Payment Validation Quick Reference
-
-| rateType | `options.online` | `options.inPerson` | Valid? |
-|----------|------------------|-------------------|--------|
-| FIXED    | true             | false             | ✓      |
-| FIXED    | false            | true              | ✓      |
-| FIXED    | true             | true              | ✓      |
-| NO_FEE   | false            | true              | ✓      |
-| NO_FEE   | true             | false             | ✗      |
-| Any      | false            | false             | ✗      |
-
----
-
-## What This Skill Does NOT Cover
-
-- **Schedule/availability setup** — staff working hours need separate configuration. See [Bookings Staff Setup](./bookings-staff-setup.md)
-- **Pricing plans** — memberships and session packs are separate. See [Create and Update Pricing Plans](../pricing-plans/create-and-update-pricing-plans.md)
-- **Service images** — requires Media Manager API (see [create-and-update-booking-services.md](./create-and-update-booking-services.md))
-
----
-
-## API Documentation Reference
-
-- [Bulk Create Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)
-- [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
-- [Query Categories](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/query-categories)
-- [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category)
-- [Query Staff Members](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/query-staff-members)
-- [Create Staff Member](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/create-staff-member)
-- [About Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types)
-- [About Service Payments](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-payments)

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

@@ -1,31 +0,0 @@
----
-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', '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", "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
-
-| User mentions | Type | Recipe |
-|---|---|---|
-| 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, 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
-
-Once the service type is determined, follow the corresponding recipe linked above. Each recipe covers:
-
-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. 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