@wix/agent-skills 1.0.0

package/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md

@@ -0,0 +1,209 @@
+---
+name: "Setup: Store Pickup Location"
+description: Configures a pickup option for an online store so customers can choose in-store pickup at checkout. Uses the Delivery Profiles API to discover the Pickup carrier, add a delivery region, and attach the carrier with a free pickup rate.
+---
+# Set Up Store Pickup Location
+
+## Prerequisites
+
+- Wix Stores (or another eCommerce business solution) installed on the site
+- The **Pickup** carrier must be installed on the site (it is a built-in carrier, not a third-party app)
+
+## Required APIs
+
+- [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/list-installed-delivery-carriers)
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles)
+- [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-region)
+- [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-carrier)
+
+---
+
+## Step 1: Discover the Pickup carrier
+
+Call [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/list-installed-delivery-carriers) to find the Pickup carrier's `id`.
+
+**Endpoint**: `GET https://www.wixapis.com/ecom/v1/delivery-profiles/installed-carriers`
+
+**Response**:
+```json
+{
+  "installedDeliveryCarriers": [
+    {
+      "id": "50d8c12f-715e-41ad-be25-d0f61375dbee",
+      "displayName": "Pickup",
+      "fallbackDefinitionMandatory": false,
+      "toggleGetCarrierSettingsEnabled": true
+    },
+    {
+      "id": "45c44b27-ca7b-4891-8c0d-1747d588b835",
+      "displayName": "Basic Shipping",
+      "description": "Manage shipping rates and options for this region",
+      "fallbackDefinitionMandatory": false,
+      "toggleGetCarrierSettingsEnabled": true
+    }
+  ]
+}
+```
+
+Look for the carrier with `"displayName": "Pickup"` and save its `id`. This is the `appId` you will use in Step 4.
+
+If no Pickup carrier appears in the list, the Pickup app is not installed on the site and must be installed before proceeding.
+
+---
+
+## Step 2: Find the default delivery profile
+
+Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles) to retrieve the site's default delivery profile.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/query`
+
+**Request**:
+```json
+{}
+```
+
+The response contains an array of `deliveryProfiles`. Find the one where `"default": true`. Save its `id` and `revision`. Inspect its `deliveryRegions` array.
+
+**Decision point:**
+- **Region exists for the user's country** (match on `destinations[].countryCode`): save that region's `id` → skip to Step 4.
+- **No matching region**: proceed to Step 3.
+
+---
+
+## Step 3: Add a delivery region for the pickup country
+
+If no region exists for the user's country in the default profile, call [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-region) to create one.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region`
+
+Replace `{deliveryProfileId}` with the default profile's `id` from Step 2.
+
+**Request**:
+```json
+{
+  "deliveryRegion": {
+    "name": "US Pickup",
+    "active": true,
+    "destinations": [
+      {
+        "countryCode": "US"
+      }
+    ]
+  },
+  "revision": "3"
+}
+```
+
+- `name`: descriptive, e.g. `"{Country} Pickup"`.
+- `countryCode`: [ISO-3166 alpha-2](https://www.iso.org/obp/ui/#search/code/) code (e.g. `"US"`, `"IL"`, `"DE"`, `"GB"`).
+- `revision`: from the profile returned in Step 2.
+
+**Response**:
+```json
+{
+  "deliveryProfile": {
+    "id": "02625bf4-70b4-49b7-93f0-5c9d72608937",
+    "name": "General profile",
+    "default": true,
+    "deliveryRegions": [
+      {
+        "id": "23823d4a-0ad2-4f92-a48a-467497a9470a",
+        "name": "US Pickup",
+        "active": true,
+        "deliveryCarriers": [],
+        "destinations": [
+          {
+            "countryCode": "US",
+            "subdivisions": []
+          }
+        ]
+      }
+    ],
+    "revision": "4"
+  }
+}
+```
+
+Save the new region's `id` from the response.
+
+---
+
+## Step 4: Add the Pickup carrier to the region
+
+Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/add-delivery-carrier) to attach the Pickup carrier to the delivery region.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/add-delivery-carrier`
+
+**Request**:
+```json
+{
+  "deliveryRegionId": "<REGION_ID>",
+  "deliveryCarrier": {
+    "appId": "50d8c12f-715e-41ad-be25-d0f61375dbee",
+    "backupRate": {
+      "title": "Pickup at 123 Main St, New York",
+      "amount": "0",
+      "active": true
+    }
+  }
+}
+```
+
+- `deliveryRegionId`: from Step 2 (existing region) or Step 3 (new region).
+- `appId`: the Pickup carrier `id` from Step 1.
+- `backupRate.title`: the pickup address customers see at checkout.
+- `backupRate.amount`: `"0"` for free pickup, or a price string like `"5.00"`.
+- `backupRate.active`: must be `true` for the option to appear at checkout.
+
+**Response**:
+```json
+{
+  "deliveryProfile": {
+    "id": "02625bf4-70b4-49b7-93f0-5c9d72608937",
+    "name": "General profile",
+    "default": true,
+    "deliveryRegions": [
+      {
+        "id": "23823d4a-0ad2-4f92-a48a-467497a9470a",
+        "name": "US Pickup",
+        "active": true,
+        "deliveryCarriers": [
+          {
+            "appId": "50d8c12f-715e-41ad-be25-d0f61375dbee",
+            "backupRate": {
+              "title": "Pickup at 123 Main St, New York",
+              "amount": "0",
+              "active": true
+            },
+            "additionalCharges": []
+          }
+        ],
+        "destinations": [
+          {
+            "countryCode": "US",
+            "subdivisions": []
+          }
+        ]
+      }
+    ],
+    "revision": "5"
+  }
+}
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `DESTINATIONS_COLLISION` | The country is already assigned to another region in the same profile. | Skip Step 3 — use the existing region's `id` and add the carrier to it in Step 4. |
+| `CARRIER_ALREADY_EXISTS_IN_REGION` | The Pickup carrier is already configured in this region. | The pickup option is already set up. No action needed. |
+| `DELIVERY_CARRIER_MISSING_BACKUP_RATE` | The `backupRate` or `backupRate.amount` field is missing. | Ensure `backupRate` includes `title`, `amount`, and `active`. |
+
+---
+
+## Related Documentation
+
+- [Delivery Profiles: Introduction](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/introduction)
+- [Delivery Profiles: Sample Flows](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/sample-flows)

package/skills/wix-manage/references/ecommerce/skill-graph.md

@@ -0,0 +1,139 @@
+---
+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
+    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 / ReadFullDocsArticle"| 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"]
+        S1["Delivery Profiles API"]
+        S2["Shipping Options API"]
+        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 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 |
+| `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

@@ -0,0 +1,124 @@
+---
+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 |

package/skills/wix-manage/references/ecommerce/troubleshoot-discount-not-applying.md

@@ -0,0 +1,95 @@
+---
+name: "Troubleshoot: Discount Not Applying"
+description: Diagnostic tree for when a discount rule exists but isn't applying at checkout. Checks active status, time window, scope targeting, revision, and app installation.
+layer: troubleshoot
+---
+# Troubleshoot: Discount Not Applying
+
+## When to use
+
+Use this diagnostic tree when a merchant reports that a discount rule exists but products are not showing the discounted price at checkout or in the storefront.
+
+---
+
+## Step 1: Check rule active status
+
+Query the discount rule by ID and verify the `active` field.
+
+- If `active: false` → **Resolution**: "The rule is deactivated. Set `active: true` to enable it."
+- If `active: true` → proceed to Step 2.
+
+---
+
+## Step 2: Check time window
+
+Examine the `activeTimeInfo` field on the discount rule.
+
+- If `activeTimeInfo` does not exist → the rule has no time constraints, proceed to Step 3.
+- If `activeTimeInfo` exists:
+  - Is the current date/time within the `start` and `end` range?
+  - If the current date is before `start` → **Resolution**: "The campaign hasn't started yet. It begins on {startDate}."
+  - If the current date is after `end` → **Resolution**: "The campaign ended on {endDate}. Update or remove the time window to re-enable."
+  - If within range → proceed to Step 3.
+
+---
+
+## Step 3: Check scope targeting
+
+Examine the discount rule's scope configuration:
+
+### CATALOG scope
+- Should apply to all products. If it's not applying, skip to Step 5 (app installation check).
+
+### COLLECTION scope
+- Verify that `categoryIds` contain valid GUIDs, not collection names.
+- Common mistake: using the collection name string instead of its GUID.
+- Call `getCategoryIds` or query collections to validate that each ID resolves to an existing collection.
+- If any ID is invalid → **Resolution**: "The collection ID '{id}' does not match any existing collection. Use the collection GUID, not the display name."
+
+### SPECIFIC_PRODUCTS scope
+- Verify that each `productId` in the rule exists in the store catalog.
+- Query products to confirm each ID resolves.
+- If any product was deleted → **Resolution**: "Product '{id}' no longer exists in the catalog. Remove it from the discount rule or replace it with a valid product ID."
+
+---
+
+## Step 4: Check revision
+
+Was the rule recently updated? A revision mismatch indicates the update failed silently.
+
+- Query the current rule and compare the `revision` field against the expected value.
+- If the revision does not match what was expected after an update → **Resolution**: "The last update to this rule may have failed. The current revision is {currentRevision}. Try updating the rule again with the correct revision number."
+
+---
+
+## Step 5: Check app installation
+
+Is the Wix Stores or eCommerce app installed on the site?
+
+- Error code `WDE0110: Wix Code not enabled` → **Resolution**: "The Wix Stores app is not installed. Install Wix Stores first, then the discount rule will take effect."
+- If the eCommerce platform is not fully set up, discount rules cannot be evaluated at checkout.
+
+---
+
+## Step 6: Check stacking interference
+
+Are other active discount rules conflicting with or overriding this one?
+
+1. Query all active discount rules.
+2. Check for scope overlap with the problematic rule.
+3. Some discount combinations may cause unexpected behavior where one rule appears to "not apply" because another rule takes precedence.
+
+**Resolution**: "There are {count} other active discount rules that overlap with this rule's scope. Review them to check if another rule is taking priority or if stacking behavior is masking this rule's effect."
+
+---
+
+## Summary: Diagnostic checklist
+
+| Step | Check | Common resolution |
+|---|---|---|
+| 1 | `active` field | Set `active: true` |
+| 2 | Time window | Update or remove expired `activeTimeInfo` |
+| 3 | Scope targeting | Fix invalid collection/product GUIDs |
+| 4 | Revision mismatch | Retry the update with correct revision |
+| 5 | App installation | Install Wix Stores app |
+| 6 | Stacking interference | Review and resolve overlapping rules |