@wix/agent-skills 1.12.0 → 1.13.0

package/skills/wix-manage/references/ecommerce/{goal-increase-aov.md → pricing-promotions/ecom-pricing-goal-increase-aov.md}

@@ -1,36 +1,25 @@
 ---
 name: "Goal: Increase AOV"
-description: Maps the UPSELL_BOOST business goal to measurable KPIs and actionable discount flows. Covers AOV benchmarking, margin-based discount tiers, and minSubTotal strategy.
-layer: goal
-references:
-  - name: "Flow: Upsell Boost"
-    path: ecommerce/flow-upsell-boost.md
-    load: true
-  - name: "Flow: Bundle and Save"
-    path: ecommerce/flow-bundle-and-save.md
-    load: true
-  - name: "Flow: Add Free Shipping"
-    path: ecommerce/flow-add-free-shipping.md
-    load: false
-  - name: "Flow: Optimize Shipping Rates"
-    path: ecommerce/flow-optimize-shipping-rates.md
-    load: false
-  - name: "Guardrail: Margin Protection"
-    path: ecommerce/guardrail-margin-protection.md
-    load: false
+description: UPSELL_BOOST goal — always load BEFORE recommending AOV / upsell / "boost my sales" / shipping-threshold actions. Owns the cross-domain lever map (discount + shipping + bundle) for open-ended sales prompts.
 ---
 # Goal: Increase Average Order Value
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Flow: Upsell Boost](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-upsell-boost)
-> - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save)
+> **Routing rule (READ FIRST).** Any merchant query about increasing AOV, upselling, "boosting sales", or open-ended "help my business" prompts MUST load this recipe before any flow-* recipe. Do NOT route directly to [Flow: Upsell Boost](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-upsell-boost) from the WixREADME index — this goal owns the cross-domain lever map (discount + shipping + bundle), the catalog→lever-selection rules, and the per-recommendation **multi-lever mix requirement** that an open "boost sales" prompt must satisfy. The flows are sub-steps.
+>
+> ⛔ **MANDATORY — call these NOW before any API call or recommendation generation:**
+> ```
+> ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-upsell-boost")
+> ```
+> If the request covers bundle/cross-sell intent too:
+> ```
+> ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save")
+> ```
 >
 > **Shipping flows that also serve AOV goals** (load if shipping domain is active):
-> - [Flow: Add Free Shipping](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-add-free-shipping) — free shipping threshold pushes carts above AOV
-> - [Flow: Optimize Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-optimize-shipping-rates) — rate optimization improves conversion on higher-value orders
+> - [Flow: Add Free Shipping](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-add-free-shipping) — free shipping threshold pushes carts above AOV
+> - [Flow: Optimize Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — rate optimization improves conversion on higher-value orders
 >
-> **Related skills** (read with `ReadFullDocsArticle` if needed):
-> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection)
+> The margin/cap guardrails are enforced in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails".
 
 Incentivize customers to spend above the store's current average order value (AOV) by creating threshold-based discounts that reward higher cart totals.
 
@@ -96,6 +85,24 @@ A complementary action that increases AOV by encouraging multi-item purchases. I
 
 ---
 
+## Presentation requirement — open prompts demand a multi-lever mix
+
+When the merchant's query is open-ended (e.g., "boost my sales", "help my business", "give me 3 to 5 actions"), the recommendation set **MUST mix at least two of the following lever types** — never propose an all-discount set:
+
+| Lever type | Example action |
+|---|---|
+| Discount rule (auto-apply) | `apply_discount` with `minSubTotal` above AOV |
+| Coupon | code-gated discount for subscribers / influencers |
+| Free-shipping / shipping change | `create_shipping_option` with AOV-calibrated threshold |
+| Bundle / `minItemQuantity` rule | multi-item discount targeting cross-sell categories |
+| `minSubTotal` / AOV-threshold rule | spend-based discount above current AOV |
+
+State the lever type per recommendation in the `reasoning` / `why` field (e.g., "Lever: free-shipping threshold — pushes carts above current AOV $X"). A recommendation set containing only `apply_discount` actions FAILS the UPSELL_BOOST goal's open-prompt intent.
+
+If the merchant's prompt names a specific lever (e.g., "give me a coupon"), this rule does NOT apply — focus all recommendations on that lever. The multi-lever requirement is for OPEN prompts where the lever is the agent's call.
+
+---
+
 ## Measurement Plan
 
 ### Before campaign launch

package/skills/wix-manage/references/ecommerce/{goal-seasonal-revenue.md → pricing-promotions/ecom-pricing-goal-seasonal-revenue.md}

@@ -1,16 +1,16 @@
 ---
 name: "Goal: Seasonal Revenue"
-description: Maps the SEASONAL business goal to event-driven revenue KPIs and promotional flows.
-layer: goal
-references:
-  - name: "Flow: Seasonal Promotion"
-    path: ecommerce/flow-seasonal-promotion.md
-    load: true
+description: SEASONAL goal — always load BEFORE recommending any holiday / event / date-tied promotion. Owns the priority rule (holiday beats UPSELL_BOOST when both signals are present).
 ---
 # Goal: Capitalize on Seasonal Events
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Flow: Seasonal Promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-seasonal-promotion)
+> **Routing rule (READ FIRST).** Any merchant query that mentions a holiday, cultural event, season, or specific date tied to a discount MUST load this recipe before any flow-* recipe. Do NOT route directly to [Flow: Seasonal Promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-seasonal-promotion) from the WixREADME index — this goal owns the **priority rule** ("holiday/event/date beats all other signals — even 'maximize revenue' / 'boost sales' must classify as SEASONAL when a date is named"), the event calendar, and the per-recommendation time-window presentation rules. The flow is a sub-step.
+>
+> ⛔ **MANDATORY — call this NOW before any API call or recommendation generation:**
+> ```
+> ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-seasonal-promotion")
+> ```
+> Do NOT skip this or defer it — the flow defines the event calendar, campaign window calculation, and discount-sizing logic required to produce correct seasonal recommendations.
 
 Capitalize on holidays, cultural events, and seasonal moments to drive revenue spikes through time-limited promotional campaigns.
 
@@ -107,6 +107,19 @@ For quick, high-urgency promotions with short windows (24-72 hours). Creates imm
 
 ---
 
+## Presentation requirement — every recommendation MUST carry a time window
+
+**Every seasonal recommendation presented to the merchant MUST include an explicit campaign window** in its `reasoning` / `why` field — either `startDate` + `endDate` in the rule params, or a duration phrase in the human-readable reasoning. The merchant must be able to see, per recommendation, when it activates and when it expires.
+
+Acceptable phrasings:
+- "Runs Nov 25 – Dec 1 (Black Friday weekend)."
+- "Campaign window: 7 days starting Dec 18; ends Christmas Eve."
+- "Active from event launch through Cyber Monday (Nov 28)."
+
+A seasonal recommendation with no time window is NOT acceptable — even if everything else is correct, the absence of a window means the discount runs indefinitely and defeats the seasonal framing. If you cannot determine a window for an item, drop it; never present a windowless seasonal recommendation.
+
+---
+
 ## Measurement Plan
 
 ### Before campaign launch

package/skills/wix-manage/references/ecommerce/{troubleshoot-discount-not-applying.md → pricing-promotions/ecom-pricing-troubleshoot-not-applying.md}

@@ -1,5 +1,5 @@
 ---
-name: "Troubleshoot: Discount Not Applying"
+name: "Pricing: 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
 ---

package/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md

@@ -18,25 +18,27 @@ references:
   - name: "Goal: Drive Cross-Sells"
     path: ecommerce/goal-drive-cross-sells.md
     load: false
-  - name: "Goal: Reduce Cart Abandonment"
-    path: ecommerce/goal-reduce-cart-abandonment.md
-    load: false
   - name: "Setup: Coupons"
     path: ecommerce/setup-coupons.md
     load: false
 ---
 # Recommend: eCommerce Strategy
 
+> ⛔ **MANDATORY PRE-STEP — do this BEFORE Step 1 (before any API call).**
+>
+> Classify the merchant's request and immediately call `ReadFullDocsArticle` on the matching goal skill. Do NOT gather data first — the goal skill tells you which metrics to pull and what guardrails to apply.
+>
+> | Merchant intent | Goal to load |
+> |---|---|
+> | Holiday / event / date mentioned | `ReadFullDocsArticle` → [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue) |
+> | "increase AOV", "spend more", "upsell", "boost sales", generic sales improvement | `ReadFullDocsArticle` → [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov) |
+> | "clear inventory", "overstock", "clearance", "slow-moving" | `ReadFullDocsArticle` → [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory) |
+> | "bundle", "cross-sell", "buy together", "more items per order" | `ReadFullDocsArticle` → [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells) |
 >
-> **After classifying domains in Step 4b**, load the matching goal skill with `ReadFullDocsArticle`:
-> - **SEASONAL** → [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue)
-> - **UPSELL_BOOST** / **SHIPPING** → [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov) (includes both discount and shipping flows)
-> - **STOCK_MOVER** → [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory)
-> - **BUNDLE_AND_SAVE** → [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells)
-> - **ABANDONED_CART** → [Goal: Reduce Cart Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-reduce-cart-abandonment)
+> After loading the goal skill, continue from Step 1 below. The goal skill will instruct you to load the matching flow skill — follow those instructions too.
 >
-> **If COUPON mechanism in Step 4c**, load:
-> - [Setup: Coupons](https://dev.wix.com/docs/api-reference/business-solutions/coupons)
+> **If COUPON mechanism in Step 4c**, also load:
+> - [Pricing: Create Coupon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-coupon)
 
 ## EXECUTION RULES — READ BEFORE ANYTHING ELSE
 
@@ -179,7 +181,6 @@ Based on the merchant's request AND the site data, determine which domains to an
 |---|---|---|
 | **DISCOUNTS** | Merchant mentions sales, promotions, revenue, AOV, clearance, holidays, coupons. **Also activate if no specific domain is mentioned** (default). | Always — site data contains discount metrics |
 | **SHIPPING** | Merchant mentions shipping, delivery, checkout conversion, cart abandonment. **Also activate proactively** if site data suggests shipping issues. | High visitors + low orders may indicate shipping friction |
-| **ABANDONED_CART** | Activate proactively if site data shows abandoned carts with no active recovery automation. No merchant trigger needed — detect from data. | `currentDiscounts` empty or no cart recovery automation visible |
 
 **Priority rule**: If the merchant mentions a specific holiday/event/date, the DISCOUNTS domain MUST use the **SEASONAL** strategy — even if other signals like "boost sales" or "increase revenue" could match other goals. Holidays are time-sensitive and take priority over general intent.
 
@@ -205,10 +206,6 @@ Based on the merchant's request AND the site data, determine which domains to an
 
 **For SHIPPING domain — load the same goal as discounts.** Shipping flows (free shipping threshold, rate optimization) serve the same business goals as discount flows. Load the matching discount goal above — it now includes shipping flow references.
 
-**For ABANDONED_CART domain — load the cart abandonment goal:**
-
-[Goal: Reduce Cart Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-reduce-cart-abandonment)
-
 **The goal skill will instruct you to load flow and guardrail skills** — follow those instructions. This chain provides the detailed execution logic you need for high-quality recommendations.
 
 **Do NOT skip this step.** The goal/flow/guardrail skills contain critical constraints (margin tiers, campaign windows, conflict checks) that prevent bad recommendations.
@@ -418,35 +415,9 @@ Analyze the site's shipping configuration using the rules below. All shipping re
 
 **Priority order:** CRITICAL blockers (no options, no coverage) → Conversion-linked (no free shipping, high rates) → Revenue opportunities (international, tiered pricing) → Configuration improvements (consolidate, add estimates).
 
-### Abandoned cart recommendations (if ABANDONED_CART domain active)
-
-Detect if the merchant has significant cart abandonment without active recovery. All abandoned cart recommendations use `domain: "abandoned_cart_recovery"`.
-
-**Eligibility gate (BOTH conditions required):**
-1. Cart abandonment recovery automation is **NOT active** on the site
-2. Estimated missing sales >= $200 over the last 30 days
-
-**If either condition fails, do NOT generate abandoned cart recommendations.**
-
-**Urgency thresholds based on missing sales (USD, last 30 days):**
-
-| Missing sales | Urgency |
-|---|---|
-| >= $1,000 | HIGH |
-| $200 — $999 | MEDIUM |
-| < $200 | Do not recommend |
-
-**Action type:** `activate_abandoned_cart_recovery`
-
-**Params must include:** `automation_key` ("wix_e_commerce-cart_abandonment"), `missing_sales_usd` (integer, rounded), `abandoned_cart_count` (integer), `window_days` (always 30).
-
-**Title pattern:** "Recover $[missing_sales_usd] in abandoned carts"
-
-**Reasoning MUST cite:** automation is inactive, exact cart count, exact missing sales USD, 30-day window, and why the urgency level was chosen.
-
 ### Cross-domain balance
 
-- If request is generic, aim for recommendations from **multiple domains** (e.g., 2-3 discount + 1-2 shipping + abandoned cart if eligible)
+- If request is generic, aim for recommendations from **multiple domains** (e.g., 2-3 discount + 1-2 shipping)
 - If request targets a specific domain, focus all slots on that domain
 - Rank by business impact: CRITICAL blockers first, then conversion-linked, then revenue opportunities
 
@@ -471,7 +442,13 @@ Detect if the merchant has significant cart abandonment without active recovery.
 
 **MANDATORY — do NOT skip unless the user said `SKIP_TRACKING`.**
 
-Call `BatchCreate` to persist ALL recommendations as PROPOSED:
+Before calling BatchCreate, load the tracking recipe to get the exact request body shape:
+
+```
+ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-recommendation-tracking")
+```
+
+Then call `BatchCreate` to persist ALL recommendations as PROPOSED:
 
 ```
 CallWixSiteAPI(
@@ -483,7 +460,7 @@ CallWixSiteAPI(
       {
         "title": "<recommendation title>",
         "reasoning": "<recommendation reasoning>",
-        "domain": "<discounts|shipping|abandoned_cart_recovery>",
+        "domain": "<discounts|shipping>",
         "urgency": "<CRITICAL|HIGH|MEDIUM|LOW>",
         "advice": {
           "action": "<action type>",
@@ -550,7 +527,7 @@ If BatchCreate fails, report the error and include recommendations without track
 | `id` | GUID from tracking BatchCreate response (omit if tracking skipped/failed) |
 | `title` | Short, actionable. Max 200 chars. Always English. |
 | `reasoning` | **Must reference which API call returned the data.** Always English. |
-| `domain` | `"discounts"`, `"shipping"`, or `"abandoned_cart_recovery"` (future: `"gift_cards"`, `"taxes"`) |
+| `domain` | `"discounts"` or `"shipping"` (future: `"gift_cards"`, `"taxes"`) |
 | `urgency` | `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW` |
 | `mechanism` | `AUTOMATIC` or `COUPON`. From Step 4c. Only for discounts domain. |
 | `name` | Marketing headline, 2-5 words. Translate to site `language` if not English. |
@@ -565,7 +542,6 @@ If BatchCreate fails, report the error and include recommendations without track
 |---|---|
 | discounts | `apply_discount` |
 | shipping | `create_shipping_option`, `update_shipping_option`, `enable_backup_rate`, `activate_region` |
-| abandoned_cart_recovery | `activate_abandoned_cart_recovery` |
 
 ---
 

package/skills/wix-manage/references/ecommerce/{api-shipping.md → shipping/ecom-shipping-api.md}

@@ -1,7 +1,6 @@
 ---
-name: "API: Shipping Delivery"
-description: REST API reference for Shipping Options and Delivery Profiles. Covers CRUD operations, region/carrier management, and query patterns for both services. Internal reference — these APIs are not yet published in public docs.
-layer: config
+name: "Shipping: API Reference"
+description: "Shipping Options API: POST /ecom/v1/shipping-options/query (list all), POST /ecom/v1/shipping-options (create), PATCH /ecom/v1/shipping-options/{id} (update), DELETE /ecom/v1/shipping-options/{id} (delete). Delivery Profiles API: POST /ecom/v1/delivery-profiles/query. Base: https://www.wixapis.com/ecom"
 ---
 # API: Shipping Delivery
 
@@ -73,6 +72,8 @@ Creates a new shipping option and associates it with one or more delivery region
 
 **Required fields**: `shippingOption.deliveryRegionId` (or `deliveryRegionIds`), `shippingOption.title`, `shippingOption.rates[]`
 
+> **Gotcha:** use the **singular** `deliveryRegionId` when linking an option to one region. Passing a single region in the plural `deliveryRegionIds` field returns `deliveryRegionId is not a valid GUID`.
+
 **Request**:
 ```json
 {

package/skills/wix-manage/references/ecommerce/{flow-fix-coverage-gaps.md → shipping/ecom-shipping-fix-coverage.md}

@@ -1,20 +1,26 @@
 ---
-name: "Flow: Fix Coverage Gaps"
-description: Detects active delivery regions with zero shipping options and creates standard shipping for them. Cross-references delivery profiles with shipping options to find regions where customers cannot complete checkout.
-layer: flow
-references:
-  - name: "Guardrail: Shipping Health"
-    path: ecommerce/guardrail-shipping-health.md
-    load: true
-  - name: "Setup: Shipping Regions"
-    path: ecommerce/setup-shipping-regions.md
-    load: true
+name: "Shipping: Fix Coverage Gaps"
+description: "Coverage gap = active delivery region with ZERO Shipping Options (NOT zero carriers or no backup rate). Step 1: POST /ecom/v1/delivery-profiles/query. Step 2: POST /ecom/v1/shipping-options/query — count options per region; gap = active region with count 0. Step 3: POST /ecom/v1/shipping-options to create standard shipping for each gap region."
 ---
 # Flow: Fix Shipping Coverage Gaps
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Guardrail: Shipping Health](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-shipping-health)
-> - [Setup: Shipping Regions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-regions)
+> **Before executing this skill**, read [Setup: Shipping Regions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-regions) with `ReadFullDocsArticle` for region/carrier mechanics.
+
+## Shipping health score (inline)
+
+Use to gauge urgency before fixing gaps:
+
+| Score | Key indicator | Action |
+|---|---|---|
+| CRITICAL | no profiles/options, or all regions inactive | immediate setup |
+| POOR | minimal config, low CVR, or no backup rates | fix fundamentals |
+| FAIR | basic setup, no free shipping, moderate CVR | add free shipping, expand regions |
+| GOOD | domestic + international, free shipping, good CVR | optimize rates/carriers |
+| EXCELLENT | full coverage, tiered rates, high CVR | maintain |
+
+## Business-context filter for international (MANDATORY)
+
+Before creating or recommending ANY international shipping, check the store's `industry`/`businessType` (case-insensitive) for: food, restaurant, grocery, bakery, catering, perishable, fresh, meat, produce, dairy, drink, beverage. **If matched → do NOT create/recommend international shipping** (cold-chain & regulatory barriers). A region is "international" if its `name` contains "international"/"internacional", its `destinations[]` is empty (Rest of World), or it includes countries outside the store's home country.
 
 Detects delivery regions where customers cannot see any shipping options at checkout and creates standard shipping to fill the gaps. A coverage gap is a HIGH priority blocking issue -- customers in affected destinations literally cannot complete a purchase.
 
@@ -26,9 +32,9 @@ Detects delivery regions where customers cannot see any shipping options at chec
 
 ## Required APIs
 
-- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles)
-- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options)
-- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option)
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles)
+- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options)
+- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option)
 
 ---
 
@@ -296,4 +302,4 @@ Use the same request from Step 2 and verify the count now covers all active, non
 
 ## References
 
-- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping)
+- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference)

package/skills/wix-manage/references/ecommerce/{flow-add-free-shipping.md → shipping/ecom-shipping-free-shipping.md}

@@ -1,20 +1,25 @@
 ---
-name: "Flow: Add Free Shipping"
+name: "Shipping: 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
+# Shipping: 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)
+> **This skill is the single source for adding free shipping.** Do NOT load `…/skills/flow-add-free-shipping` — that legacy slug pre-dates the routing tree migration and its content has been merged into this file. If the WixREADME index surfaces it, or this slug returns a transient 404 from the docs backend (rawdocs ingestion delay), retry this same URL — do NOT fall back to the legacy slug.
+
+> **Before executing this skill**, read [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-rates) with `ReadFullDocsArticle` for the rate-object mechanics.
+
+## Rate pricing sanity (inline guardrail)
+
+Validate every rate you create or update against the store's AOV; flag any that fail:
+
+| Check | Threshold | Why / fix |
+|---|---|---|
+| Excessive rate | amount > AOV × 0.15 | top cart-abandonment driver |
+| Per-item penalty | `multiplyByQuantity: true` | penalizes larger orders → use flat/tiered |
+| Free threshold too high | threshold > AOV × 2 | unreachable; lower to ~AOV × 1.2 |
+| Free threshold too low | threshold < AOV × 0.8 | no upsell incentive; raise to ~AOV × 1.2 |
+| Backup rate shock | `backupRate.amount` > AOV × 0.15 | set to 5–10% of AOV |
+| Hidden surcharges | total `additionalCharges` > AOV × 0.10 | review necessity |
 
 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.
 
@@ -27,10 +32,10 @@ Adds a free shipping option with an optimal threshold calibrated against the sit
 
 ## Required APIs
 
-- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options)
-- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option)
-- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#update-shipping-option)
-- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles)
+- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options)
+- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option)
+- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#update-shipping-option)
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles)
 
 ---
 
@@ -263,4 +268,4 @@ Report to the merchant:
 
 ## References
 
-- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping)
+- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference)

package/skills/wix-manage/references/ecommerce/{flow-optimize-shipping-rates.md → shipping/ecom-shipping-optimize-rates.md}

@@ -1,20 +1,23 @@
 ---
-name: "Flow: Optimize Shipping Rates"
+name: "Shipping: Optimize Rates"
 description: Analyzes catalog price distribution and current rate structure to recommend optimal shipping rate strategy. Handles flat-to-tiered conversion, tier gap detection, and per-item penalty removal.
-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: Optimize Shipping Rates
 
-> **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)
+> **Routing rule:** BEFORE taking any action, call `ReadFullDocsArticle` on [Shipping API Reference](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference). The Query Shipping Options and Update/Create Shipping Option endpoints used in Steps 2–4 live there. Do NOT query or modify any shipping options without loading it first.
+
+## Rate pricing sanity (inline guardrail)
+
+Validate every rate you create or update against the store's AOV; flag any that fail:
+
+| Check | Threshold | Why / fix |
+|---|---|---|
+| Excessive rate | amount > AOV × 0.15 | top cart-abandonment driver |
+| Per-item penalty | `multiplyByQuantity: true` | penalizes larger orders → use flat/tiered |
+| Free threshold too high | threshold > AOV × 2 | unreachable; lower to ~AOV × 1.2 |
+| Free threshold too low | threshold < AOV × 0.8 | no upsell incentive; raise to ~AOV × 1.2 |
+| Backup rate shock | `backupRate.amount` > AOV × 0.15 | set to 5–10% of AOV |
+| Hidden surcharges | total `additionalCharges` > AOV × 0.10 | review necessity |
 
 Analyzes the site's catalog price distribution and current shipping rate structure to determine if the rate strategy is optimal. Recommends and applies changes when flat rates should become tiered, when tier gaps exist, or when per-item penalties are harming conversion.
 
@@ -27,9 +30,9 @@ Analyzes the site's catalog price distribution and current shipping rate structu
 
 ## Required APIs
 
-- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options)
-- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#update-shipping-option)
-- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option)
+- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options)
+- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#update-shipping-option)
+- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option)
 
 ---
 
@@ -360,4 +363,4 @@ Verify:
 
 ## References
 
-- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping)
+- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference)

package/skills/wix-manage/references/ecommerce/{setup-store-pickup-location.md → shipping/ecom-shipping-setup-pickup.md}

@@ -1,9 +1,11 @@
 ---
-name: "Setup: Store Pickup Location"
+name: "Shipping: Set Up Pickup / Local Delivery"
 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
 
+> **Routing rule:** BEFORE taking any action, call `ReadFullDocsArticle` on [Shipping API Reference](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference). The endpoint shapes for List Installed Delivery Carriers, Query Delivery Profiles, Add Delivery Region, and Add Delivery Carrier all live there. Do NOT call any of these APIs without loading it first.
+
 ## Prerequisites
 
 - Wix Stores (or another eCommerce business solution) installed on the site
@@ -11,16 +13,16 @@ description: Configures a pickup option for an online store so customers can cho
 
 ## Required APIs
 
-- [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#list-installed-delivery-carriers)
-- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles)
-- [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-region)
-- [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#add-delivery-carrier)
+- [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#list-installed-delivery-carriers)
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles)
+- [Add Delivery Region](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#add-delivery-region)
+- [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#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/skills/api-shipping#list-installed-delivery-carriers) to find the Pickup carrier's `id`.
+Call [List Installed Delivery Carriers](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#list-installed-delivery-carriers) to find the Pickup carrier's `id`.
 
 **Endpoint**: `GET https://www.wixapis.com/ecom/v1/delivery-profiles/installed-carriers`
 
@@ -53,7 +55,7 @@ If no Pickup carrier appears in the list, the Pickup app is not installed on the
 
 ## Step 2: Find the default delivery profile
 
-Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles) to retrieve the site's default delivery profile.
+Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles) to retrieve the site's default delivery profile.
 
 **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/query`
 
@@ -72,7 +74,7 @@ The response contains an array of `deliveryProfiles`. Find the one where `"defau
 
 ## 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/skills/api-shipping#add-delivery-region) to create one.
+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/skills/shipping-api-reference#add-delivery-region) to create one.
 
 **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region`
 
@@ -130,7 +132,7 @@ 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/skills/api-shipping#add-delivery-carrier) to attach the Pickup carrier to the delivery region.
+Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#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`
 
@@ -205,4 +207,4 @@ Call [Add Delivery Carrier](https://dev.wix.com/docs/api-reference/business-solu
 
 ## Related Documentation
 
-- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping)
+- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference)

package/skills/wix-manage/references/ecommerce/{setup-shipping-rates.md → shipping/ecom-shipping-setup-rates.md}

@@ -1,7 +1,6 @@
 ---
-name: "Setup: Shipping Rates"
+name: "Shipping: Set Up 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
 

package/skills/wix-manage/references/ecommerce/{setup-shipping-regions.md → shipping/ecom-shipping-setup-regions.md}

@@ -1,7 +1,6 @@
 ---
-name: "Setup: Shipping Regions"
+name: "Shipping: Set Up 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