@wix/agent-skills 1.0.0

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

@@ -0,0 +1,444 @@
+---
+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.
+layer: config
+---
+# Setup Discount Rules
+
+## Prerequisites
+
+- Wix Stores (or another eCommerce business solution) installed on the site
+- At least one product in the catalog
+
+## Required APIs
+
+- [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/create-discount-rule)
+- [Get Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/get-discount-rule)
+- [Query Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/query-discount-rules)
+- [Update Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/update-discount-rule)
+- [Delete Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/delete-discount-rule)
+
+---
+
+## Step 1: Query existing discount rules
+
+Before creating new rules, check what already exists to avoid conflicts.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
+
+**Request**:
+```json
+{
+  "query": {
+    "paging": {
+      "limit": 100
+    }
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "discountRules": [
+    {
+      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "revision": "1",
+      "name": "Summer Sale 10%",
+      "active": true,
+      "activeTimeInfo": {
+        "start": "2026-06-01T00:00:00.000Z",
+        "end": "2026-08-31T23:59:59.000Z"
+      },
+      "discounts": [
+        {
+          "discount": {
+            "discountType": "PERCENTAGE",
+            "percentage": 10
+          },
+          "scope": {
+            "id": "catalog",
+            "type": "CATALOG"
+          }
+        }
+      ]
+    }
+  ],
+  "pagingMetadata": {
+    "count": 1,
+    "hasNext": false
+  }
+}
+```
+
+Note existing rules and their scopes to avoid stacking conflicts.
+
+---
+
+## Step 2: Create a percentage discount rule
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules`
+
+**Request** — 20% off all products:
+```json
+{
+  "discountRule": {
+    "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"
+        }
+      }
+    ]
+  }
+}
+```
+
+**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"
+        }
+      }
+    ]
+  }
+}
+```
+
+**Request** — 15% off a specific collection:
+```json
+{
+  "discountRule": {
+    "name": "Summer Collection Sale",
+    "active": true,
+    "discounts": [
+      {
+        "discount": {
+          "discountType": "PERCENTAGE",
+          "percentage": 15
+        },
+        "scope": {
+          "id": "collection-uuid-here",
+          "type": "COLLECTION"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Step 3: Create a fixed-amount discount rule
+
+**Request** — $5 off specific products:
+```json
+{
+  "discountRule": {
+    "name": "$5 Off Selected Items",
+    "active": true,
+    "discounts": [
+      {
+        "discount": {
+          "discountType": "FIXED_AMOUNT",
+          "fixedAmount": "5.00"
+        },
+        "scope": {
+          "id": "product-uuid-here",
+          "type": "SPECIFIC_PRODUCTS"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Step 4: Update a discount rule
+
+**Endpoint**: `PATCH https://www.wixapis.com/ecom/v1/discount-rules/{discountRuleId}`
+
+**Request**:
+```json
+{
+  "discountRule": {
+    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+    "revision": "1",
+    "name": "Extended Flash Sale 25% Off",
+    "discounts": [
+      {
+        "discount": {
+          "discountType": "PERCENTAGE",
+          "percentage": 25
+        },
+        "scope": {
+          "id": "catalog",
+          "type": "CATALOG"
+        }
+      }
+    ]
+  }
+}
+```
+
+The `revision` field is required and must match the current revision.
+
+---
+
+## Step 5: Deactivate or delete a discount rule
+
+To deactivate without deleting:
+```json
+{
+  "discountRule": {
+    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+    "revision": "2",
+    "active": false
+  }
+}
+```
+
+To delete permanently:
+
+**Endpoint**: `DELETE https://www.wixapis.com/ecom/v1/discount-rules/{discountRuleId}`
+
+---
+
+## Key field rules
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | Yes | Internal name for the rule |
+| `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[].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 |
+
+## 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) |
+
+## Recommendation → API Mapping
+
+When creating a discount rule from a recommendation output, use this mapping to convert the recommendation's simplified JSON into the actual Discount Rules API payload.
+
+### Constants
+
+- **Store catalog app ID**: `215238eb-22a5-4c36-9e7b-e7c08025e04e` — used in all scope constructions below.
+- **Initial state**: Recommendations create rules as `active: false` with `status: "PENDING"`. The merchant must approve before the rule goes live.
+
+### Scope mapping
+
+The recommendation's `scope` field maps to the API's internal scope structure. The scope ID uses a prefix convention:
+
+| Recommendation scope | API scope type | Scope ID prefix | How to build |
+|---|---|---|---|
+| `SITE` | `CATALOG_ITEM` | `all_` | Set `catalogItemFilter.catalogAppId` to the store catalog app ID. No item IDs. |
+| `ITEMS` | `CATALOG_ITEM` | `specific_` | Set `catalogItemFilter.catalogAppId` + `catalogItemFilter.catalogItemIds` to the product UUIDs from `productIds`. |
+| `CATEGORY` | `CUSTOM_FILTER` | `collections_` | Set `customFilter.appId` to the store catalog app ID + `customFilter.params.collectionIds` to the category UUIDs from `categoryIds`. |
+
+**Example — SITE scope**:
+```json
+{
+  "scope": {
+    "id": "all_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+    "type": "CATALOG_ITEM",
+    "catalogItemFilter": {
+      "catalogAppId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
+    }
+  }
+}
+```
+
+**Example — ITEMS scope** (with product IDs):
+```json
+{
+  "scope": {
+    "id": "specific_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+    "type": "CATALOG_ITEM",
+    "catalogItemFilter": {
+      "catalogAppId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+      "catalogItemIds": ["product-uuid-1", "product-uuid-2"]
+    }
+  }
+}
+```
+
+**Example — CATEGORY scope** (with collection IDs):
+```json
+{
+  "scope": {
+    "id": "collections_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+    "type": "CUSTOM_FILTER",
+    "customFilter": {
+      "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+      "params": {
+        "collectionIds": ["collection-uuid-1"]
+      }
+    }
+  }
+}
+```
+
+### Discount type mapping
+
+| Recommendation `discountType` | API field to set | Value format |
+|---|---|---|
+| `PERCENTAGE` | `discount.percentage` | Integer (e.g., `15`) |
+| `FIXED_AMOUNT` | `discount.fixedAmount` | String (e.g., `"5.00"`) |
+| `FIXED_PRICE` | `discount.fixedPrice` | String (e.g., `"29.99"`) |
+
+All discount entries use `targetType: "SPECIFIC_ITEMS"` with the scope wrapped in `specificItemsInfo.scopes[]`.
+
+### Trigger mapping (conditions)
+
+Triggers determine WHEN the discount activates. They are built from the recommendation's `conditions` fields. **If no conditions exist (both minSubTotal and minItemQuantity are 0), do NOT set a trigger — the discount applies unconditionally.**
+
+| Condition | Trigger type | How to build |
+|---|---|---|
+| `minItemQuantity > 0` only | `ITEM_QUANTITY_RANGE` | Set `itemQuantityRange.from` to the value. No upper bound. Include the same scope as the discount target. |
+| `minSubTotal > 0` only | `SUBTOTAL_RANGE` | Set `subtotalRange.from` to the value as a string. No upper bound. Include the same scope. |
+| Both conditions > 0 | `AND` | Combine both triggers in `and.triggers[]` array. |
+| Neither condition | No trigger | Leave trigger field unset entirely. |
+
+**Example — minSubTotal trigger** (upsell boost: spend $200+):
+```json
+{
+  "trigger": {
+    "triggerType": "SUBTOTAL_RANGE",
+    "subtotalRange": {
+      "from": "200",
+      "scopes": [
+        {
+          "id": "all_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+          "type": "CATALOG_ITEM",
+          "catalogItemFilter": {
+            "catalogAppId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+**Example — minItemQuantity trigger** (bundle: buy 3+):
+```json
+{
+  "trigger": {
+    "triggerType": "ITEM_QUANTITY_RANGE",
+    "itemQuantityRange": {
+      "from": 3,
+      "scopes": [
+        {
+          "id": "collections_215238eb-22a5-4c36-9e7b-e7c08025e04e",
+          "type": "CUSTOM_FILTER",
+          "customFilter": {
+            "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+            "params": {
+              "collectionIds": ["category-uuid"]
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+**Example — AND trigger** (both conditions):
+```json
+{
+  "trigger": {
+    "triggerType": "AND",
+    "and": {
+      "triggers": [
+        {
+          "triggerType": "ITEM_QUANTITY_RANGE",
+          "itemQuantityRange": { "from": 2, "scopes": [/* same scope */] }
+        },
+        {
+          "triggerType": "SUBTOTAL_RANGE",
+          "subtotalRange": { "from": "100", "scopes": [/* same scope */] }
+        }
+      ]
+    }
+  }
+}
+```
+
+### Date handling
+
+| Recommendation field | API mapping |
+|---|---|
+| `startDate` is a date string (e.g., `"2026-06-01"`) | Convert to ISO 8601 timestamp: `activeTimeInfo.start` |
+| `startDate` is empty `""` | Default to current time (now) |
+| `endDate` is a date string | Convert to ISO 8601 timestamp: `activeTimeInfo.end` |
+| `endDate` is empty `""` | Omit `activeTimeInfo.end` — rule has no expiration |
+
+### Settings
+
+All recommendation-created rules use these fixed settings:
+```json
+{
+  "settings": {
+    "appliesTo": "ALL_ITEMS",
+    "indexOptIn": true
+  }
+}
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Fix |
+|---|---|---|
+| `DISCOUNT_RULE_NOT_FOUND` | The discount rule ID doesn't exist | Re-query discount rules to get current IDs |
+| `REVISION_MISMATCH` | The `revision` doesn't match the current version | Re-fetch the rule to get the latest revision, then retry |
+| `INVALID_DISCOUNT_TYPE` | Unsupported discount type | Use `PERCENTAGE` or `FIXED_AMOUNT` |
+| Both `productIds` and `categoryIds` set | Scope mutual exclusivity violation | Use only one: ITEMS with productIds OR CATEGORY with categoryIds |
+| `productIds` empty when scope is ITEMS | Missing required IDs | Query products and provide at least 1 product UUID |
+| `categoryIds` empty when scope is CATEGORY | Missing required IDs | Call getCategoryIds to convert category names to GUIDs |
+
+## References
+
+- [Discount Rules API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/introduction)
+- [Coupons API](https://dev.wix.com/docs/api-reference/business-solutions/coupons/introduction)

package/skills/wix-manage/references/ecommerce/setup-shipping-rates.md

@@ -0,0 +1,86 @@
+---
+name: "Setup: Shipping Rates"
+description: Configures shipping option rates — rate types (flat, tiered, free), condition types and operators, free shipping threshold calibration, AOV sanity check, per-item penalty avoidance, and tier gap detection.
+layer: config
+---
+# Shipping Rates
+
+## AOV Sanity Check
+
+**MANDATORY before any threshold calculation that references AOV.** Raw AOV can be misleading due to data issues or bulk purchases.
+
+1. Extract `price_p25` and `price_p50` from `catalog_stats` (use the "All Products" category group).
+
+2. Evaluate AOV against catalog price distribution:
+
+| Condition | Interpretation | Action |
+|---|---|---|
+| AOV < price_p25 | Anomalous — likely a data or unit issue | Override: use `price_p50` as base. Note in reasoning. |
+| AOV > price_p90 | Possible bulk/combo orders | Still use AOV but note discrepancy. |
+| price_p25 <= AOV <= price_p90 | Reasonable | Use AOV as-is. |
+
+3. Store the result as `effective_aov`. Use `effective_aov` everywhere AOV would be referenced — backup rate calibration, shipping thresholds, free shipping thresholds.
+
+---
+
+## Rate Types
+
+Rate types are determined by the conditions array, not by an explicit field.
+
+| Rate Type | Configuration |
+|---|---|
+| Flat rate | `conditions[]` empty, just `amount` |
+| Free shipping | `amount = "0"` with optional `BY_TOTAL_PRICE GTE [threshold]` |
+| Weight-based tiers | `BY_TOTAL_WEIGHT` conditions |
+| Price-based tiers | `BY_TOTAL_PRICE` conditions |
+| Quantity-based | `BY_TOTAL_QUANTITY` conditions |
+
+## Condition Operators
+
+Supported operators: `EQ`, `GT`, `GTE`, `LT`, `LTE`.
+
+When multiple conditions appear in the same rate entry, they combine with AND logic.
+
+## Free Shipping Threshold Calibration
+
+Optimal range: `effective_aov x 1.0` to `effective_aov x 1.5`
+
+| Scenario | Impact |
+|---|---|
+| `threshold > AOV x 2` | Too high -- customers rarely qualify |
+| `threshold < AOV x 0.8` | Too low -- potential margin erosion |
+
+Enhanced calibration using catalog stats:
+- If `price_p75 > aov x 1.5` then use `price_p50 x 1.5`
+- If `price_p75 < aov` then use `aov x 1.2`
+- Default: `max(aov x 1.2, price_p75)`
+
+## Per-Item Penalty Avoidance
+
+`multiplyByQuantity = true` charges `amount x cart quantity`. Always flag this configuration and recommend switching to flat rate or tiered pricing instead.
+
+## Price-Based Tiers Recommendation
+
+Recommend switching from flat to tiered rates when ALL of the following are true:
+- `price_spread_ratio > 10`
+- `price_stddev > price_avg x 0.5`
+- Only flat rates currently exist
+
+Recommended tier structure:
+- **Tier 1**: Below p50 -- lower rate
+- **Tier 2**: p50 to p75 -- standard rate
+- **Tier 3**: Above p75 -- higher rate or free
+
+## Flat Rate Confirmation
+
+When ALL of the following are true, flat rate is optimal and no change is needed:
+- `price_spread_ratio <= 3`
+- `price_stddev < price_avg x 0.3`
+
+## Tier Gap Detection
+
+Sort all conditions by value and look for gaps between ranges. Gaps mean some cart totals have no matching rate, which can cause checkout failures.
+
+## Shipping Cost Sanity Check
+
+Any rate `amount > AOV x 0.15` (15% of average order value) should be flagged as a cart abandonment risk.

package/skills/wix-manage/references/ecommerce/setup-shipping-regions.md

@@ -0,0 +1,56 @@
+---
+name: "Setup: Shipping Regions"
+description: Configures delivery profiles and regions — creating profiles, adding regions with destinations, assigning carriers, enabling backup rates, and handling externally managed regions.
+layer: config
+---
+# Shipping Regions
+
+## Creating Delivery Profiles
+
+- The first profile is auto-created when Stores is installed.
+- Up to **99 profiles** per site.
+
+## Adding Regions
+
+- Up to **100 regions** per profile.
+- Each region requires: `name`, `destinations` (array of country codes), `active` flag.
+
+### Domestic Region
+
+Set `countryCode` to match `site_context.country`.
+
+### International Region
+
+Use multiple country codes, or leave `destinations` empty to represent "Rest of World."
+
+## Assigning Carriers
+
+- Up to **25 carriers** per region.
+- Use `appId` to identify the carrier.
+
+## Enabling Backup Rates
+
+CRITICAL -- set `backupRate.active = true` on each carrier. The backup rate amount should be **5-10% of effective AOV**.
+
+Without a backup rate, if the carrier service fails the shipping option silently disappears from checkout.
+
+## External Carrier Detection
+
+- Shippo `appId`: `2b1943e2-3fc2-47bc-be56-3d402e5966d7`
+- If **ALL** carriers in a region are external, skip that region -- it is externally managed.
+- If the region has a mix of external and Wix-native carriers, treat it as hybrid and only configure the Wix-native carriers.
+
+## Business Context Filter for International (MANDATORY)
+
+Check the site's industry. If it matches any of the following categories, DO NOT recommend international shipping:
+
+food, restaurant, grocery, bakery, catering, perishable, fresh, meat, produce, dairy, drink, beverage
+
+Perishable goods require cold chain logistics that standard international shipping does not support.
+
+## Identifying International Regions
+
+A region is considered "international" if any of the following are true:
+- Region name contains "international" or "internacional" (case-insensitive)
+- `destinations[]` is empty (Rest of World)
+- `destinations` include countries OTHER than the site country