@wix/agent-skills 1.0.0

package/skills/wix-manage/references/ecommerce/flow-bundle-and-save.md

@@ -0,0 +1,290 @@
+---
+name: "Flow: Bundle and Save"
+description: Creates a discount campaign promoting product discovery and cross-selling by requiring minimum item quantities. Targets high-margin categories with complementary products.
+layer: flow
+references:
+  - name: "Guardrail: Discount Conflicts"
+    path: ecommerce/guardrail-discount-conflicts.md
+    load: true
+  - name: "Setup: Discount Rules"
+    path: ecommerce/setup-discount-rules.md
+    load: true
+---
+# Flow: Bundle & Save Campaign
+
+> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
+> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts)
+> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules)
+
+Creates a discount that rewards customers for purchasing multiple items, encouraging product discovery and cross-selling. The discount activates when the cart contains a minimum number of items, and targets categories or products where bundling makes strategic sense.
+
+## Prerequisites
+
+- Wix Stores installed on the site
+- Products exist in the catalog across multiple categories
+- Access to `getCatalogAnalytics` and `getProductCatalogData` tools
+- Categories with 2+ products suitable for bundling
+
+## Required APIs
+
+- [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/create-discount-rule)
+- [Query Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/query-discount-rules)
+
+---
+
+## Step 1: Gather catalog data
+
+Call `getCatalogAnalytics` and `getProductCatalogData` concurrently to assess the catalog's bundle potential.
+
+**getCatalogAnalytics** call:
+```
+aggregates: min(price), max(price), avg(profitMargin), count
+```
+
+**getProductCatalogData** call:
+```
+ordered: price DESC, ordersCount DESC
+```
+
+Save the following values:
+- `min_price`, `max_price` — price range determines viable bundle combinations
+- `avg_profit_margin` — sets the discount ceiling
+- `count` — catalog breadth; more products = more bundling options
+- Top products by price and order count — identifies popular items for bundle anchoring
+
+---
+
+## Step 2: Analyze cross-sell patterns
+
+Evaluate the catalog for bundling opportunities:
+
+1. **Category diversity**: Look for categories with multiple products at complementary price points (e.g., a $50 main item + $15 accessories).
+2. **Price range suitability**: Wide price ranges (large gap between min_price and max_price) suggest tiered bundles. Narrow ranges suggest quantity-based bundles.
+3. **High-margin categories**: Categories with above-average profit margin are better candidates because the discount erodes less absolute profit.
+4. **Popular + discoverable**: Pair best-selling products (high ordersCount) with lower-visibility products to drive discovery.
+
+---
+
+## Step 3: Set minimum item quantity
+
+Determine the `minItemQuantity` based on catalog characteristics:
+
+| Catalog Profile | Recommended minItemQuantity | Rationale |
+|---|---|---|
+| High-price items (avg price > price_p75) | 2 | Customers are less likely to buy 3+ expensive items |
+| Medium-price items | 2-3 | Standard bundle size |
+| Low-price items (avg price < price_p25) | 3-4 | Lower price per item makes larger bundles feasible |
+| Many items in category (count > 10) | 3 | More products to choose from |
+| Few items in category (count <= 5) | 2 | Limited selection constrains bundle size |
+
+Default to `minItemQuantity: 2` if data is ambiguous.
+
+---
+
+## Step 4: Select discount percentage
+
+Scale the discount to the average margin, rewarding multi-item purchases without eroding profitability:
+
+| Margin Tier | Condition | Recommended Discount |
+|---|---|---|
+| Low margin | `avg_profit_margin < 25%` | 10% |
+| Medium margin | `25% <= avg_profit_margin <= 50%` | 15% |
+| High margin | `avg_profit_margin > 50%` | 20% |
+| No data | Margin unavailable | 10% |
+
+Verify that the discount respects the global cap of 25% and the minimum margin threshold of 15% (`discount <= avg_profit_margin - 15%`).
+
+---
+
+## Step 5: Determine discount scope
+
+Select the scope based on bundling analysis:
+
+- **CATEGORY** (preferred): When analytics show a clear category with cross-sell potential — multiple products, high margin, complementary items. Target that category.
+- **ITEMS**: When specific complementary products are identified for bundling (max 5 productIds). Use when cross-sell pairs are specific rather than category-wide.
+- **SITE**: When the goal is store-wide multi-buy incentive. Less targeted but simpler.
+
+---
+
+## Step 6: Convert category names to GUIDs (if CATEGORY scope)
+
+If scope is CATEGORY, call `getCategoryIds` to convert category names to GUIDs.
+
+- Never use category names as scope IDs — always use the GUID.
+- Exclude the "All Products" system category.
+- Max 3 categoryIds per discount rule.
+
+---
+
+## Step 7: Run guardrail checks
+
+**Run the Guardrail: Discount Conflicts checks before creating the rule.**
+
+1. Query existing active discount rules:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
+
+**Request**:
+```json
+{
+  "query": {
+    "filter": {
+      "active": true
+    },
+    "paging": {
+      "limit": 100
+    }
+  }
+}
+```
+
+2. Check for scope overlap with existing rules. Bundle discounts are especially prone to stacking — a customer buying 3 items in a category with both a bundle discount and a catalog-wide sale would get both.
+3. Check for coupon stacking risks.
+4. If conflicts found, present to merchant and get confirmation.
+
+---
+
+## Step 8: Create the discount rule with minItemQuantity condition
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules`
+
+**Request** — Buy 2+ items from a category, get 15% off:
+```json
+{
+  "discountRule": {
+    "name": "Buy 2+, Save 15% on Accessories",
+    "active": true,
+    "discounts": [
+      {
+        "discount": {
+          "discountType": "PERCENTAGE",
+          "percentage": 15
+        },
+        "scope": {
+          "id": "accessories-category-guid",
+          "type": "COLLECTION"
+        }
+      }
+    ],
+    "conditions": {
+      "itemQuantityRange": {
+        "from": 2
+      }
+    }
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "discountRule": {
+    "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
+    "revision": "1",
+    "name": "Buy 2+, Save 15% on Accessories",
+    "active": true,
+    "discounts": [
+      {
+        "discount": {
+          "discountType": "PERCENTAGE",
+          "percentage": 15
+        },
+        "scope": {
+          "id": "accessories-category-guid",
+          "type": "COLLECTION"
+        }
+      }
+    ],
+    "conditions": {
+      "itemQuantityRange": {
+        "from": 2
+      }
+    }
+  }
+}
+```
+
+**Request** — Buy 3+ specific items, get 10% off:
+```json
+{
+  "discountRule": {
+    "name": "Bundle 3 Best Sellers, Save 10%",
+    "active": true,
+    "discounts": [
+      {
+        "discount": {
+          "discountType": "PERCENTAGE",
+          "percentage": 10
+        },
+        "scope": {
+          "id": "product-uuid-1",
+          "type": "SPECIFIC_PRODUCTS"
+        }
+      },
+      {
+        "discount": {
+          "discountType": "PERCENTAGE",
+          "percentage": 10
+        },
+        "scope": {
+          "id": "product-uuid-2",
+          "type": "SPECIFIC_PRODUCTS"
+        }
+      },
+      {
+        "discount": {
+          "discountType": "PERCENTAGE",
+          "percentage": 10
+        },
+        "scope": {
+          "id": "product-uuid-3",
+          "type": "SPECIFIC_PRODUCTS"
+        }
+      }
+    ],
+    "conditions": {
+      "itemQuantityRange": {
+        "from": 3
+      }
+    }
+  }
+}
+```
+
+Save the returned `id` and `revision` for later management.
+
+---
+
+## Step 9: Verify the rule is active
+
+1. Query discount rules to confirm the new rule exists and is `active: true`
+2. Verify the minItemQuantity condition is correctly set
+3. Report to the merchant:
+   > "Bundle discount is live: {discount}% off when buying {minItemQuantity}+ items from {scope description}. This encourages customers to explore more products and increases items per order."
+
+---
+
+## Branching logic
+
+| Merchant intent | Scope | minItemQuantity | Discount |
+|---|---|---|---|
+| "Encourage people to buy more" | Determined by analytics | 2-3 | Margin-tiered |
+| "Bundle accessories together" | COLLECTION with category GUID | 2 | Margin-tiered |
+| "Buy 3 get 20% off these products" (explicit) | SPECIFIC_PRODUCTS with product GUIDs | 3 (user override) | 20% (user override) |
+| "Multi-buy deal on everything" | CATALOG (site-wide) | 2 | Margin-tiered |
+| "Promote these 4 items as a set" | SPECIFIC_PRODUCTS (max 5) | 2-4 | Margin-tiered |
+
+## Error Handling
+
+| Error | Cause | Fix |
+|---|---|---|
+| `DISCOUNT_RULE_NOT_FOUND` | Rule ID doesn't exist | Re-query discount rules for current IDs |
+| `REVISION_MISMATCH` | Revision doesn't match | Re-fetch rule for latest revision, then retry |
+| Too few products in category | Category has only 1 product — bundling not viable | Switch to SITE scope or suggest a different category |
+| Margin data unavailable | No profit margin data in catalog | Default to 10% discount |
+| Category GUID not found | Category name doesn't match any collection | Re-query categories or fall back to SITE scope |
+| Max items exceeded | More than 5 productIds specified | Reduce to top 5 by ordersCount or switch to CATEGORY scope |
+
+## References
+
+- [Discount Rules API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/introduction)

package/skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md

@@ -0,0 +1,300 @@
+---
+name: "Flow: Fix Coverage Gaps"
+description: Detects active delivery regions with zero shipping options and creates standard shipping for them. Cross-references delivery profiles with shipping options to find regions where customers cannot complete checkout.
+layer: flow
+references:
+  - name: "Guardrail: Shipping Health"
+    path: ecommerce/guardrail-shipping-health.md
+    load: true
+  - name: "Setup: Shipping Regions"
+    path: ecommerce/setup-shipping-regions.md
+    load: true
+---
+# Flow: Fix Shipping Coverage Gaps
+
+> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
+> - [Guardrail: Shipping Health](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-shipping-health)
+> - [Setup: Shipping Regions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-regions)
+
+Detects delivery regions where customers cannot see any shipping options at checkout and creates standard shipping to fill the gaps. A coverage gap is a HIGH priority blocking issue -- customers in affected destinations literally cannot complete a purchase.
+
+## Prerequisites
+
+- Wix Stores (or another eCommerce business solution) installed on the site
+- Site metrics available for AOV-based rate calculation (effective_aov)
+- Delivery profiles configured with at least one region
+
+## Required APIs
+
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles)
+- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/shipping-options/query-shipping-options)
+- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/shipping-options/create-shipping-option)
+
+---
+
+## Step 1: Query all delivery profiles
+
+Retrieve all delivery profiles to build a complete map of regions and their carriers.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/query`
+
+**Request**:
+```json
+{
+  "query": {
+    "cursorPaging": {
+      "limit": 100
+    }
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "deliveryProfiles": [
+    {
+      "id": "6a9b2f9b-533a-4d0d-ac8d-64ec3f32fcbd",
+      "name": "General profile",
+      "default": true,
+      "deliveryRegions": [
+        {
+          "id": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
+          "name": "Domestic",
+          "active": true,
+          "deliveryCarriers": [
+            {
+              "appId": "45c44b27-ca7b-4891-8c0d-1747d588b835",
+              "additionalCharges": []
+            }
+          ],
+          "destinations": [
+            {
+              "countryCode": "GB",
+              "subdivisions": []
+            }
+          ]
+        },
+        {
+          "id": "a1c2d3e4-f5a6-7890-bcde-f12345678901",
+          "name": "International",
+          "active": true,
+          "deliveryCarriers": [
+            {
+              "appId": "45c44b27-ca7b-4891-8c0d-1747d588b835",
+              "additionalCharges": []
+            }
+          ],
+          "destinations": []
+        }
+      ],
+      "revision": "43",
+      "createdDate": "2025-10-26T11:05:10.774Z",
+      "updatedDate": "2026-04-14T14:43:25.397Z"
+    }
+  ],
+  "pagingMetadata": {
+    "count": 1,
+    "cursors": {},
+    "hasNext": false
+  }
+}
+```
+
+Save every region `id`, `name`, `active` status, and carrier `appId` values.
+
+---
+
+## Step 2: Query all shipping options
+
+Retrieve all shipping options to determine which regions already have coverage.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options/query`
+
+**Request**:
+```json
+{
+  "query": {
+    "cursorPaging": {
+      "limit": 100
+    }
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "shippingOptions": [
+    {
+      "id": "c0e5be8f-5266-4720-a732-5f571e4750db",
+      "revision": "1",
+      "createdDate": "2026-04-14T14:43:24.804Z",
+      "updatedDate": "2026-04-14T14:43:24.804Z",
+      "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
+      "deliveryRegionIds": [],
+      "title": "Standard Shipping",
+      "estimatedDeliveryTime": "5-7 business days",
+      "rates": [
+        {
+          "amount": "15.00",
+          "conditions": [],
+          "multiplyByQuantity": false
+        }
+      ]
+    }
+  ],
+  "pagingMetadata": {
+    "count": 1,
+    "cursors": {},
+    "hasNext": false
+  }
+}
+```
+
+Build a map of `deliveryRegionId` to the count of shipping options linked to it.
+
+---
+
+## Step 3: Cross-reference regions and options to find gaps
+
+For each `deliveryRegion` across all profiles, apply these checks in order:
+
+### 3a: Skip externally managed regions
+
+If ALL carriers in the region have an external appId (e.g., Shippo `appId: "2b1943e2-3fc2-47bc-be56-3d402e5966d7"`), skip the region entirely. External carriers manage their own rates.
+
+### 3b: Skip inactive regions
+
+If `active=false`, skip. Inactive regions are not shown at checkout regardless of shipping options.
+
+### 3c: Count linked shipping options
+
+Count how many shipping options have this region's `id` in their `deliveryRegionId` field. If the count is **zero**, this is a **coverage gap**.
+
+**Severity**: HIGH -- blocking. Customers shipping to this region's destinations cannot see any shipping options and cannot complete checkout.
+
+### 3d: Check for options linked only to inactive regions
+
+For each shipping option, check if ALL of its linked regions have `active=false`. If so, the option exists but is invisible at checkout. This is a configuration issue worth flagging.
+
+### 3e: Check for orphaned options
+
+For each shipping option, verify that its `deliveryRegionId` actually exists in one of the delivery profiles. If the region no longer exists, the option is orphaned -- it exists in the system but is never shown to customers.
+
+---
+
+## Step 4: Create shipping options for each gap
+
+For each region identified as having zero coverage, create a standard shipping option and a free shipping tier.
+
+### 4a: Calculate rates
+
+- **Standard rate**: 5-10% of `effective_aov` (e.g., if effective_aov is $60, rate is $3.00-$6.00)
+- **Free shipping threshold**: `effective_aov x 1.2` (e.g., if effective_aov is $60, threshold is $72)
+- **Always set `estimatedDeliveryTime`** -- never leave it empty. Use "5-7 business days" for domestic, "7-14 business days" for international.
+
+### 4b: Create standard shipping option
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options`
+
+**Request**:
+```json
+{
+  "shippingOption": {
+    "title": "Standard Shipping",
+    "estimatedDeliveryTime": "5-7 business days",
+    "deliveryRegionId": "a1c2d3e4-f5a6-7890-bcde-f12345678901",
+    "rates": [
+      {
+        "amount": "4.99",
+        "multiplyByQuantity": false,
+        "conditions": []
+      }
+    ]
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "shippingOption": {
+    "id": "b2c3d4e5-f6a7-8901-cdef-234567890abc",
+    "revision": "1",
+    "createdDate": "2026-04-15T13:14:01.214Z",
+    "updatedDate": "2026-04-15T13:14:01.214Z",
+    "deliveryRegionId": "a1c2d3e4-f5a6-7890-bcde-f12345678901",
+    "deliveryRegionIds": [],
+    "title": "Standard Shipping",
+    "estimatedDeliveryTime": "5-7 business days",
+    "rates": [
+      {
+        "amount": "4.99",
+        "conditions": [],
+        "multiplyByQuantity": false
+      }
+    ]
+  }
+}
+```
+
+### 4c: Create free shipping option with threshold
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options`
+
+**Request**:
+```json
+{
+  "shippingOption": {
+    "title": "Free Shipping",
+    "estimatedDeliveryTime": "5-7 business days",
+    "deliveryRegionId": "a1c2d3e4-f5a6-7890-bcde-f12345678901",
+    "rates": [
+      {
+        "amount": "0",
+        "multiplyByQuantity": false,
+        "conditions": [
+          {
+            "type": "BY_TOTAL_PRICE",
+            "operator": "GTE",
+            "value": "72"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Step 5: Verify the fix
+
+After creating options for all gaps, re-query shipping options to confirm:
+
+1. New options appear in the list with correct titles and rates
+2. Each new option is linked to the correct `deliveryRegionId`
+3. The `estimatedDeliveryTime` is populated (not empty)
+4. No regions remain uncovered
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options/query`
+
+Use the same request from Step 2 and verify the count now covers all active, non-external regions.
+
+---
+
+## Error Handling
+
+| Error | Cause | Fix |
+|---|---|---|
+| `deliveryRegionId is not a valid GUID` | Used `deliveryRegionIds` (plural) instead of `deliveryRegionId` (singular) in create request | Use the singular `deliveryRegionId` field |
+| `SHIPPING_OPTION_NOT_FOUND` | The shipping option ID doesn't exist | Re-query shipping options to get current IDs |
+| `REVISION_MISMATCH` | The `revision` doesn't match the current version | Re-fetch the option to get the latest revision, then retry |
+| Region appears covered but customers still can't check out | Region has `active=false` | Check region active status in the delivery profile; activate the region if intended |
+| Option exists but not visible at checkout | Option linked to an inactive or deleted region | Verify region exists and `active=true` in the delivery profile |
+
+## References
+
+- [Delivery Profiles API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/introduction)
+- [Shipping Options API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/shipping-options/introduction)