@wix/agent-skills 1.5.0 → 1.7.0

package/skills/wix-manage/references/ecommerce/setup-discount-rules.md

@@ -1,6 +1,6 @@
 ---
 name: "Setup: Discount Rules"
-description: Configures automatic discount rules using the eCommerce Discount Rules API. Covers percentage and fixed-amount discounts, scope targeting (catalog-wide, specific collections, or individual products), and scheduling active periods.
+description: Configures automatic discount rules using the eCommerce Discount Rules API. Covers percentage and fixed-amount discounts, scope targeting (catalog-wide, specific collections, or individual products), scheduling active periods, and the find-by-name + update pattern.
 layer: config
 ---
 # Setup Discount Rules
@@ -20,23 +20,66 @@ layer: config
 
 ---
 
-## Step 1: Query existing discount rules
+## Critical: `discounts` structure
+
+**The API always returns the full normalized structure.** Never assume a simplified form. Each discount entry looks like:
+
+```json
+{
+  "targetType": "SPECIFIC_ITEMS",
+  "specificItemsInfo": {
+    "scopes": [
+      {
+        "id": "all_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+        "type": "CATALOG_ITEM",
+        "catalogItemFilter": {
+          "catalogAppId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
+        }
+      }
+    ]
+  },
+  "discount": {
+    "discountType": "PERCENTAGE",
+    "percentage": 20
+  }
+}
+```
+
+When updating a rule, always use the `discounts` array as returned from the query/get, modifying only the specific fields you need. **Do not reconstruct from scratch unless creating a new rule.**
+
+---
 
-Before creating new rules, check what already exists to avoid conflicts.
+## Step 1: Query existing discount rules
 
 **Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
 
-**Request**:
+> **Paging**: This API uses **cursor paging** (`cursorPaging`), not offset paging. Using `paging` instead of `cursorPaging` will fail.
+
+**Request** — list all rules:
 ```json
 {
   "query": {
-    "paging": {
+    "cursorPaging": {
       "limit": 100
     }
   }
 }
 ```
 
+**Request** — find by name (exact match):
+```json
+{
+  "query": {
+    "filter": {
+      "name": { "$eq": "Summer Sale" }
+    },
+    "cursorPaging": { "limit": 10 }
+  }
+}
+```
+
+Filterable fields: `id`, `name`, `active`, `revision`, `created_date`, `updated_date`, `active_time_info.start`, `active_time_info.end`
+
 **Response**:
 ```json
 {
@@ -52,20 +95,28 @@ Before creating new rules, check what already exists to avoid conflicts.
       },
       "discounts": [
         {
+          "targetType": "SPECIFIC_ITEMS",
+          "specificItemsInfo": {
+            "scopes": [
+              {
+                "id": "all_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+                "type": "CATALOG_ITEM",
+                "catalogItemFilter": {
+                  "catalogAppId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
+                }
+              }
+            ]
+          },
           "discount": {
             "discountType": "PERCENTAGE",
             "percentage": 10
-          },
-          "scope": {
-            "id": "catalog",
-            "type": "CATALOG"
           }
         }
       ]
     }
   ],
   "pagingMetadata": {
-    "count": 1,
+    "cursors": {},
     "hasNext": false
   }
 }
@@ -91,44 +142,27 @@ Note existing rules and their scopes to avoid stacking conflicts.
     },
     "discounts": [
       {
-        "discount": {
-          "discountType": "PERCENTAGE",
-          "percentage": 20
+        "targetType": "SPECIFIC_ITEMS",
+        "specificItemsInfo": {
+          "scopes": [
+            {
+              "id": "all_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+              "type": "CATALOG_ITEM",
+              "catalogItemFilter": {
+                "catalogAppId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
+              }
+            }
+          ]
         },
-        "scope": {
-          "id": "catalog",
-          "type": "CATALOG"
-        }
-      }
-    ]
-  }
-}
-```
-
-**Response**:
-```json
-{
-  "discountRule": {
-    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
-    "revision": "1",
-    "name": "Flash Sale 20% Off",
-    "active": true,
-    "activeTimeInfo": {
-      "start": "2026-05-01T00:00:00.000Z",
-      "end": "2026-05-03T23:59:59.000Z"
-    },
-    "discounts": [
-      {
         "discount": {
           "discountType": "PERCENTAGE",
           "percentage": 20
-        },
-        "scope": {
-          "id": "catalog",
-          "type": "CATALOG"
         }
       }
-    ]
+    ],
+    "settings": {
+      "appliesTo": "ALL_ITEMS"
+    }
   }
 }
 ```
@@ -141,16 +175,30 @@ Note existing rules and their scopes to avoid stacking conflicts.
     "active": true,
     "discounts": [
       {
+        "targetType": "SPECIFIC_ITEMS",
+        "specificItemsInfo": {
+          "scopes": [
+            {
+              "id": "collections_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+              "type": "CUSTOM_FILTER",
+              "customFilter": {
+                "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+                "params": {
+                  "collectionIds": ["collection-uuid-here"]
+                }
+              }
+            }
+          ]
+        },
         "discount": {
           "discountType": "PERCENTAGE",
           "percentage": 15
-        },
-        "scope": {
-          "id": "collection-uuid-here",
-          "type": "COLLECTION"
         }
       }
-    ]
+    ],
+    "settings": {
+      "appliesTo": "ALL_ITEMS"
+    }
   }
 }
 ```
@@ -167,16 +215,28 @@ Note existing rules and their scopes to avoid stacking conflicts.
     "active": true,
     "discounts": [
       {
+        "targetType": "SPECIFIC_ITEMS",
+        "specificItemsInfo": {
+          "scopes": [
+            {
+              "id": "specific_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+              "type": "CATALOG_ITEM",
+              "catalogItemFilter": {
+                "catalogAppId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+                "catalogItemIds": ["product-uuid-here"]
+              }
+            }
+          ]
+        },
         "discount": {
           "discountType": "FIXED_AMOUNT",
           "fixedAmount": "5.00"
-        },
-        "scope": {
-          "id": "product-uuid-here",
-          "type": "SPECIFIC_PRODUCTS"
         }
       }
-    ]
+    ],
+    "settings": {
+      "appliesTo": "ALL_ITEMS"
+    }
   }
 }
 ```
@@ -185,36 +245,107 @@ Note existing rules and their scopes to avoid stacking conflicts.
 
 ## Step 4: Update a discount rule
 
-**Endpoint**: `PATCH https://www.wixapis.com/ecom/v1/discount-rules/{discountRuleId}`
+Always fetch the rule first (via Get or Query), then modify only the fields you need. The `mask` field tells the API which fields to update — omit it to replace all writable fields.
 
-**Request**:
+**Endpoint**: `PATCH https://www.wixapis.com/ecom/v1/discount-rules/{discountRule.id}`
+
+**Required**: `discountRule.id`, `discountRule.revision` (must match current revision)
+
+**Request** — change percentage on an existing rule (full discounts replacement):
 ```json
 {
   "discountRule": {
-    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "revision": "1",
-    "name": "Extended Flash Sale 25% Off",
     "discounts": [
       {
+        "targetType": "SPECIFIC_ITEMS",
+        "specificItemsInfo": {
+          "scopes": [
+            {
+              "id": "all_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+              "type": "CATALOG_ITEM",
+              "catalogItemFilter": {
+                "catalogAppId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
+              }
+            }
+          ]
+        },
         "discount": {
           "discountType": "PERCENTAGE",
           "percentage": 25
-        },
-        "scope": {
-          "id": "catalog",
-          "type": "CATALOG"
         }
       }
     ]
+  },
+  "mask": { "paths": ["discounts"] }
+}
+```
+
+**Request** — change only `active` status (field mask for partial update):
+```json
+{
+  "discountRule": {
+    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "revision": "2",
+    "active": false
+  },
+  "mask": { "paths": ["active"] }
+}
+```
+
+---
+
+## Step 5: Find by name and update (complete pattern)
+
+The safe pattern for "find a rule by name and update its percentage":
+
+1. Query with name filter → get the rule's `id`, `revision`, and `discounts` array
+2. Modify only the `discount.percentage` inside each discount entry, keeping all other fields intact
+3. PATCH with the modified `discounts` and `mask: { paths: ["discounts"] }`
+
+**Step 5a — Query by name**:
+```json
+POST https://www.wixapis.com/ecom/v1/discount-rules/query
+{
+  "query": {
+    "filter": { "name": { "$eq": "My Rule Name" } },
+    "cursorPaging": { "limit": 1 }
   }
 }
 ```
 
-The `revision` field is required and must match the current revision.
+Extract from response: `discountRules[0].id`, `discountRules[0].revision`, `discountRules[0].discounts`
+
+**Step 5b — Update percentage** (modify the returned discounts in-place):
+
+Take the `discounts` array from the query response and update only `discount.percentage` on each entry:
+```json
+PATCH https://www.wixapis.com/ecom/v1/discount-rules/{id}
+{
+  "discountRule": {
+    "id": "<id from query>",
+    "revision": "<revision from query>",
+    "discounts": [
+      {
+        "targetType": "SPECIFIC_ITEMS",
+        "specificItemsInfo": { "<scopes unchanged from query response>" },
+        "discount": {
+          "discountType": "PERCENTAGE",
+          "percentage": 10
+        }
+      }
+    ]
+  },
+  "mask": { "paths": ["discounts"] }
+}
+```
+
+> **Important**: Copy `targetType`, `specificItemsInfo.scopes` verbatim from the query response — do not reconstruct them. Only change `discount.discountType` and `discount.percentage`/`discount.fixedAmount`.
 
 ---
 
-## Step 5: Deactivate or delete a discount rule
+## Step 6: Deactivate or delete a discount rule
 
 To deactivate without deleting:
 ```json
@@ -223,7 +354,8 @@ To deactivate without deleting:
     "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
     "revision": "2",
     "active": false
-  }
+  },
+  "mask": { "paths": ["active"] }
 }
 ```
 
@@ -237,23 +369,28 @@ To delete permanently:
 
 | Field | Required | Notes |
 |---|---|---|
-| `name` | Yes | Internal name for the rule |
+| `name` | Yes | Internal name for the rule. Filterable in query. |
 | `active` | Yes | Whether the rule is currently applied |
 | `activeTimeInfo.start` | No | ISO 8601 start time. Omit for immediate activation |
 | `activeTimeInfo.end` | No | ISO 8601 end time. Omit for no expiration |
-| `discounts[].discount.discountType` | Yes | `PERCENTAGE` or `FIXED_AMOUNT` |
+| `discounts[].targetType` | Yes | Always `"SPECIFIC_ITEMS"` for standard rules |
+| `discounts[].specificItemsInfo.scopes[]` | Yes | Array of scope objects — see Scope types below |
+| `discounts[].discount.discountType` | Yes | `"PERCENTAGE"` or `"FIXED_AMOUNT"` or `"FIXED_PRICE"` |
 | `discounts[].discount.percentage` | If PERCENTAGE | Integer 1-100 |
 | `discounts[].discount.fixedAmount` | If FIXED_AMOUNT | Decimal string (e.g., `"5.00"`) |
-| `discounts[].scope.type` | Yes | `CATALOG`, `COLLECTION`, or `SPECIFIC_PRODUCTS` |
-| `discounts[].scope.id` | Yes | `"catalog"` for CATALOG type, or the collection/product UUID |
+| `settings.appliesTo` | Yes on create | Always `"ALL_ITEMS"` |
+| `revision` | On update/delete | Must match current value — fetch first |
+| `mask.paths[]` | On update | Recommended — list fields being changed (e.g., `["discounts"]`, `["active"]`) |
 
 ## Scope types
 
-| Scope Type | `scope.id` value | Description |
-|---|---|---|
-| `CATALOG` | `"catalog"` | Applies to all products in the store |
-| `COLLECTION` | Collection UUID | Applies to all products in a specific collection |
-| `SPECIFIC_PRODUCTS` | Product UUID | Applies to a single product (use multiple discount entries for multiple products) |
+| Scope | `type` | `id` prefix | When to use |
+|---|---|---|---|
+| All products | `"CATALOG_ITEM"` | `all_<appId>` | `catalogItemFilter.catalogAppId` only, no `catalogItemIds` |
+| Specific products | `"CATALOG_ITEM"` | `specific_<appId>` | `catalogItemFilter.catalogAppId` + `catalogItemFilter.catalogItemIds` |
+| Collection | `"CUSTOM_FILTER"` | `collections_<appId>` | `customFilter.appId` + `customFilter.params.collectionIds` |
+
+**Store catalog app ID** (required in all scopes): `215238eb-22a5-4c36-9e7b-e7c08025e04e`
 
 ## Recommendation → API Mapping
 

package/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md

@@ -11,16 +11,16 @@ description: Configures a pickup option for an online store so customers can cho
 
 ## Required APIs
 
-- [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/list-installed-delivery-carriers)
-- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles)
-- [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-region)
-- [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-carrier)
+- [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#list-installed-delivery-carriers)
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles)
+- [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-region)
+- [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-carrier)
 
 ---
 
 ## Step 1: Discover the Pickup carrier
 
-Call [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/list-installed-delivery-carriers) to find the Pickup carrier's `id`.
+Call [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#list-installed-delivery-carriers) to find the Pickup carrier's `id`.
 
 **Endpoint**: `GET https://www.wixapis.com/ecom/v1/delivery-profiles/installed-carriers`
 
@@ -53,7 +53,7 @@ If no Pickup carrier appears in the list, the Pickup app is not installed on the
 
 ## Step 2: Find the default delivery profile
 
-Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles) to retrieve the site's default delivery profile.
+Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles) to retrieve the site's default delivery profile.
 
 **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/query`
 
@@ -72,7 +72,7 @@ The response contains an array of `deliveryProfiles`. Find the one where `"defau
 
 ## Step 3: Add a delivery region for the pickup country
 
-If no region exists for the user's country in the default profile, call [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-region) to create one.
+If no region exists for the user's country in the default profile, call [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-region) to create one.
 
 **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region`
 
@@ -130,7 +130,7 @@ Save the new region's `id` from the response.
 
 ## Step 4: Add the Pickup carrier to the region
 
-Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-carrier) to attach the Pickup carrier to the delivery region.
+Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-carrier) to attach the Pickup carrier to the delivery region.
 
 **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/add-delivery-carrier`
 
@@ -205,5 +205,4 @@ Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solu
 
 ## Related Documentation
 
-- [Delivery Profiles: Introduction](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/introduction)
-- [Delivery Profiles: Sample Flows](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/sample-flows)
+- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping)

package/skills/wix-manage/references/ecommerce/skill-graph.md

@@ -61,6 +61,7 @@ flowchart TB
         setup-coupons
         setup-shipping-regions
         setup-shipping-rates
+        api-shipping
     end
 
     subgraph TrackingAPI["Tracking API"]
@@ -74,7 +75,7 @@ flowchart TB
         troubleshoot-checkout-delivery-dropoff
     end
 
-    Config -.-> |"calls via CallWixSiteAPI / ReadFullDocsArticle"| API
+    Config -.-> |"calls via CallWixSiteAPI"| API
 
     subgraph API["Wix REST API Docs (dev.wix.com)"]
         D1["Discount Rules API"]
@@ -82,8 +83,6 @@ flowchart TB
         D3["Products V3 API"]
         D4["Categories API"]
         D5["Catalog Analytics"]
-        S1["Delivery Profiles API"]
-        S2["Shipping Options API"]
         S3["Pickup Locations API"]
         S4["Local Delivery API"]
         SD["Profile Service API (wix-profile-client)"]
@@ -100,7 +99,7 @@ flowchart TB
     class goal-increase-aov,goal-clear-inventory,goal-seasonal-revenue,goal-drive-cross-sells,goal-reduce-cart-abandonment goal
     class guardrail-discount-conflicts,guardrail-margin-protection,guardrail-shipping-health,guardrail-rate-pricing-sanity guardrail
     class flow-upsell-boost,flow-bundle-and-save,flow-stock-mover,flow-seasonal-promotion,flow-fix-coverage-gaps,flow-add-free-shipping,flow-optimize-shipping-rates flow
-    class setup-discount-rules,setup-coupons,setup-shipping-regions,setup-shipping-rates,api-recommendation-tracking config
+    class setup-discount-rules,setup-coupons,setup-shipping-regions,setup-shipping-rates,api-recommendation-tracking,api-shipping config
     class recommend-ecommerce-strategy reco
     class recipe-apply-shipping-recommendations,setup-store-pickup-location,troubleshoot-discount-not-applying,troubleshoot-checkout-delivery-dropoff standalone
     class D1,D2,D3,D4,D5,S1,S2,S3,S4,SD apidoc
@@ -132,6 +131,7 @@ flowchart TB
 | `setup-coupons.md` | Step 4c (COUPON mechanism) |
 | `setup-shipping-regions.md` | flow-fix-coverage-gaps chain |
 | `setup-shipping-rates.md` | flow-add-free-shipping / optimize chains |
+| `api-shipping.md` | Shipping flows (fix-coverage-gaps, add-free-shipping, optimize, recipe, setup-store-pickup) |
 | `recipe-apply-shipping-recommendations.md` | README direct entry |
 | `setup-store-pickup-location.md` | README direct entry |
 | `troubleshoot-discount-not-applying.md` | README direct entry |

package/skills/wix-manage/references/forms/create-form.md

@@ -4,6 +4,8 @@ description: Creates a form with fields (name, email, etc.) using the Form Schem
 ---
 # RECIPE: Create a Wix Form
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST against `form-schema-service/v4/forms` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+
 Create a form on a Wix site that appears in the Forms & Submissions dashboard. The form collects visitor information (e.g., name, email) and can automatically upsert contacts on submission.
 
 ---

package/skills/wix-manage/references/stores/bulk-create-products-with-options.md

@@ -4,6 +4,8 @@ description: Uses bulk products endpoint to create multiple products with invent
 ---
 # RECIPE: Business Recipe - Bulk Creating Wix Store Products with inventory and options
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST against `stores/v3/bulk/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+
 Learn how to create multiple Wix store products with customizable options like colors, sizes, or other variants in a single bulk operation, allowing efficient creation of product catalogs.
 
 ---