@wix/agent-skills 1.0.0

package/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md

@@ -0,0 +1,88 @@
+---
+name: "Guardrail: Margin Protection"
+description: Safety constraints for discount percentages — global discount cap, minimum margin requirements, user override protocol, and percentage sanity checks.
+layer: guardrail
+---
+# Guardrail: Margin Protection
+
+## When to apply
+
+Run before EVERY discount rule creation or update. Check both the new rule's discount AND the cumulative effect with existing active rules (stacking).
+
+---
+
+## Constraint 1: Global discount cap
+
+The default maximum discount percentage (`discountMargin`) is **25%**.
+
+Any discount rule that exceeds this cap should be flagged before creation:
+
+> "This discount ({pct}%) exceeds the default cap of 25%. Proceeding only because you explicitly requested it."
+
+Respect the cap unless user input explicitly overrides it.
+
+---
+
+## Constraint 2: Minimum margin requirement
+
+The default minimum margin percentage (`minMarginPct`) is **15%**.
+
+Never create a discount that would push the effective margin below 15% unless the user explicitly overrides this constraint.
+
+If cost data is available, calculate:
+- `effective_margin = (price - cost - discount_amount) / price × 100`
+- If `effective_margin < minMarginPct` → block and explain the margin impact.
+
+---
+
+## Constraint 3: Percentage sanity checks
+
+| Discount value | Action |
+|---|---|
+| Discount > 50% | Warn — "This discount is {pct}% off. A $100 product would sell for ${100 - pct}. Are you sure?" |
+| Discount = 100% | Block unless explicitly confirmed — "This makes the product free." |
+| Discount > 100% | Block always — "A discount cannot exceed 100%." |
+
+---
+
+## Constraint 4: User input override protocol (ABSOLUTE PRIORITY)
+
+User input overrides ALL constraints — margin caps, discount caps, naming conventions, percentage limits.
+
+**How it works:**
+
+- If the user says "50% discount" and the cap is 25%, honor 50%.
+- If the user says "set margin to 5%" and the minimum is 15%, honor 5%.
+- Document which constraints were overridden in reasoning so there is a clear audit trail.
+
+**Example reasoning output:**
+
+> "Creating a 50% discount as requested. Note: this overrides the default 25% discount cap. The effective margin on a product with 60% gross margin would drop to 10%, below the default 15% minimum margin threshold. Proceeding per explicit user instruction."
+
+---
+
+## Constraint 5: Stacking cumulative check
+
+When creating a new discount, also check the cumulative effect with existing active rules:
+
+1. Query all active discount rules that overlap in scope with the new rule.
+2. Calculate the combined discount percentage (accounting for multiplicative stacking).
+3. If the combined discount exceeds the global cap or violates the minimum margin, warn the merchant:
+
+> "Combined with the existing '{existingRuleName}' ({existingPct}%), the total effective discount would be approximately {combinedPct}%. This exceeds the {cap}% cap / pushes margin below {minMarginPct}%."
+
+---
+
+## Summary: Decision matrix
+
+| Scenario | Action |
+|---|---|
+| Discount ≤ 25% and margin ≥ 15% | Proceed |
+| Discount > 25% but ≤ 50%, no user override | Warn, ask for confirmation |
+| Discount > 25%, user explicitly requested | Proceed, document override |
+| Discount > 50% | Warn with dollar example, ask for confirmation |
+| Discount = 100% | Block unless explicitly confirmed |
+| Discount > 100% | Block always |
+| Combined stacking exceeds cap | Warn about cumulative effect |
+| Margin drops below 15%, no user override | Block, explain margin impact |
+| Margin drops below 15%, user override | Proceed, document override |

package/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md

@@ -0,0 +1,108 @@
+---
+name: "Guardrail: Rate Pricing Sanity"
+description: Validates shipping rate pricing against AOV and catalog data. Flags excessive rates, per-item penalties, unreachable free shipping thresholds, and backup rate sticker shock.
+layer: guardrail
+---
+# Guardrail: Rate Pricing Sanity
+
+## When to use
+
+Run these checks when evaluating existing shipping rates or before creating/updating shipping rate configurations. All thresholds are relative to the store's Average Order Value (AOV).
+
+---
+
+## Check 1: Excessive shipping cost
+
+**Threshold**: Any rate `amount` > AOV x 0.15 (15%)
+
+**Why**: Shipping costs above 15% of order value are a top reason for cart abandonment. Customers who see disproportionately high shipping fees frequently abandon their carts.
+
+**Detection**:
+- For each shipping rate, compare `amount` against `AOV × 0.15`
+- If exceeded → flag:
+
+> "Shipping rate '{title}' charges ${amount}, which is {pct}% of your average order value (${AOV}). Shipping costs above 15% of order value are a top reason for cart abandonment."
+
+---
+
+## Check 2: Per-item penalty (multiplyByQuantity)
+
+**Trigger**: `multiplyByQuantity: true` on any shipping rate
+
+**Why**: Per-item shipping charges penalize larger orders and discourage customers from adding more items to cart.
+
+**Detection**:
+- Find all rates with `multiplyByQuantity: true`
+- Calculate the impact for a typical multi-item order:
+
+> "Your '{title}' rate charges per item (${amount} x quantity). A 5-item order costs ${amount x 5}. Switch to a flat rate or tiered pricing to encourage larger orders."
+
+---
+
+## Check 3: Free shipping threshold too high
+
+**Threshold**: Free shipping threshold > AOV x 2
+
+**Why**: If the free shipping minimum is more than double the average order, very few customers will ever qualify. The threshold should be achievable — close enough to the AOV to encourage customers to add one more item.
+
+**Detection**:
+- Compare free shipping `threshold` against `AOV × 2`
+- If exceeded → flag:
+
+> "Your free shipping threshold (${threshold}) is {X}x your average order (${AOV}). Most customers won't reach it. Lower to ${AOV x 1.2} to make it achievable and drive larger orders."
+
+---
+
+## Check 4: Free shipping threshold too low
+
+**Threshold**: Free shipping threshold < AOV x 0.8
+
+**Why**: If the threshold is below the average order value, most customers already qualify for free shipping without adding anything to their cart. This provides no upsell incentive and may erode margins unnecessarily.
+
+**Detection**:
+- Compare free shipping `threshold` against `AOV × 0.8`
+- If below → flag:
+
+> "Your free shipping threshold (${threshold}) is below your average order value (${AOV}). Most customers already qualify, so this threshold isn't driving larger orders. Consider raising it to ${AOV x 1.2} to encourage add-on purchases."
+
+---
+
+## Check 5: Backup rate sticker shock
+
+**Threshold**: `backupRate.amount` > effective AOV x 0.15
+
+**Why**: Backup rates apply when the primary carrier can't fulfill (e.g., remote address, service outage). If the backup rate is dramatically higher than normal shipping, customers experience sticker shock at checkout.
+
+**Detection**:
+- For each carrier's `backupRate`, compare `amount` against `effective_aov × 0.15`
+- If exceeded → flag:
+
+> "Backup rate of ${amount} is {pct}% of your average order value. When triggered, this will surprise customers with unexpectedly high shipping. Set the backup rate to 5-10% of average order value (${effective_aov x 0.05} - ${effective_aov x 0.10})."
+
+---
+
+## Check 6: Hidden surcharges
+
+**Threshold**: Total `additionalCharges` across all carriers > AOV x 0.10
+
+**Why**: Carrier surcharges (fuel, residential delivery, handling fees) add up. If the total surcharge burden exceeds 10% of the order value, it may negate the perceived value of the base shipping rate.
+
+**Detection**:
+- Sum all `additionalCharges` across active carriers
+- Compare total against `AOV × 0.10`
+- If exceeded → flag:
+
+> "Carrier surcharges add ${total} to shipping costs. Combined with base rates, total shipping cost may deter customers. Review each surcharge to determine if it's necessary."
+
+---
+
+## Summary: Pricing sanity thresholds
+
+| Check | Threshold | Action |
+|---|---|---|
+| Excessive rate | Rate > 15% of AOV | Flag — cart abandonment risk |
+| Per-item penalty | `multiplyByQuantity: true` | Flag — discourages larger orders |
+| Free threshold too high | Threshold > 2x AOV | Flag — unreachable for most customers |
+| Free threshold too low | Threshold < 0.8x AOV | Flag — no upsell incentive, margin erosion |
+| Backup rate shock | Backup > 15% of AOV | Flag — recommend 5-10% of AOV |
+| Hidden surcharges | Total surcharges > 10% of AOV | Flag — review necessity |

package/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md

@@ -0,0 +1,124 @@
+---
+name: "Guardrail: Shipping Health"
+description: Shipping health score calculation (CRITICAL/POOR/FAIR/GOOD/EXCELLENT) with exact scoring criteria. Includes the mandatory business context filter for international shipping recommendations.
+layer: guardrail
+references:
+  - name: "Troubleshoot: Checkout Delivery Drop-off"
+    path: ecommerce/troubleshoot-checkout-delivery-dropoff.md
+    load: false
+---
+# Guardrail: Shipping Health
+
+> **Related skills** (read with `ReadFullDocsArticle` if needed):
+> - [Troubleshoot: Checkout Delivery Drop-off](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/troubleshoot-checkout-delivery-drop-off)
+
+## When to use
+
+Calculate the shipping health score whenever evaluating a store's shipping configuration. Use this score to prioritize recommendations and determine urgency of shipping issues.
+
+---
+
+## Health score levels
+
+### CRITICAL
+
+Any of the following conditions:
+
+- `delivery_profiles` is empty AND `shipping_options` is empty
+- All regions across all profiles have `active: false`
+
+**Implication**: The store cannot ship any orders. Immediate action required.
+
+### POOR
+
+Any of the following conditions:
+
+- Only 1 delivery profile with empty regions
+- Only 1 shipping option total
+- `delivery_step_cvr` < 50% with shipping issues detected
+- All carriers have `backupRate.active: false`
+
+**Implication**: Shipping is minimally functional but has significant gaps that are likely causing lost sales.
+
+### FAIR
+
+All of the following conditions:
+
+- 1-2 delivery profiles with 1-2 active regions
+- 2-4 shipping options
+- No free shipping option available
+- OR: `delivery_step_cvr` between 50-65%
+
+**Implication**: Basic shipping is working but missing key elements that drive conversion.
+
+### GOOD
+
+All of the following conditions:
+
+- 1+ delivery profiles with both domestic and international regions
+- 3-5 shipping options including at least one free shipping option
+- 1+ active carriers
+- `delivery_step_cvr` between 65-75%
+
+**Implication**: Solid shipping setup. Optimization opportunities exist but fundamentals are covered.
+
+### EXCELLENT
+
+All of the following conditions:
+
+- Multiple active regions
+- Tiered shipping rates
+- Free shipping option available
+- Multiple carriers with backup rates enabled
+- Pickup and/or local delivery options configured
+- `delivery_step_cvr` ≥ 75%
+- No `multiplyByQuantity` pricing on any rate
+
+**Implication**: Best-in-class shipping configuration. Focus on maintaining and fine-tuning.
+
+---
+
+## Business context filter (MANDATORY)
+
+**This filter MUST be applied before recommending any international shipping action.**
+
+### Check business type
+
+Inspect the store's `industry` and `businessType` fields (case-insensitive match) for any of the following keywords:
+
+- food
+- restaurant
+- grocery
+- bakery
+- catering
+- perishable
+- fresh
+- meat
+- produce
+- dairy
+- drink
+- beverage
+
+### If matched
+
+**DO NOT recommend any international shipping action.** Perishable/food businesses face regulatory, spoilage, and logistics barriers that make international shipping impractical as a default recommendation.
+
+### Identifying international regions
+
+A region is considered "international" if any of the following are true:
+
+- Region `name` contains "international" or "internacional" (case-insensitive)
+- Region `destinations[]` is empty (wildcard / all countries)
+- Region `destinations` include countries outside the store's home country
+
+---
+
+## Summary: Score decision table
+
+| Score | Key indicator | Action |
+|---|---|---|
+| CRITICAL | No profiles/options or all regions inactive | Immediate setup required |
+| POOR | Minimal config, low CVR, or no backup rates | Address fundamental gaps |
+| FAIR | Basic setup, no free shipping, moderate CVR | Add free shipping, expand regions |
+| GOOD | Domestic + international, free shipping, good CVR | Optimize rates and carriers |
+| EXCELLENT | Full coverage, tiered rates, high CVR | Maintain and fine-tune |

package/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md

@@ -0,0 +1,299 @@
+---
+name: "Recipe: Apply Shipping Recommendations"
+description: Applies AI-generated shipping recommendations to a Wix e-commerce store. Reads the current delivery profile and shipping options, then creates or updates shipping options based on recommendation data. Supports creating new options with conditional rates, updating existing options, and querying delivery profiles for region/carrier context.
+---
+# Apply Shipping Recommendations
+
+## Prerequisites
+
+- Wix Stores (or another eCommerce business solution) installed on the site
+- Shipping recommendations data available (from the AI recommendation system or provided directly)
+
+## Required APIs
+
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles)
+- [Get Delivery Profile](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/get-delivery-profile)
+
+---
+
+## Step 1: Query the current shipping configuration
+
+Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles) to understand the site's delivery setup — profiles, regions, carriers, and backup rates.
+
+**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": []
+            }
+          ]
+        }
+      ],
+      "revision": "43",
+      "createdDate": "2025-10-26T11:05:10.774Z",
+      "updatedDate": "2026-04-14T14:43:25.397Z"
+    }
+  ],
+  "pagingMetadata": {
+    "count": 1,
+    "cursors": {},
+    "hasNext": false
+  }
+}
+```
+
+Save the profile `id`, `revision`, and each region's `id` and `active` status. Identify which regions have carriers with missing backup rates (`backupRate` absent or `backupRate.active: false`).
+
+---
+
+## Step 2: Query existing shipping options
+
+**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
+  }
+}
+```
+
+Note: The response uses `deliveryRegionId` (singular) as the primary field linking an option to a region.
+
+---
+
+## Step 3: Apply recommendation — Create a new shipping option
+
+When the recommendation action is `create_shipping_option`, create a new option linked to a specific delivery region.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options`
+
+**Request** — flat rate example:
+```json
+{
+  "shippingOption": {
+    "title": "Express Shipping",
+    "estimatedDeliveryTime": "1-2 business days",
+    "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
+    "rates": [
+      {
+        "amount": "12.99",
+        "multiplyByQuantity": false,
+        "conditions": []
+      }
+    ]
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "shippingOption": {
+    "id": "dece6160-4e72-4fcc-adcc-7607215edab0",
+    "revision": "1",
+    "createdDate": "2026-04-15T13:14:01.214Z",
+    "updatedDate": "2026-04-15T13:14:01.214Z",
+    "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
+    "deliveryRegionIds": [],
+    "title": "Express Shipping",
+    "estimatedDeliveryTime": "1-2 business days",
+    "rates": [
+      {
+        "amount": "12.99",
+        "conditions": [],
+        "multiplyByQuantity": false
+      }
+    ]
+  }
+}
+```
+
+**Request** — free shipping with price threshold:
+```json
+{
+  "shippingOption": {
+    "title": "Free Shipping",
+    "estimatedDeliveryTime": "5-7 business days",
+    "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
+    "rates": [
+      {
+        "amount": "0",
+        "multiplyByQuantity": false,
+        "conditions": [
+          {
+            "type": "BY_TOTAL_PRICE",
+            "operator": "GTE",
+            "value": "75"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Key field rules:**
+
+| Field | Required | Notes |
+|---|---|---|
+| `title` | Yes | Display name at checkout |
+| `estimatedDeliveryTime` | Yes | Free text shown to customers |
+| `deliveryRegionId` | Yes | Region UUID from Step 1. Must use **singular** field, not `deliveryRegionIds` |
+| `rates` | Yes | Array of rate objects |
+| `rates[].amount` | Yes | Decimal string (`"5.99"`, `"0"` for free) |
+| `rates[].multiplyByQuantity` | Yes | Almost always `false` |
+| `rates[].conditions` | Yes | Empty array for flat rate; see condition types below |
+
+**Condition types** (for tiered/conditional rates):
+
+| Type | Description | Example |
+|---|---|---|
+| `BY_TOTAL_PRICE` | Cart total threshold | `"operator": "GTE", "value": "75"` |
+| `BY_TOTAL_WEIGHT` | Weight threshold | `"operator": "LTE", "value": "10"` |
+| `BY_TOTAL_QUANTITY` | Item count threshold | `"operator": "GTE", "value": "3"` |
+
+Operators: `EQ`, `GT`, `GTE`, `LT`, `LTE`
+
+---
+
+## Step 4: Apply recommendation — Update an existing shipping option
+
+When the recommendation action is `update_shipping_option`, update an existing option's title, delivery time, or rates.
+
+**Endpoint**: `PATCH https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}`
+
+Replace `{shippingOptionId}` with the option's `id` from Step 2.
+
+**Request**:
+```json
+{
+  "shippingOption": {
+    "id": "c0e5be8f-5266-4720-a732-5f571e4750db",
+    "revision": "1",
+    "title": "Updated Standard Shipping",
+    "estimatedDeliveryTime": "3-5 business days",
+    "rates": [
+      {
+        "amount": "9.99",
+        "multiplyByQuantity": false,
+        "conditions": []
+      }
+    ]
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "shippingOption": {
+    "id": "c0e5be8f-5266-4720-a732-5f571e4750db",
+    "revision": "2",
+    "createdDate": "2026-04-14T14:43:24.804Z",
+    "updatedDate": "2026-04-15T13:14:13.716Z",
+    "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
+    "deliveryRegionIds": [],
+    "title": "Updated Standard Shipping",
+    "estimatedDeliveryTime": "3-5 business days",
+    "rates": [
+      {
+        "amount": "9.99",
+        "conditions": [],
+        "multiplyByQuantity": false
+      }
+    ]
+  }
+}
+```
+
+The `revision` field is required and must match the current revision. The response returns the incremented revision.
+
+---
+
+## Step 5: Verify the changes
+
+After applying recommendations, query shipping options again (Step 2) to confirm the changes took effect. Verify:
+
+- New options appear in the list with the correct title, rates, and region link
+- Updated options reflect the new values and incremented revision
+- The option is linked to the correct `deliveryRegionId`
+
+---
+
+## 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 |
+
+## 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)