@wix/agent-skills 1.12.0 → 1.14.0

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

@@ -1,298 +0,0 @@
----
-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/skills/api-shipping#query-delivery-profiles)
-- [Get Delivery Profile](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#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/skills/api-shipping#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
-
-- [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

@@ -1,139 +0,0 @@
----
-name: "eCommerce Skill Graph"
-description: Mermaid diagram showing how eCommerce skills connect — unified strategy entry point, goal/flow/guardrail chain, tracking inlined, troubleshoot as direct entries.
----
-
-## Skill Graph Diagram
-
-```mermaid
-flowchart TB
-    MR["Merchant Request"] --> R
-
-    subgraph R["R — Unified Entry Point"]
-        recommend-ecommerce-strategy
-    end
-
-    R --> |"loads API ref"| Config
-    R --> |"Step 4b: loads matching goal"| Goals
-    R --> |"Step 2+8: tracking inlined"| TrackingAPI
-
-    subgraph Goals["Goals — Business Objectives"]
-        subgraph GD["Discount + Shipping"]
-            goal-increase-aov
-            goal-clear-inventory
-            goal-seasonal-revenue
-            goal-drive-cross-sells
-        end
-        subgraph GA["Abandoned Cart"]
-            goal-reduce-cart-abandonment
-        end
-    end
-
-    Goals --> |"loads matching flows"| Flows
-    goal-increase-aov --> |"also loads shipping flows"| FS
-
-    subgraph Flows["Flows — Business Logic"]
-        subgraph FD["Discount"]
-            flow-upsell-boost
-            flow-bundle-and-save
-            flow-stock-mover
-            flow-seasonal-promotion
-        end
-        subgraph FS["Shipping"]
-            flow-fix-coverage-gaps
-            flow-add-free-shipping
-            flow-optimize-shipping-rates
-        end
-    end
-
-    Flows --> |"loads validation"| Guardrails
-    Flows --> |"loads setup"| Config
-
-    subgraph Guardrails["Cross-cutting: Guardrails"]
-        guardrail-discount-conflicts
-        guardrail-margin-protection
-        guardrail-shipping-health
-        guardrail-rate-pricing-sanity
-    end
-
-    subgraph Config["Config — Setup & API References"]
-        setup-discount-rules
-        setup-coupons
-        setup-shipping-regions
-        setup-shipping-rates
-        api-shipping
-    end
-
-    subgraph TrackingAPI["Tracking API"]
-        api-recommendation-tracking
-    end
-
-    subgraph Standalone["Direct Entry Points (from README)"]
-        recipe-apply-shipping-recommendations
-        setup-store-pickup-location
-        troubleshoot-discount-not-applying
-        troubleshoot-checkout-delivery-dropoff
-    end
-
-    Config -.-> |"calls via CallWixSiteAPI"| API
-
-    subgraph API["Wix REST API Docs (dev.wix.com)"]
-        D1["Discount Rules API"]
-        D2["Coupons API"]
-        D3["Products V3 API"]
-        D4["Categories API"]
-        D5["Catalog Analytics"]
-        S3["Pickup Locations API"]
-        S4["Local Delivery API"]
-        SD["Profile Service API (wix-profile-client)"]
-    end
-
-    classDef goal fill:#8b5cf6,stroke:#6d28d9,color:#fff
-    classDef guardrail fill:#ef4444,stroke:#dc2626,color:#fff
-    classDef flow fill:#3b82f6,stroke:#2563eb,color:#fff
-    classDef config fill:#f59e0b,stroke:#d97706,color:#fff
-    classDef reco fill:#ec4899,stroke:#db2777,color:#fff
-    classDef standalone fill:#6b7280,stroke:#4b5563,color:#fff
-    classDef apidoc fill:#e5e7eb,stroke:#9ca3af,color:#374151
-
-    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,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
-```
-
-## File Reachability
-
-| File | Reached via |
-|---|---|
-| `recommend-ecommerce-strategy.md` | README routing (entry point) |
-| `api-recommendation-tracking.md` | Entry point tracking steps |
-| `goal-increase-aov.md` | Step 4b (UPSELL_BOOST) |
-| `goal-clear-inventory.md` | Step 4b (STOCK_MOVER) |
-| `goal-seasonal-revenue.md` | Step 4b (SEASONAL) |
-| `goal-drive-cross-sells.md` | Step 4b (BUNDLE_AND_SAVE) |
-| `goal-reduce-cart-abandonment.md` | Step 4b (ABANDONED_CART domain) |
-| `flow-upsell-boost.md` | goal-increase-aov chain |
-| `flow-bundle-and-save.md` | goal-increase-aov / goal-drive-cross-sells chain |
-| `flow-stock-mover.md` | goal-clear-inventory chain |
-| `flow-seasonal-promotion.md` | goal-seasonal-revenue chain |
-| `flow-fix-coverage-gaps.md` | goal-reduce-cart-abandonment chain (critical operational fix) |
-| `flow-add-free-shipping.md` | goal-increase-aov chain (shipping flows serving AOV) |
-| `flow-optimize-shipping-rates.md` | goal-increase-aov chain (shipping flows serving AOV) |
-| `guardrail-discount-conflicts.md` | flow-upsell-boost / bundle / stock / seasonal chains |
-| `guardrail-margin-protection.md` | flow-upsell-boost / stock-mover chains |
-| `guardrail-shipping-health.md` | flow-fix-coverage-gaps chain |
-| `guardrail-rate-pricing-sanity.md` | flow-add-free-shipping / optimize chains |
-| `setup-discount-rules.md` | All discount flow chains |
-| `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 |
-| `troubleshoot-checkout-delivery-dropoff.md` | README direct entry |
-| `skill-graph.md` | Documentation reference |

package/skills/wix-manage/references/ecommerce/troubleshoot-checkout-delivery-dropoff.md

@@ -1,124 +0,0 @@
----
-name: "Troubleshoot: Checkout Delivery Drop-off"
-description: Diagnostic tree for when delivery step conversion is below benchmark. Correlates shipping issues with checkout abandonment and calculates revenue impact.
-layer: troubleshoot
----
-# Troubleshoot: Checkout Delivery Drop-off
-
-## When to use
-
-Use this diagnostic tree when analyzing checkout funnel performance and the delivery step shows elevated abandonment. The delivery step is where customers choose their shipping method — drop-off here directly indicates shipping-related friction.
-
----
-
-## Step 1: Check delivery step conversion rate
-
-Compare `delivery_step_cvr` against the benchmark of **65%**.
-
-### Interpretation
-
-| CVR range | Interpretation | Action |
-|---|---|---|
-| cvr < benchmark (65%) AND shipping issues detected | Correlate specific issues to conversion drop | Proceed to full diagnostic |
-| cvr ≥ benchmark (65%) | Do NOT cite CVR gap as justification | Focus on best practices, not recovery |
-| cvr ≥ 90% | Excellent — note strong performance | Focus on maintaining, not fixing |
-
-**Important**: If the CVR is at or above benchmark, do not frame recommendations as fixing a conversion problem. Only cite CVR gap when the data supports it.
-
----
-
-## Step 2: Calculate revenue impact
-
-Use this formula to quantify the business impact of the delivery step drop-off:
-
-```
-revenue_impact = (benchmark_delivery_cvr - delivery_step_cvr) / 100 × total_checkouts × aov
-```
-
-**Example**: If benchmark is 65%, current CVR is 55%, with 2,000 checkouts/month and $80 AOV:
-- `(65 - 55) / 100 × 2000 × 80 = $16,000/month` in potential lost revenue.
-
-### High traffic amplifier
-
-If `visitors > 30,000` (approximately 1,000+ per day) AND a HIGH-severity shipping issue is detected, include a daily revenue impact estimate to emphasize urgency:
-
-```
-daily_impact = revenue_impact / 30
-```
-
-> "At your traffic volume, this shipping issue may be costing approximately ${daily_impact} per day."
-
----
-
-## Step 3: Assign priority
-
-Based on the gap between current CVR and benchmark:
-
-| Gap | Priority | Urgency |
-|---|---|---|
-| Gap > 10 percentage points | **HIGH** | Address immediately — significant revenue loss |
-| Gap 5-10 percentage points | **MEDIUM** | Address soon — meaningful improvement opportunity |
-| Gap < 5 percentage points | **LOW** | Optimize when convenient — incremental gains |
-
----
-
-## Step 4: Identify common causes
-
-Check for these known shipping issues that correlate with delivery step drop-off:
-
-1. **No free shipping option**: Stores without any free shipping option see higher delivery-step abandonment. Customers expect at least a conditional free shipping tier.
-
-2. **Missing delivery estimates**: Shipping options without estimated delivery times create uncertainty. Customers abandon when they don't know when their order will arrive.
-
-3. **Per-item pricing (`multiplyByQuantity`)**: Customers adding multiple items see shipping costs spike unexpectedly at checkout.
-
-4. **Coverage gaps**: Customer's delivery address falls outside configured shipping regions. The checkout shows no available shipping methods.
-
-5. **Inactive backup rates**: When the primary carrier can't fulfill and no backup rate is configured, the customer sees no shipping options.
-
-6. **Options on inactive regions**: Shipping options configured for regions that are set to `active: false` are not available at checkout.
-
----
-
-## Step 5: Run diagnostic sequence
-
-Follow this sequence to systematically identify the root cause:
-
-### 5.1 Check configuration completeness
-- Are delivery profiles configured?
-- Are regions active?
-- Are shipping options assigned to active regions?
-
-### 5.2 Check coverage gaps
-- Do the configured regions cover the store's primary customer geographies?
-- Are there common destination countries/states missing from region definitions?
-
-### 5.3 Check free shipping presence
-- Is there at least one free shipping option (unconditional or threshold-based)?
-- If threshold-based, is the threshold achievable relative to AOV?
-
-### 5.4 Check rate pricing sanity
-- Are any rates exceeding 15% of AOV?
-- Is `multiplyByQuantity` enabled on any rate?
-- See the **Guardrail: Rate Pricing Sanity** skill for detailed checks.
-
-### 5.5 Check backup rates
-- Are backup rates configured on carriers?
-- Are backup rate amounts reasonable (5-10% of AOV)?
-
-### 5.6 Correlate findings with CVR impact
-- For each issue found, estimate its contribution to the CVR gap.
-- Prioritize fixes by expected conversion recovery.
-- Present findings in order of impact, with revenue estimates where possible.
-
----
-
-## Summary: Diagnostic checklist
-
-| Step | Check | What to look for |
-|---|---|---|
-| 1 | CVR vs benchmark | Is there actually a gap to address? |
-| 2 | Revenue impact | Quantify the business cost |
-| 3 | Priority | HIGH (>10pt gap), MEDIUM (5-10pt), LOW (<5pt) |
-| 4 | Common causes | Free shipping, estimates, per-item, coverage, backups |
-| 5 | Diagnostic sequence | Config → coverage → free shipping → rates → backups → correlate |