@wix/agent-skills 1.0.0

package/skills/wix-manage/references/ecommerce/api-recommendation-tracking.md

@@ -0,0 +1,420 @@
+---
+name: "API: Recommendation Tracking"
+description: CRUD API for persisting and managing the lifecycle of AI-generated recommendations. Tracks state transitions from PROPOSED through APPROVED, EXECUTING, to DONE/FAILED/REJECTED. Every recommendation must be persisted here before presenting to the merchant.
+layer: config
+---
+# API: Recommendation Tracking Service
+
+This service persists recommendations in a database and tracks their lifecycle state. Every recommendation generated by any domain (discounts, shipping, etc.) **MUST** be persisted here before being presented to the merchant.
+
+**Service**: `wix.ecom.agentic.recommendations.v1.AgenticRecommendationsService`
+
+**Base URL**: `https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations`
+
+## How to call these APIs
+
+Use `CallWixSiteAPI` to invoke each endpoint:
+
+```
+CallWixSiteAPI(
+  url: "https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/<endpoint>",
+  method: "POST",
+  body: { ... }
+)
+```
+
+---
+
+## Data Model
+
+### Recommendation
+
+| Field | Type | Access | Description |
+|---|---|---|---|
+| `id` | string (GUID) | readOnly | Auto-generated unique identifier |
+| `revision` | int64 | readOnly | Optimistic lock — must match current value for state transitions |
+| `createdDate` | Timestamp | readOnly | When the recommendation was created |
+| `updatedDate` | Timestamp | readOnly | When the recommendation was last updated |
+| `title` | string | writable | Short human-readable title (max 200 chars) |
+| `reasoning` | string | writable | Why this recommendation is being made, citing specific data (max 2000 chars) |
+| `domain` | string | writable | Business domain: `"shipping"`, `"discounts"`, etc. (max 50 chars) |
+| `urgency` | enum | writable | `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW` |
+| `advice` | Advice | writable | The action to take (see below) |
+| `state` | enum | readOnly | Current lifecycle state (see State Machine) |
+| `expiresAt` | Timestamp | writable | When the recommendation auto-expires |
+| `conversationId` | string (GUID) | writable | Links all recommendations in a session |
+| `decidedBy` | string | readOnly | Who made the last state transition |
+| `rejectionReason` | string | readOnly | Reason for rejection (max 1000 chars) |
+| `rejectionPermanent` | boolean | readOnly | If true, this action type is permanently blocked for this site |
+| `executionResult` | ExecutionResult | readOnly | Result of execution (set on DONE/FAILED) |
+
+### Advice
+
+| Field | Type | Description |
+|---|---|---|
+| `action` | string | Action identifier (e.g., `"apply_discount"`, `"create_shipping_option"`) (max 100 chars) |
+| `params` | object | Domain-specific parameters (discount config, shipping option details, etc.) |
+| `successCriteria` | string | How to verify the action succeeded (max 500 chars) |
+
+### ExecutionResult
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | enum | `SUCCESS`, `PARTIAL_FAILURE`, or `FAILURE` |
+| `summary` | string | Description of what happened (max 2000 chars) |
+| `error` | string | Error message if failed (max 2000 chars) |
+| `resultPayload` | object | Additional result data |
+
+---
+
+## State Machine
+
+```
+PROPOSED → APPROVED → EXECUTING → DONE
+    │                      └──→ FAILED
+    ├──→ REJECTED
+    └──→ EXPIRED (scheduler)
+```
+
+| From | To | Trigger | API Method |
+|---|---|---|---|
+| — | PROPOSED | Recommendation created | BatchCreate / Create |
+| PROPOSED | APPROVED | Merchant approves | Approve |
+| PROPOSED | REJECTED | Merchant rejects | Reject |
+| PROPOSED | EXPIRED | `expiresAt` passed | Automatic (scheduler) |
+| PROPOSED | PROPOSED | Merchant modifies parameters | Update (state unchanged) |
+| APPROVED | EXECUTING | Execution begins | MarkExecuting |
+| EXECUTING | DONE | Execution succeeded | MarkDone |
+| EXECUTING | FAILED | Execution failed | MarkFailed |
+
+---
+
+## BatchCreate
+
+Creates multiple recommendations (1-100) atomically. All start in PROPOSED state. **Use this as the default** — always batch recommendations together.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/batch-create`
+
+**Request**:
+```json
+{
+  "agenticRecommendations": [
+    {
+      "title": "15% Off Electronics — Orders Over $200",
+      "reasoning": "AOV is $165. Electronics avg margin 42%. $200 threshold incentivizes adding one more item.",
+      "domain": "discounts",
+      "urgency": "HIGH",
+      "advice": {
+        "action": "apply_discount",
+        "params": {
+          "mechanism": "AUTOMATIC",
+          "scope": "CATEGORY",
+          "discountType": "PERCENTAGE",
+          "discount": 15,
+          "conditions": { "minSubTotal": 200 }
+        },
+        "successCriteria": "15% discount applied to Electronics for orders above $200"
+      }
+    }
+  ],
+  "conversationId": "<conversationId>"
+}
+```
+
+**Response**:
+```json
+{
+  "results": [
+    {
+      "agenticRecommendation": {
+        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+        "revision": "1",
+        "state": "PROPOSED",
+        "title": "15% Off Electronics — Orders Over $200",
+        "reasoning": "...",
+        "domain": "discounts",
+        "urgency": "HIGH",
+        "advice": { "..." : "..." },
+        "conversationId": "...",
+        "createdDate": "2026-05-10T10:00:00Z",
+        "updatedDate": "2026-05-10T10:00:00Z"
+      }
+    }
+  ]
+}
+```
+
+**Important**: Save the `id` and `revision` from each result — you need them for all subsequent state transitions.
+
+---
+
+## Create
+
+Creates a single recommendation in PROPOSED state. Prefer BatchCreate for multiple recommendations.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations`
+
+**Request**:
+```json
+{
+  "agenticRecommendation": {
+    "title": "Add Free Shipping for Orders Over $75",
+    "reasoning": "No free shipping option. delivery_step_cvr is 48%, below 65% benchmark. AOV is $62.",
+    "domain": "shipping",
+    "urgency": "HIGH",
+    "advice": {
+      "action": "create_shipping_option",
+      "params": {
+        "category": "free_shipping",
+        "ids": ["region-guid"],
+        "rates": [{ "amount": "0", "conditions": [{ "type": "BY_TOTAL_PRICE", "operator": "GTE", "value": "75" }] }]
+      },
+      "successCriteria": "Free shipping option created for orders above $75"
+    },
+    "conversationId": "<conversationId>"
+  }
+}
+```
+
+**Response**: Single `agenticRecommendation` object with `id`, `revision`, and `state: "PROPOSED"`.
+
+---
+
+## Query
+
+Query recommendations by conversation ID, state, or domain. Returns paginated results.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/query`
+
+**Request**:
+```json
+{
+  "query": {
+    "filter": {
+      "conversationId": "<conversationId>",
+      "state": { "$in": ["PROPOSED", "APPROVED"] }
+    },
+    "cursorPaging": { "limit": 50 }
+  }
+}
+```
+
+**Filterable fields**: `conversationId`, `state`, `domain`, `urgency`, `id`
+
+**Response**:
+```json
+{
+  "agenticRecommendations": [
+    {
+      "id": "a1b2c3d4-...",
+      "revision": "1",
+      "state": "PROPOSED",
+      "title": "...",
+      "domain": "discounts",
+      "urgency": "HIGH",
+      "advice": { "..." : "..." }
+    }
+  ],
+  "pagingMetadata": { "count": 1, "cursors": {}, "hasNext": false }
+}
+```
+
+---
+
+## Get
+
+Fetch a single recommendation by ID.
+
+**Endpoint**: `GET https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}`
+
+**Response**: Single `agenticRecommendation` object with all fields.
+
+---
+
+## Count
+
+Get recommendation counts grouped by state for the current site.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/count`
+
+**Request**: `{}`
+
+**Response**:
+```json
+{
+  "counts": {
+    "PROPOSED": 3,
+    "APPROVED": 1,
+    "EXECUTING": 0,
+    "DONE": 5,
+    "FAILED": 1,
+    "REJECTED": 2
+  }
+}
+```
+
+---
+
+## Update
+
+Update a PROPOSED recommendation. Only `title`, `reasoning`, `urgency`, `advice`, and `expiresAt` can be updated. State stays PROPOSED.
+
+**Endpoint**: `PATCH https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}`
+
+**Request**:
+```json
+{
+  "agenticRecommendation": {
+    "id": "a1b2c3d4-...",
+    "revision": "1",
+    "advice": {
+      "action": "apply_discount",
+      "params": { "discount": 20 },
+      "successCriteria": "20% discount applied"
+    }
+  },
+  "fieldMask": { "paths": ["advice"] }
+}
+```
+
+**Response**: Updated `agenticRecommendation` with incremented `revision`.
+
+**Constraint**: Only works on PROPOSED recommendations. Non-PROPOSED returns INVALID_STATE_TRANSITION.
+
+---
+
+## Approve
+
+PROPOSED → APPROVED. Call when the merchant agrees with a recommendation.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/approve`
+
+**Request**:
+```json
+{
+  "revision": "1"
+}
+```
+
+**Response**: Updated `agenticRecommendation` with `state: "APPROVED"` and incremented `revision`.
+
+---
+
+## Reject
+
+PROPOSED → REJECTED. Call when the merchant declines.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/reject`
+
+**Request**:
+```json
+{
+  "revision": "1",
+  "reason": "Merchant prefers flat-rate discount instead",
+  "permanent": false
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `revision` | int64 | Yes | Current revision for optimistic locking |
+| `reason` | string | No | Why the merchant rejected (max 1000 chars) |
+| `permanent` | boolean | No | If true, permanently blocks this action type for this site |
+
+**Response**: Updated `agenticRecommendation` with `state: "REJECTED"`.
+
+---
+
+## MarkExecuting
+
+APPROVED → EXECUTING. Call immediately before applying the recommendation.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/mark-executing`
+
+**Request**:
+```json
+{
+  "revision": "2"
+}
+```
+
+**Response**: Updated `agenticRecommendation` with `state: "EXECUTING"` and incremented `revision`.
+
+---
+
+## MarkDone
+
+EXECUTING → DONE. Call after the recommendation was successfully applied.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/mark-done`
+
+**Request**:
+```json
+{
+  "revision": "3",
+  "executionResult": {
+    "status": "SUCCESS",
+    "summary": "Created 15% discount rule for Electronics with $200 minimum"
+  }
+}
+```
+
+**Response**: Updated `agenticRecommendation` with `state: "DONE"` and `executionResult`.
+
+---
+
+## MarkFailed
+
+EXECUTING → FAILED. Call when execution fails.
+
+**Endpoint**: `POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/mark-failed`
+
+**Request**:
+```json
+{
+  "revision": "3",
+  "executionResult": {
+    "status": "FAILURE",
+    "summary": "Failed to create discount rule",
+    "error": "REVISION_MISMATCH: discount rule was modified by another process"
+  }
+}
+```
+
+**Response**: Updated `agenticRecommendation` with `state: "FAILED"` and `executionResult`.
+
+---
+
+## Error Codes
+
+| Error | HTTP | Meaning |
+|---|---|---|
+| RECOMMENDATION_SUPPRESSED | 400 | Action + site blocked by permanent rejection |
+| INVALID_STATE_TRANSITION | 400 | Wrong source state for the requested transition |
+| VERSION_MISMATCH | 400 | Optimistic lock conflict — re-fetch and retry |
+| RECOMMENDATION_NOT_FOUND | 404 | ID doesn't exist |
+
+On VERSION_MISMATCH: Query to get the latest revision, then retry the operation with the updated revision.
+
+---
+
+## Integration pattern for all recommendation flows
+
+Every recommendation flow MUST follow this lifecycle:
+
+```
+Step 1: Generate recommendations (domain-specific analysis)
+Step 2: BatchCreate → persist ALL recommendations as PROPOSED (save id + revision for each)
+Step 3: Present recommendations to merchant (include id + revision)
+Step 4: On each merchant action:
+  - APPROVE: Approve → MarkExecuting → apply the change → MarkDone or MarkFailed
+  - REJECT:  Reject (with reason, permanent flag)
+  - MODIFY:  Update (field mask) → stays PROPOSED → re-present
+```
+
+**Rules**:
+- Every recommendation MUST be persisted before presenting to the merchant
+- Always use the latest `revision` from the previous API response
+- Track ALL outcomes — both success (MarkDone) and failure (MarkFailed)
+- On VERSION_MISMATCH: re-fetch with Query, get latest revision, retry
+- Never skip the EXECUTING state — always call MarkExecuting before applying

package/skills/wix-manage/references/ecommerce/flow-add-free-shipping.md

@@ -0,0 +1,267 @@
+---
+name: "Flow: Add Free Shipping"
+description: Creates a free shipping option with an AOV-calibrated threshold to reduce cart abandonment and increase average order value. Validates threshold against catalog price distribution.
+layer: flow
+references:
+  - name: "Guardrail: Rate Pricing Sanity"
+    path: ecommerce/guardrail-rate-pricing-sanity.md
+    load: true
+  - name: "Setup: Shipping Rates"
+    path: ecommerce/setup-shipping-rates.md
+    load: true
+---
+# Flow: Add Free Shipping
+
+> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
+> - [Guardrail: Rate Pricing Sanity](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-rate-pricing-sanity)
+> - [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-rates)
+
+Adds a free shipping option with an optimal threshold calibrated against the site's average order value and catalog price distribution. Free shipping is the single most effective lever for reducing cart abandonment at the delivery step.
+
+## Prerequisites
+
+- Wix Stores (or another eCommerce business solution) installed on the site
+- Site metrics available (revenue, ordersCount) for AOV calculation
+- Catalog stats available (price quantiles) for threshold calibration
+- At least one active delivery region configured
+
+## Required APIs
+
+- [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)
+- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/shipping-options/update-shipping-option)
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles)
+
+---
+
+## Step 1: Check for existing free shipping
+
+Query all shipping options and check if free shipping already exists.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options/query`
+
+**Request**:
+```json
+{
+  "query": {
+    "cursorPaging": {
+      "limit": 100
+    }
+  }
+}
+```
+
+Scan the response for any option matching either condition:
+- `rates[].amount` equals `"0"`
+- `title` contains "free" (case-insensitive match)
+
+If free shipping already exists, proceed to Step 2 (threshold calibration check). If no free shipping exists, skip to Step 3.
+
+---
+
+## Step 2: Validate existing free shipping threshold
+
+If a free shipping option already exists, extract its threshold and validate it.
+
+### 2a: Extract the threshold
+
+Find the `BY_TOTAL_PRICE` `GTE` condition value from the free rate's `conditions[]` array.
+
+Example rate with threshold:
+```json
+{
+  "amount": "0",
+  "multiplyByQuantity": false,
+  "conditions": [
+    {
+      "type": "BY_TOTAL_PRICE",
+      "operator": "GTE",
+      "value": "75"
+    }
+  ]
+}
+```
+
+If there is no condition (unconditional free shipping), note this but do not flag it as an error -- the merchant may intentionally offer free shipping on all orders.
+
+### 2b: Evaluate threshold against AOV
+
+| Condition | Diagnosis | Recommendation |
+|---|---|---|
+| `threshold > AOV x 2` | Too high -- customers rarely qualify for free shipping | Lower the threshold to `AOV x 1.2` |
+| `threshold < AOV x 0.8` | Too low -- margin erosion risk, most orders qualify automatically | Raise the threshold to `AOV x 1.2` |
+| `AOV x 0.8 <= threshold <= AOV x 2` | Acceptable range | No change needed |
+
+If the threshold needs adjustment, update the shipping option via PATCH (see Step 5 for the update pattern).
+
+---
+
+## Step 3: Run AOV sanity check
+
+Before calculating a threshold, validate that AOV is reliable by comparing it against catalog price distribution.
+
+### 3a: Get catalog price statistics
+
+Use the catalog stats to retrieve price quantiles for the "All Products" category group:
+- `price_p25` -- 25th percentile product price
+- `price_p50` -- 50th percentile (median) product price
+- `price_p75` -- 75th percentile product price
+- `price_p90` -- 90th percentile product price
+
+### 3b: Determine effective_aov
+
+| Condition | Interpretation | Action |
+|---|---|---|
+| `AOV < price_p25` | Anomalous -- AOV is below 75% of product prices | Override: use `price_p50` as `effective_aov` |
+| `AOV > price_p90` | Possible bulk/combo orders | Use AOV but note the discrepancy |
+| `price_p25 <= AOV <= price_p90` | Reasonable | Use AOV as `effective_aov` |
+
+---
+
+## Step 4: Calculate optimal free shipping threshold
+
+Apply enhanced calibration using both `effective_aov` and catalog stats:
+
+| Condition | Threshold Formula | Rationale |
+|---|---|---|
+| `price_p75 > effective_aov x 1.5` | `price_p50 x 1.5` | High-price items skew the catalog; threshold encourages 2-item orders of mid-range products |
+| `price_p75 < effective_aov` | `effective_aov x 1.2` | Most products are lower-priced; threshold encourages adding items to cart |
+| Default (neither condition) | `max(effective_aov x 1.2, price_p75)` | Standard calibration balancing reach and margin |
+
+**Example calculation**:
+- `effective_aov` = $60
+- `price_p50` = $35, `price_p75` = $55
+- `price_p75 ($55) < effective_aov ($60)` --> use `effective_aov x 1.2` = $72
+- Threshold = $72
+
+---
+
+## Step 5: Identify the target delivery region
+
+Query delivery profiles to find the primary/domestic active region.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/query`
+
+**Request**:
+```json
+{
+  "query": {
+    "cursorPaging": {
+      "limit": 100
+    }
+  }
+}
+```
+
+Select the region where:
+1. `active=true`
+2. `destinations[].countryCode` matches the site's primary country
+3. Falls within the default delivery profile
+
+Save the region's `id` as the `deliveryRegionId` for the new option.
+
+---
+
+## Step 6: Create the free shipping option
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options`
+
+**Request**:
+```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": "72"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**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": "Free Shipping",
+    "estimatedDeliveryTime": "5-7 business days",
+    "rates": [
+      {
+        "amount": "0",
+        "conditions": [
+          {
+            "type": "BY_TOTAL_PRICE",
+            "operator": "GTE",
+            "value": "72"
+          }
+        ],
+        "multiplyByQuantity": false
+      }
+    ]
+  }
+}
+```
+
+**Key field rules**:
+
+| Field | Value | Notes |
+|---|---|---|
+| `title` | `"Free Shipping"` | Display name at checkout |
+| `estimatedDeliveryTime` | `"5-7 business days"` | Always populate -- never leave empty |
+| `deliveryRegionId` | Region UUID | Use singular field, not `deliveryRegionIds` |
+| `rates[].amount` | `"0"` | Decimal string for free |
+| `rates[].multiplyByQuantity` | `false` | Always false for free shipping |
+| `rates[].conditions[].type` | `"BY_TOTAL_PRICE"` | Cart total threshold |
+| `rates[].conditions[].operator` | `"GTE"` | Greater than or equal to |
+| `rates[].conditions[].value` | Threshold as string | Calculated in Step 4 |
+
+---
+
+## Step 7: Verify the option appears in checkout
+
+Re-query shipping options to confirm the new free shipping option is live.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options/query`
+
+Verify:
+1. The new option appears with `title: "Free Shipping"` and `amount: "0"`
+2. The condition shows the correct threshold value
+3. The option is linked to the correct `deliveryRegionId`
+4. The linked region has `active=true` in its delivery profile
+
+Report to the merchant:
+> "Free shipping created with a $[threshold] minimum order. Customers spending $[threshold] or more will see free shipping at checkout. This threshold is calibrated to your average order value to encourage larger carts while protecting margins."
+
+---
+
+## Error Handling
+
+| Error | Cause | Fix |
+|---|---|---|
+| `deliveryRegionId is not a valid GUID` | Used `deliveryRegionIds` (plural) instead of `deliveryRegionId` (singular) | Use the singular `deliveryRegionId` field |
+| `SHIPPING_OPTION_NOT_FOUND` | Option ID doesn't exist when trying to update | Re-query shipping options to get current IDs |
+| `REVISION_MISMATCH` | Revision doesn't match the current version when updating | Re-fetch the option for the latest revision, then retry |
+| Threshold seems unreasonable | AOV data is unreliable (too few orders, data anomaly) | Run the AOV sanity check (Step 3) and use `effective_aov` instead of raw AOV |
+| Free shipping not visible at checkout | Region linked to the option has `active=false` | Check region active status and activate if intended |
+
+## 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)