@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -1,6 +1,6 @@
 ---
 name: "Find Products (Query and Search, Catalog V3)"
-description: Find, search, query, and list products from a Wix Store using Catalog V3 Search Products and Query Products endpoints. Explains when to use each endpoint, correct fields enum values, filtering, sorting, and paging.
+description: Find, search, query, and list products from a Wix Store using Catalog V3 Search Products and Query Products endpoints. Explains when to use each endpoint, correct fields enum values, filtering (including by price), sorting, and paging.
 ---
 
 # RECIPE: Business Recipe – Find Products in a Wix Store (Query and Search, Catalog V3)
@@ -18,11 +18,12 @@ Use **Search Products** for text search and name-based lookup. Use **Query Produ
 | Find products by name or free text | [Search Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products) | Best for user-provided names, keywords, and broad product lookup. |
 | List all products or page through the catalog | [Query Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products) | Supports paging and structured filters on the fields listed below. |
 | Filter by `id`, `slug`, `handle`, dates, or `visible` | [Query Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products) | Best for exact structured criteria. |
+| Filter by price — "products under $20", "between $10 and $50" | [Search Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products) | Query Products has no price filter, so filter server-side here (STEP 1) instead of paging the catalog and comparing amounts yourself. |
 | Need exact name matching after text lookup | [Search Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products) + client-side match | Search by the name text, then match the returned `product.name` in your own code. |
 
-### STEP 1: Search products by name or free text
+### STEP 1: Search products by name, free text, or price
 
-Use Search Products when the user gives a product name, keyword, or other text expression:
+Use Search Products when the user gives a product name, keyword, or other text expression, and for price criteria, which Query Products cannot filter on. Free text goes in `search.search`; price and other structured criteria go in `search.filter`. Send only the part you need:
 
 ```bash
 curl -X POST 'https://www.wixapis.com/stores/v3/products/search' \
@@ -30,11 +31,25 @@ curl -X POST 'https://www.wixapis.com/stores/v3/products/search' \
 -H 'Authorization: <AUTH>' \
 -d '{
   "search": {
-    "expression": "Blue Shirt"
+    "search": { "expression": "Blue Shirt" },
+    "filter": { "actualPriceRange.minValue.amount": { "$lt": 20 } }
   }
 }'
 ```
 
+The response puts the matches in `products`:
+
+```json
+{
+  "products": [
+    { "id": "...", "name": "Blue Shirt", "slug": "blue-shirt" }
+  ],
+  "pagingMetadata": { "count": 1 }
+}
+```
+
+Query Products returns the same envelope.
+
 For exact name matching, search with the user-provided text and then compare the returned `product.name` values in your own code.
 
 ### STEP 2: Query products with structured filters, sorting, or paging
@@ -54,7 +69,9 @@ curl -X POST 'https://www.wixapis.com/stores/v3/products/query' \
 }'
 ```
 
-This returns all products with their default fields (id, name, slug, visible, productType, priceData, stock, media, etc.).
+This returns all products with their default fields, including `inventory` for product-level availability.
+
+Take availability from `inventory`, and look up any other field you need in the Catalog V3 docs rather than carrying a name over from Catalog V1 — the two catalogs do not share a product shape. A name that isn't on the V3 product reads as `undefined` rather than raising, so the request still succeeds and a check against it quietly matches nothing: an availability question answered that way returns an empty list, which reads as "everything is in stock" instead of as a failure.
 
 ### STEP 3: Understanding the `fields` parameter
 
@@ -78,7 +95,7 @@ The `fields` array requests **additional** fields beyond the defaults. It does *
 | `DESCRIPTION`                      | Rich text description        |
 | `DIRECT_CATEGORIES_INFO`           | Direct category info         |
 | `ALL_CATEGORIES_INFO`              | All category info            |
-| `MIN_VARIANT_PRICE_INFO`           | Minimum variant price        |
+| `MIN_PRICE_VARIANT`                | Lowest-priced visible variant |
 | `INFO_SECTION_DESCRIPTION`         | Info section rich content    |
 | `THUMBNAIL`                        | Thumbnail image              |
 | `DIRECT_CATEGORY_IDS`              | Direct category IDs          |
@@ -104,7 +121,7 @@ The `fields` array requests **additional** fields beyond the defaults. It does *
 
 ### STEP 4: Filtering and sorting with Query Products
 
-`QueryProducts` supports filters only on these fields:
+`QueryProducts` supports filters only on these fields. Price is not among them, so answer a price question with Search Products rather than paging the whole catalog and comparing amounts in your own code:
 
 | Field | Supported Filters | Sortable |
 | ----- | ----------------- | -------- |
@@ -186,7 +203,8 @@ Check the response `pagingMetadata` to determine if more pages exist.
 
 - **Variant data is NOT returned** by Query Products. To get variant details, use [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product) for individual products.
 - **Non-visible products** require the `SCOPE.STORES.PRODUCT_READ_ADMIN` permission.
-- Default fields include: `id`, `name`, `slug`, `visible`, `productType`, `priceData`, `stock`, `media`, `createdDate`, `updatedDate`.
+- Default fields include: `id`, `name`, `slug`, `visible`, `productType`, `inventory`, `media`, `createdDate`, `updatedDate`.
+- **Availability is not in STEP 4's filterable set.** To list out-of-stock products, query the catalog — paging until `pagingMetadata` reports no more results — and select on each returned product's `inventory` availability status in your own code, rather than putting it in `query.filter`.
 - The `fields` parameter adds fields **on top of** the defaults — you never need to request `id` or `name` explicitly.
 
 ## Conclusion

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

@@ -0,0 +1,65 @@
+---
+name: "Stores Dashboard Navigation"
+description: "Builds direct links to Wix Stores and eCommerce dashboard pages on manage.wix.com — products list, edit a specific product, categories, inventory, orders list, a specific order, abandoned checkouts, gift cards, shipping and tax settings. Pairs each main Stores/eCommerce entity 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."
+---
+
+# Stores Dashboard Navigation
+
+Build direct links into the store pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+Store pages are split across **two apps** with two URL namespaces:
+
+- **Wix Stores** (`215238eb-22a5-4c36-9e7b-e7c08025e04e`) — catalog: products, categories, inventory. Routes under `wix-stores/`.
+- **Checkout & Orders / eCommerce platform** (`1380b703-ce81-ff05-f115-39571d94dfcd`) — orders, checkout, gift cards, shipping, tax. Routes under `ecom-platform/`.
+
+Older `store/...` links (e.g. `store/orders`, `store/inventory`) redirect to the current routes.
+
+## Catalog Pages (Wix Stores)
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Products list | `wix-stores/products` | All products |
+| New product | `wix-stores/products/new-product` | Create a product |
+| Edit product | `wix-stores/products/product/{productId}` | A specific product |
+| Categories | `wix-stores/categories/list` | Product categories |
+| Inventory | `wix-stores/inventory` | Stock levels per variant |
+| Import products | `wix-stores/import-products` | CSV import |
+| Back in stock | `wix-stores/back-in-stock` | Back-in-stock notification requests |
+| Store settings | `wix-stores/settings` | Stores-level settings |
+
+Sales-channel pages (Google, Meta, Amazon, eBay, Pinterest, PayPal) live at `wix-stores/channel/{channel}`, e.g. `wix-stores/channel/google`.
+
+## Orders & Checkout Pages (eCommerce)
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Orders list | `ecom-platform/orders-list` | All orders |
+| Order details | `ecom-platform/order-details/{orderId}` | A specific order |
+| Create manual order | `ecom-platform/orders/create-manual` | Draft/manual orders |
+| Abandoned checkouts | `ecom-platform/abandoned-checkouts` | Abandoned cart recovery |
+| Gift cards | `ecom-platform/gift-cards` | Gift card products |
+| Gift card sales | `ecom-platform/gift-cards/sales` | Sold gift cards |
+| Shipping | `ecom-platform/delivery-profile` | Shipping rates and regions (delivery profiles) |
+| Tax | `ecom-platform/tax` | Tax rules |
+| Tax exemptions | `ecom-platform/tax-exemptions` | Exempt customer groups |
+| Checkout settings | `ecom-platform/checkout-settings` | Checkout configuration |
+
+## 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. Dashboard routes are the same whether the site's catalog is V1 or V3.
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Product (Catalog V3) | `POST /stores/v3/products/search` · `POST /stores/v3/products/query` | `wix-stores/products/product/{productId}` (edit) or `wix-stores/products` (list) |
+| Product (Catalog V1) | `POST /stores-reader/v1/products/query` | same as above |
+| Category | Categories API (`/categories/v1/categories`) | `wix-stores/categories/list` |
+| Inventory item (V3) | `POST /stores/v3/inventory-items/query` | `wix-stores/inventory` |
+| Order | `POST /ecom/v1/orders/search` · `GET /ecom/v1/orders/{orderId}` | `ecom-platform/order-details/{orderId}` |
+| Abandoned checkout | Abandoned Checkouts API (`/ecom/v1/abandoned-checkouts`) | `ecom-platform/abandoned-checkouts` |
+
+Example — after creating a product, hand back its edit link:
+
+```
+Created "Organic Cotton Tee".
+Manage it here: https://manage.wix.com/dashboard/{metaSiteId}/wix-stores/products/product/{productId}
+```

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

@@ -1,18 +1,19 @@
 ---
 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, and revision-based updates to prevent conflicts.
+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.
 ---
 **RECIPE**: Business Recipe - Updating a Wix Store Product (Catalog V3)
 
-Use this recipe to update an existing Catalog V3 product: description, media, options, variants, prices, or stock-related inventory records.
+Use this recipe to update an existing Catalog V3 product: storefront visibility, description, media, options, variants, prices, or stock-related inventory records.
 
 ## Before Any Product Update
 
 Every Catalog V3 product update is revision-based:
 
 - If the user gives a product name instead of a product ID, use [Search Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products) and choose the exact product name match.
-- Use [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product) to retrieve the current product and `product.revision`.
+- 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.
 
 ### Find the product by name
@@ -28,7 +29,7 @@ curl -X POST "https://www.wixapis.com/stores/v3/products/search" \
   }'
 ```
 
-For product-name lookup, prefer Search Products before retrieving the product by ID.
+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.
 
 ### Get the current revision
 
@@ -39,6 +40,32 @@ curl -X GET "https://www.wixapis.com/stores/v3/products/{productId}" \
 
 ## Common Update Patterns
 
+### Hide or Show a Product
+
+"Hide this product", "make it not show in my store", "unhide it", "put it back in the store" are all product-level visibility changes. Set the `visible` boolean on the product in an Update Product PATCH. Do not delete the product, and do not change variant visibility to hide the product.
+
+```bash
+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}",
+      "visible": false
+    }
+  }'
+```
+
+Send `"visible": true` to show it again. Nothing else needs to be in the body — `name`, `options`, `variantsInfo` and the other top-level fields you omit are left unchanged. Confirm the result from `product.visible` in the response.
+
+Visibility behaviour to report back accurately:
+
+- `visible` defaults to `true`.
+- For a product **without** options, updating `product.visible` automatically updates the default variant's `visible` to match.
+- 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
 
 For a normal user request like "set the product description to X", use `plainDescription` with valid HTML. The API converts it to rich content.
@@ -189,7 +216,7 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
-When updating existing variants, include each existing variant `id`. If no GUID is passed, a variant is created with a new GUID.
+When updating existing variants, include each existing variant `id`. If no GUID is passed, a variant is created with a new GUID. Each variant object is replaced whole rather than merged, so carry over the fields you are not changing: rebuilding a variant from just its `id` plus the field you want to set drops everything else and is rejected on the first required field it lost (`price must not be empty`). Start from the variant as returned by Get Product and override only what the user asked to change.
 
 ### Convert a Simple Product to Color Variants
 
@@ -272,6 +299,8 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
 
 ### Update Variant Price Only
 
+Read `{existingVariantId}` off the Get Product response; a Search or Query Products result does not carry it.
+
 ```bash
 curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   -H "Content-Type: application/json" \
@@ -298,11 +327,12 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
 
 ## Important Notes
 
+- A request to hide a product is a `visible: false` update on the product, never a Delete Product call and never a variant-only change.
 - To update array fields like `options`, `modifiers`, `variantsInfo.variants`, and any others, pass the entire existing array. Passing only the changed item overwrites the whole array.
 - To update `variantsInfo.variants`, also pass `options`, and vice versa. Variants and options are mutually dependent and must stay aligned.
 - When converting a simple product to an optioned product, rebuild the variants list so every variant has `choices`; do not keep an existing choice-less default variant unchanged.
 - Always include `choicesSettings` with the complete list of choices when updating a product with options.
-- Use `optionChoiceNames` rather than `optionChoiceIds` in variants for more reliable updates.
+- Use `optionChoiceNames` rather than `optionChoiceIds` in variants for more reliable updates. Reading them back is not symmetric: Get Product returns each variant's `choices` with `optionChoiceIds` only, and fills in `optionChoiceNames` just when the request's `fields` array includes `"VARIANT_OPTION_CHOICE_NAMES"`. So to find the variant for a named choice such as `Large`, either pass that field and match on the name, or take the choice GUID from `options[].choicesSettings.choices[].choiceId` and match it against `variants[].choices[].optionChoiceIds.choiceId`. Matching on a name the response never carried raises nothing — it just selects no variant.
 - Include the `renderType` in `optionChoiceNames`.
 
 ## Error Message Reference
@@ -314,5 +344,7 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
 | `Expected an object` for `description` | Sent `description` as a string | Use `plainDescription` for HTML strings, or send `description` as Rich Content |
 | `choicesSettings must not be empty` | Missing choices array | Include full `choicesSettings.choices` array |
 | `Missing product option choices` | Variant references non-existent option | Use `optionChoiceNames` with exact option and choice names |
-| `price must not be empty` | A variant was created or replaced without a price | Include `price.actualPrice.amount` on every new variant |
+| `price must not be empty` | A variant was sent without a price — including an existing variant rebuilt from only its `id` and the field being changed | Carry `price.actualPrice.amount` on every variant you send, not just new ones; copy it from the Get Product response for variants you are not repricing |
+| `variantsInfo is invalid: variants has size 0, expected 1 or more` | Variants were read from a Search or Query Products response, which does not return them | Re-read the product with Get Product and send its `variantsInfo.variants` |
 | `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 |

package/skills/wix-replatform/.publish-manifest.json

@@ -0,0 +1,8 @@
+{
+  "bundle": "replatform",
+  "version": "1.2.0",
+  "sourceRepo": "wix-private/replatform",
+  "sourcePath": "skills/",
+  "sourceCommit": "9aaaebd",
+  "publishedAt": "2026-08-05T13:55:48Z"
+}