@wix/agent-skills 1.0.0

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

@@ -0,0 +1,194 @@
+---
+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.
+---
+
+# RECIPE: Business Recipe – Find Products in a Wix Store (Query and Search, Catalog V3)
+
+Find products in a Wix store using the Catalog V3 Search Products and Query Products APIs.
+
+## Article: How to Find Products
+
+### STEP 0: Choose the right product lookup method
+
+Use **Search Products** for text search and name-based lookup. Use **Query Products** for structured filtering, sorting, paging, and listing products.
+
+| Need | Endpoint | Notes |
+| ---- | -------- | ----- |
+| 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. |
+| 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
+
+Use Search Products when the user gives a product name, keyword, or other text expression:
+
+```bash
+curl -X POST 'https://www.wixapis.com/stores/v3/products/search' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "search": {
+    "expression": "Blue Shirt"
+  }
+}'
+```
+
+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
+
+Use the **POST** [Query Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products) endpoint to query products. The endpoint returns up to 100 products per request.
+
+**Endpoint:** `POST https://www.wixapis.com/stores/v3/products/query`
+
+**Basic query (all products, default fields):**
+
+```bash
+curl -X POST 'https://www.wixapis.com/stores/v3/products/query' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "query": {}
+}'
+```
+
+This returns all products with their default fields (id, name, slug, visible, productType, priceData, stock, media, etc.).
+
+### STEP 3: Understanding the `fields` parameter
+
+The `fields` array requests **additional** fields beyond the defaults. It does **NOT** accept property names like `"name"` or `"id"`.
+
+**⚠️ CRITICAL: Valid `fields` enum values:**
+
+| Enum Value                         | Description                  |
+| ---------------------------------- | ---------------------------- |
+| `URL`                              | Product page URL             |
+| `CURRENCY`                         | Currency information         |
+| `INFO_SECTION`                     | Info sections (rich content) |
+| `MERCHANT_DATA`                    | Merchant-specific data       |
+| `PLAIN_DESCRIPTION`                | Plain text description       |
+| `INFO_SECTION_PLAIN_DESCRIPTION`   | Info section plain text      |
+| `SUBSCRIPTION_PRICES_INFO`         | Subscription pricing         |
+| `BREADCRUMBS_INFO`                 | Category breadcrumbs         |
+| `WEIGHT_MEASUREMENT_UNIT_INFO`     | Weight unit info             |
+| `VARIANT_OPTION_CHOICE_NAMES`      | Variant option choice names  |
+| `MEDIA_ITEMS_INFO`                 | Additional media items       |
+| `DESCRIPTION`                      | Rich text description        |
+| `DIRECT_CATEGORIES_INFO`           | Direct category info         |
+| `ALL_CATEGORIES_INFO`              | All category info            |
+| `MIN_VARIANT_PRICE_INFO`           | Minimum variant price        |
+| `INFO_SECTION_DESCRIPTION`         | Info section rich content    |
+| `THUMBNAIL`                        | Thumbnail image              |
+| `DIRECT_CATEGORY_IDS`              | Direct category IDs          |
+| `PRODUCT_CHOICES_MEDIA_REFERENCES` | Choice-specific media        |
+
+**WRONG – these are NOT valid field values:**
+
+```json
+"fields": ["id", "name", "slug", "visible", "priceData"]
+```
+
+**CORRECT – use enum constants or leave empty for defaults:**
+
+```json
+"fields": []
+```
+
+**CORRECT – requesting additional fields:**
+
+```json
+"fields": ["DESCRIPTION", "URL", "ALL_CATEGORIES_INFO"]
+```
+
+### STEP 4: Filtering and sorting with Query Products
+
+`QueryProducts` supports filters only on these fields:
+
+| Field | Supported Filters | Sortable |
+| ----- | ----------------- | -------- |
+| `id` | `$eq`, `$ne`, `$exists`, `$in`, `$startsWith` | No |
+| `handle` | `$eq`, `$ne`, `$exists`, `$in`, `$startsWith` | No |
+| `options.id` | `$isEmpty`, `$hasAll`, `$hasSome` | No |
+| `slug` | `$eq`, `$ne`, `$exists`, `$in`, `$startsWith` | Yes |
+| `createdDate` | `$eq`, `$ne`, `$exists`, `$in`, `$lt`, `$lte`, `$gt`, `$gte` | Yes |
+| `updatedDate` | `$eq`, `$ne`, `$exists`, `$in`, `$lt`, `$lte`, `$gt`, `$gte` | Yes |
+| `visible` | `$eq`, `$ne`, `$exists`, `$in` | Yes |
+
+**Query with filter and sort:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/stores/v3/products/query' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "fields": [],
+  "query": {
+    "filter": {
+      "visible": true
+    },
+    "sort": [
+      {
+        "field_name": "createdDate",
+        "order": "ASC"
+      }
+    ],
+    "paging": {
+      "limit": 50,
+      "offset": 0
+    }
+  }
+}'
+```
+
+**Filter by product IDs:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/stores/v3/products/query' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "fields": [],
+  "query": {
+    "filter": {
+      "id": {
+        "$in": [
+          "product-id-1",
+          "product-id-2"
+        ]
+      }
+    }
+  }
+}'
+```
+
+### STEP 5: Handling pagination
+
+When there are more products than the page limit, use cursor-based or offset-based paging:
+
+```json
+{
+  "query": {
+    "paging": {
+      "limit": 100,
+      "offset": 0
+    }
+  }
+}
+```
+
+Check the response `pagingMetadata` to determine if more pages exist.
+
+---
+
+## Important Notes
+
+- **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`.
+- The `fields` parameter adds fields **on top of** the defaults — you never need to request `id` or `name` explicitly.
+
+## Conclusion
+
+To find products by name or free text, use `POST https://www.wixapis.com/stores/v3/products/search`. To list, page, sort, or structurally filter products, use `POST https://www.wixapis.com/stores/v3/products/query`. Use `fields: []` for defaults, or pass valid enum values like `DESCRIPTION`, `URL`, `ALL_CATEGORIES_INFO` for additional data. Never pass property names as field values.

package/skills/wix-manage/references/stores/query-products-catalog-v1.md

@@ -0,0 +1,80 @@
+---
+name: "Query Products (Catalog V1)"
+description: Query and list products from a Wix Store using the Catalog V1 Query Products endpoint. Use this recipe when the site's catalog version is CATALOG_V1. Covers basic queries, filtering, sorting, and paging.
+---
+# RECIPE: Business Recipe - Query Products (Catalog V1)
+
+## STEP 1: Query Products
+
+Use `POST https://www.wixapis.com/stores-reader/v1/products/query` to query products from a V1 store.
+
+**Basic query (all products):**
+
+```bash
+curl -X POST 'https://www.wixapis.com/stores-reader/v1/products/query' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "query": {}
+}'
+```
+
+---
+
+## STEP 2: Filtering and Sorting
+
+> **CRITICAL:** In V1, `filter` and `sort` are **JSON-encoded strings**, not objects — unlike V3 where they are plain objects.
+
+**Query with filter and sort:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/stores-reader/v1/products/query' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "query": {
+    "filter": "{\"visible\": true}",
+    "sort": "[{\"fieldName\": \"name\", \"order\": \"ASC\"}]",
+    "paging": {
+      "limit": 50,
+      "offset": 0
+    }
+  }
+}'
+```
+
+**Query by product IDs:**
+
+```bash
+curl -X POST 'https://www.wixapis.com/stores-reader/v1/products/query' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+  "query": {
+    "filter": "{\"id\": {\"$in\": [\"product-id-1\", \"product-id-2\"]}}"
+  }
+}'
+```
+
+---
+
+## Key Differences from V3
+
+| Feature | Catalog V1 | Catalog V3 |
+|---|---|---|
+| Query endpoint | `POST /stores-reader/v1/products/query` | `POST /stores/v3/products/query` |
+| Filter/sort | JSON-encoded strings | Plain objects |
+| Additional fields | Not applicable | Enum values like `DESCRIPTION`, `URL` |
+
+---
+
+## Important Notes
+
+- **Never use `/stores/v3/` endpoints on a CATALOG_V1 site** — they return `428 Precondition Required`.
+- Check the site's catalog version in dynamic context before choosing endpoints.
+- To create products on a V1 site, see [Create Product (Catalog V1)](create-product-catalog-v1.md).
+
+## References
+
+- [V1 Query Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/query-products)
+- [Catalog Versioning Overview](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction)

package/skills/wix-manage/references/stores/setup-online-store-catalog-v3.md

@@ -0,0 +1,99 @@
+---
+name: "Setup Online Store (Catalog V3)"
+description: Initializes a Stores catalog with Catalog V3 Products API, bulk products endpoint, and Categories API. Covers product creation, option configuration, variant management, and category assignment.
+---
+**RECIPE**: Business Recipe – Initial Setup for a Wix Online Store (Catalog V3)
+
+A concise checklist for preparing any new Wix site that uses the Online Stores app with Catalog V3.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial catalog setup.
+
+---
+
+## Article: Steps for Setting Up a Wix Online Store
+**YOU MUST** Complete all the following steps **in the given order** (1 -5) without skipping any and **without requiring additional user input**.
+**YOU MUST** remind yourself as many times as needed throughout the process that you most complete all the steps and not stop at all in the middle.
+
+
+**⚠️ CRITICAL ORDER REQUIREMENT: You MUST start with creating products FIRST (Steps 1-2), then categories (Steps 3-5). Categories API might take some time to be fully available after Stores installation, so always create products before attempting category operations.**
+
+### STEP 1: Confirm Catalog V3 & Stick to V3 APIs
+
+- **Check if the site uses Catalog V3.**
+ This can be done using the [Get Catalog Version](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/get-catalog-version) endpoint.
+ path: `https://www.wixapis.com/stores/v3/provision/version`
+
+
+- From this point forward, as long as the result is V3, use only Catalog V3 REST endpoints.
+All API calls should be directed to endpoints starting with `/stores/v3/....` Do not mix V3 calls with earlier versions.
+
+
+- Exception for Categories:
+The Categories API is an exception. It uses a v1 endpoint, as it replaces the older Collections API. For example, to create a category in V3, use the following endpoint:
+`https://www.wixapis.com/categories/v1/categories`
+
+
+### STEP 2: Create 5 new products based on the format specified in the Bulk Create Products with Options recipe (4 in stock, 1 out of stock)
+1. First *YOU MUST* pull up the [Bulk Create Wix Store Products with Options](bulk-create-products-with-options.md) recipe to understand the exact format required for creating products.
+2. Create 5 products according to this format using bulk creation (use a single bulk request). 4 of the created products **MUST** have ALL there variants in-stock, and the last (5th) product **MUST** have all its variants be out-of-stock.
+3. **Make sure** to add in image (using media) using  a url from the web that matches each product.
+4. **YOU MUST** use the price formatting as seen in the example, meaning using actualPrice and compareAtPrice.
+5. **ALL** products **MUST** be created **EXACTLY** from the same format as the full example in the Bulk Create Wix Store Products with Options recipe. **ONLY** information within the strings of the given fields may differ based on the products.
+
+
+**⚠️ CRITICAL: EXACT FORMAT REQUIREMENTS**
+**YOU MUST** use the following recipe to create ALL products with the EXACT same format:
+- **Bulk Create Wix Store Products with Options**
+ [Recipe: Bulk Create Products with Options](bulk-create-products-with-options.md)
+
+
+### STEP 3: Prepare Three Store Categories
+1. Determine how many categories the user requested.
+2. If fewer than **3** are provided, create additional categories until the total equals **3** which are relevant for the type of store.
+3. Examples for different types of stores:
+  - **Book store** → Drama, Kids, Sci-Fi
+  - **Fashion** → Men, Women, Kids
+  - **Other industries** → any logical grouping that fits the catalog.
+4. Use the Categories API to create each category. **YOU MUST USE** the endpoint: [Create Category](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/create-category) based on the example below.
+**⚠️ CRITICAL: Use correct endpoint `/categories/v1/bulk/categories/{categoryId}/add-items` with `catalogItemId`, `appId: "215238eb-22a5-4c36-9e7b-e7c08025e04e"`, and `treeReference` object.**
+When calling the endpoint, make sure the request body includes a top-level `treeReference` field. It must **not** be nested inside the `category` object.
+
+Use the following example format:
+
+```json
+{
+  "category": {
+    "name": "Drinkware",
+    "description": "The Drinkware category includes a wide range of containers designed for holding beverages",
+    "visible": true
+  },
+  "treeReference": {
+    "appNamespace": "@wix/stores",
+    "treeKey": null
+  }
+}
+```
+
+
+### STEP 4: Add Each Product to a Category
+1. **YOU MUST** add each existing product to at least one category that most makes sense.
+2. First acquire the product's ids to use for this action.
+3. Then adding a product to a category **MUST** be done using the Category API, specifically [Bulk Add Items To Category](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-add-items-to-category), where products are referred to as items. This endpoint enables adding multiple products at once to a category.
+
+**⚠️ CRITICAL: Use correct endpoint `/categories/v1/bulk/categories/{categoryId}/add-items` with `catalogItemId`, `appId: "215238eb-22a5-4c36-9e7b-e7c08025e04e"`, and `treeReference` object.**
+**Make Sure** you pass the treeReference correctly at the same level as "items".
+
+
+### STEP 5: Ensure Each Product was Added to a Category
+1. **YOU MUST** ensure that each product is connected to at least one category.
+2. **You MUST** do this by using the [List Items In Category](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/list-items-in-category) for EVERY Category (for example: 3 required api calls for 3 categories). If the list of items is empty, it means that the product was not added to that category and **YOU MUST** repeat step 4.
+The path for this endpoint in REST is: `https://www.wixapis.com/categories/v1/categories/{categoryId}/list-items`
+3. When calling the endpoint, make sure the request body includes a top-level `treeReference` field. It must **not** be nested inside the `category` object.
+
+---
+
+## Conclusion
+Following these steps **in order** guarantees the creation flow for new V3 Wix Online Store sites:
+- Contains exactly **3** categories
+- Contains exactly **5** products (unless the user explicitly requests fewer)
+- Each product is connected to at least one category.
+- All products follow the correct Catalog V3 API format as specified in the referenced recipe.

package/skills/wix-manage/references/stores/update-product-pre-order.md

@@ -0,0 +1,213 @@
+---
+name: "Update Product Pre-Order (Catalog V3)"
+description: Manages pre-order settings for product variants using V3 Inventory API. Covers enabling/disabling pre-orders, setting messages, configuring limits, and handling trackQuantity requirements.
+---
+# Update Product Pre-Order Information (Catalog V3)
+
+This recipe outlines the steps to manage pre-orders for product variants, including enabling/disabling pre-orders, setting messages, and configuring limits.
+
+## Prerequisites
+
+- Wix Stores app installed
+- Product with variants already created
+- API access with stores permissions
+
+## Required APIs
+
+- **Products Search API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products)
+- **Query Inventory Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/query-inventory-items)
+- **Bulk Update Inventory Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/bulk-update-inventory-items)
+- **Update Inventory Item API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/update-inventory-item)
+
+---
+
+## Step 1: Find the Product and Get Variant Information
+
+### 1.1 Search for the Product
+
+**Endpoint**: `POST https://www.wixapis.com/stores/v3/products/search`
+
+```json
+{
+  "search": {
+    "expression": "Product Name"
+  }
+}
+```
+
+### 1.2 Query Inventory Items for Variant Details
+
+Use the `productId` from the search to get variant information:
+
+**Endpoint**: `POST https://www.wixapis.com/stores/v3/inventory-items/query`
+
+```json
+{
+  "query": {
+    "filter": {
+      "productId": {
+        "$in": ["<PRODUCT_ID>"]
+      }
+    }
+  }
+}
+```
+
+The response includes:
+- `product.variantName` - identifies each variant
+- `inventoryItemId` - needed for updates
+- `revision` - required for update operations
+- `locationId` - inventory location
+- Current `preorderInfo` settings
+
+### IMPORTANT NOTES:
+- I MUST get user input on which specific variant(s) to update
+- I MUST NEVER update all variants without explicit user selection
+- I MUST ask the user whether to enable or disable pre-orders for each variant
+- If enabling, I MUST get the pre-order message from the user
+- If setting a pre-order limit, I MUST ensure `trackQuantity: true` is set
+
+---
+
+## Step 2: Update Pre-Order Information
+
+### Method A: Bulk Update (PREFERRED for multiple variants)
+
+Use when applying the same pre-order settings to multiple variants:
+
+**Endpoint**: `POST https://www.wixapis.com/stores/v3/bulk/inventory-items/update`
+
+**Request Body (Enable Pre-Order)**:
+```json
+{
+  "inventoryItems": [
+    {
+      "inventoryItem": {
+        "id": "<inventoryItemId_variant1>",
+        "revision": "<revision_as_integer>",
+        "preorderInfo": {
+          "enabled": true,
+          "message": "Available for pre-order! Ships in 2 weeks."
+        }
+      }
+    },
+    {
+      "inventoryItem": {
+        "id": "<inventoryItemId_variant2>",
+        "revision": "<revision_as_integer>",
+        "preorderInfo": {
+          "enabled": true,
+          "message": "Available for pre-order! Ships in 2 weeks."
+        }
+      }
+    }
+  ],
+  "returnEntity": true,
+  "reason": "MANUAL"
+}
+```
+
+**Request Body (With Pre-Order Limit)**:
+```json
+{
+  "inventoryItems": [
+    {
+      "inventoryItem": {
+        "id": "<inventoryItemId>",
+        "revision": "<revision_as_integer>",
+        "trackQuantity": true,
+        "quantity": 100,
+        "preorderInfo": {
+          "enabled": true,
+          "message": "Pre-order now!",
+          "limit": 50
+        }
+      }
+    }
+  ],
+  "returnEntity": true,
+  "reason": "MANUAL"
+}
+```
+
+### IMPORTANT NOTES:
+- Pre-order limits ONLY work when `trackQuantity: true`
+- If variant wasn't tracking quantity, I MUST ask user for initial quantity
+- The `revision` field is required and must be an integer
+
+---
+
+### Method B: Individual Update (Single variant or unique settings)
+
+**Endpoint**: `PATCH https://www.wixapis.com/stores/v3/inventory-items/{inventoryItemId}`
+
+**Request Body (Enable Pre-Order)**:
+```json
+{
+  "inventoryItem": {
+    "id": "<inventoryItemId>",
+    "revision": "<revision_as_integer>",
+    "preorderInfo": {
+      "enabled": true,
+      "message": "Coming soon! Pre-order today."
+    }
+  },
+  "reason": "MANUAL"
+}
+```
+
+**Request Body (Disable Pre-Order)**:
+```json
+{
+  "inventoryItem": {
+    "id": "<inventoryItemId>",
+    "revision": "<revision_as_integer>",
+    "preorderInfo": {
+      "enabled": false,
+      "limit": null
+    }
+  },
+  "reason": "MANUAL"
+}
+```
+
+---
+
+## Pre-Order Limit Behavior
+
+When you set a `preorderInfo.limit`:
+- It specifies how many units can be pre-ordered **after stock reaches zero**
+- Example: 10 in stock + limit of 50 = customers can order up to 60 total (10 regular + 50 pre-order)
+
+### CRITICAL: Enabling Quantity Tracking
+
+If setting a limit on a variant that wasn't tracking quantity:
+
+1. **Inform the user**: "`trackQuantity` will be enabled for this variant"
+2. **Ask for initial quantity**: "What initial stock quantity should I set?"
+3. **Include both in update**:
+```json
+{
+  "inventoryItem": {
+    "id": "<inventoryItemId>",
+    "revision": "<revision_as_integer>",
+    "trackQuantity": true,
+    "quantity": "<USER_PROVIDED_QUANTITY>",
+    "preorderInfo": {
+      "enabled": true,
+      "message": "Pre-order message",
+      "limit": 50
+    }
+  },
+  "reason": "MANUAL"
+}
+```
+
+---
+
+## Next Steps
+
+After updating pre-order settings:
+- Confirm the changes with the user
+- Offer to update other products or variants
+- Consider updating product descriptions to mention pre-order availability