@wix/agent-skills 1.0.0

package/skills/wix-manage/references/ecommerce/goal-drive-cross-sells.md

@@ -0,0 +1,122 @@
+---
+name: "Goal: Drive Cross-Sells"
+description: Maps the BUNDLE_AND_SAVE business goal to multi-item purchase KPIs and bundling flows.
+layer: goal
+references:
+  - name: "Flow: Bundle and Save"
+    path: ecommerce/flow-bundle-and-save.md
+    load: true
+---
+# Goal: Drive Cross-Sells and Product Discovery
+
+> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
+> - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save)
+
+Promote product discovery and multi-item purchases by creating bundle-based discounts that reward customers for buying across categories or adding complementary items to their cart.
+
+---
+
+## Business Goal
+
+**Goal ID:** `BUNDLE_AND_SAVE`
+
+The merchant wants customers to explore more of the catalog and purchase multiple items per order. This is achieved through minimum item quantity conditions that incentivize buyers to add more products, particularly in categories with natural cross-sell relationships.
+
+---
+
+## KPIs
+
+| KPI | Definition | How to measure |
+|---|---|---|
+| Items per order | Average number of line items per completed order | Order data: total items / total orders |
+| Cross-sell rate | Percentage of orders containing items from 2+ categories | Analyze order composition across categories |
+| Category diversity per order | Number of distinct categories represented per order | Track unique categories per order before and after |
+| Bundle discount redemption | Orders meeting the minItemQuantity condition / total orders | Count qualifying orders vs total |
+
+---
+
+## Triggers
+
+Activate this goal when the merchant expresses any of the following intents:
+
+- "bundle"
+- "cross-sell"
+- "buy together"
+- "product discovery"
+- "multi-buy"
+- "encourage people to buy more items"
+- "sell accessories with main products"
+- "increase items per order"
+- "mix and match"
+- Any request about getting customers to explore more of the catalog
+
+---
+
+## Recommended Actions
+
+### Primary: Flow: Bundle & Save Campaign
+
+The sole action for this goal. Creates a percentage discount with a `minItemQuantity` condition that activates when the customer adds enough items to their cart.
+
+**When to use:** Whenever the merchant wants to incentivize multi-item purchases, cross-category exploration, or product discovery.
+
+**Key mechanics:**
+- minItemQuantity condition (typically 2-3 items based on catalog profile)
+- Scope determines which products count toward the bundle:
+  - CATEGORY — items from a specific category (best for focused cross-sell)
+  - ITEMS — specific complementary products (best for curated bundles)
+  - SITE — any items in the store (broadest reach)
+- Discount percentage scaled to margin (10-20%)
+- Higher item thresholds for lower-priced catalogs, lower thresholds for premium catalogs
+
+**Catalog profile matching:**
+
+| Catalog Type | minItemQuantity | Scope | Example |
+|---|---|---|---|
+| Accessories + main products | 2 | CATEGORY (accessories) | "Buy 2+ accessories, save 15%" |
+| Wide catalog, many categories | 3 | SITE | "Buy any 3 items, save 10%" |
+| Curated complementary items | 2 | ITEMS (specific products) | "Buy these together, save 15%" |
+| Low-price items (avg < price_p25) | 3-4 | CATEGORY or SITE | "Buy 4+, save 20%" |
+| High-price items (avg > price_p75) | 2 | CATEGORY | "Buy 2 premium items, save 10%" |
+
+---
+
+## Measurement Plan
+
+### Before campaign launch
+
+1. Record baseline items per order
+2. Record baseline category distribution per order
+3. Identify current cross-sell rate (orders with 2+ categories)
+
+### During campaign (weekly check-ins)
+
+1. Track items per order vs baseline
+2. Monitor bundle redemption rate
+3. Check margin impact — multi-item discounts compound with quantity
+4. Verify the minItemQuantity threshold is appropriate:
+   - Redemption rate > 70% — threshold may be too low
+   - Redemption rate < 5% — threshold may be too high or scope too narrow
+
+### After campaign (30-day assessment)
+
+1. Calculate items-per-order lift: `(new_items_per_order - baseline) / baseline * 100`
+2. Measure new category penetration — did customers discover categories they had not purchased from before?
+3. Assess AOV impact — bundling often increases AOV as a side effect
+4. Evaluate whether specific product combinations drove the most bundle completions
+5. Target benchmarks:
+   - Items per order increase > 15% = strong result
+   - Cross-sell rate increase > 10% = successful discovery
+
+---
+
+## Decision Matrix
+
+| Scenario | Approach | Rationale |
+|---|---|---|
+| Store has clear accessory categories | CATEGORY scope on accessories, minItemQuantity: 2 | Natural cross-sell with main products |
+| Broad catalog, no clear bundles | SITE scope, minItemQuantity: 3 | Encourages exploration across the entire catalog |
+| Merchant names specific products | ITEMS scope with those products | Curated bundle matching merchant's intent |
+| Low average price catalog | Higher minItemQuantity (3-4) | Lower price per item makes larger bundles feasible |
+| High average price catalog | Lower minItemQuantity (2) | Customers less likely to buy 3+ expensive items |
+| Merchant specifies quantities or discounts | Honor merchant input | User overrides always take priority |

package/skills/wix-manage/references/ecommerce/goal-increase-aov.md

@@ -0,0 +1,132 @@
+---
+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
+---
+# 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)
+>
+> **Shipping flows that also serve AOV goals** (read with `ReadFullDocsArticle` 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
+>
+> **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)
+
+Incentivize customers to spend above the store's current average order value (AOV) by creating threshold-based discounts that reward higher cart totals.
+
+---
+
+## Business Goal
+
+**Goal ID:** `UPSELL_BOOST`
+
+The merchant wants to increase the average amount customers spend per order. This is achieved by setting a minimum subtotal condition above the current AOV, so customers are encouraged to add more items or upgrade to higher-priced products to unlock the discount.
+
+---
+
+## KPIs
+
+| KPI | Definition | How to measure |
+|---|---|---|
+| Average Order Value (AOV) | Total revenue / total orders | `getSiteData` — revenue / ordersCount |
+| Revenue per order | Gross revenue attributed to each completed order | Track via order data before and after campaign |
+| Discount redemption rate | Orders qualifying for the discount / total orders | Count orders with the discount applied vs total |
+| Cart size increase | Change in items per order after campaign | Compare items per order pre/post |
+
+---
+
+## Triggers
+
+Activate this goal when the merchant expresses any of the following intents:
+
+- "increase AOV"
+- "boost order value"
+- "upsell"
+- "get people to spend more"
+- "increase average order"
+- "raise order size"
+- "higher cart value"
+- Any request mentioning order value, spending thresholds, or minimum purchase incentives
+
+---
+
+## Recommended Actions
+
+### Primary: Flow: Upsell Boost Campaign
+
+The primary action for this goal. Creates a percentage discount with a `minSubTotal` condition set above the current AOV. The discount percentage and threshold are tiered based on the store's average profit margin.
+
+**When to use:** Always the first recommendation for AOV-focused goals. Works best when the store has clear AOV data and margin information.
+
+**Key mechanics:**
+- minSubTotal set to 1.15x-1.5x the effective AOV (based on margin tier)
+- Discount percentage scaled to margin (10-20%)
+- Scope prioritized: CATEGORY (high-margin) > ITEMS (specific upsell candidates) > SITE (fallback)
+
+### Secondary: Flow: Bundle & Save Campaign
+
+A complementary action that increases AOV by encouraging multi-item purchases. Instead of a subtotal threshold, it uses an item quantity threshold.
+
+**When to use:** When the catalog has natural cross-sell opportunities (complementary products, accessories, related items). Particularly effective when the store has many lower-priced items where quantity-based incentives drive higher totals.
+
+**Key mechanics:**
+- minItemQuantity condition (typically 2-3 items)
+- Targets categories with cross-sell potential
+- Can run alongside an upsell boost if scoped to different categories
+
+---
+
+## Measurement Plan
+
+### Before campaign launch
+
+1. Record baseline AOV from `getSiteData` (revenue / ordersCount)
+2. Record baseline items per order
+3. Note the campaign start date
+
+### During campaign (weekly check-ins)
+
+1. Compare current AOV to baseline
+2. Track discount redemption rate
+3. Monitor margin impact (ensure effective margin stays above 15%)
+
+### After campaign (30-day assessment)
+
+1. Calculate AOV lift: `(new_aov - baseline_aov) / baseline_aov * 100`
+2. Calculate incremental revenue attributable to higher order values
+3. Assess whether the minSubTotal threshold needs adjustment:
+   - If redemption rate > 80% — threshold may be too low, consider raising
+   - If redemption rate < 10% — threshold may be too high, consider lowering
+   - Sweet spot: 20-40% redemption rate
+
+---
+
+## Decision Matrix
+
+| Scenario | Recommended Flow | Rationale |
+|---|---|---|
+| Clear AOV data, margin data available | Upsell Boost (primary) | Full data enables optimal threshold + discount calculation |
+| Low-data store (few orders) | Upsell Boost with conservative defaults | Use price_p50 as AOV proxy, 10% discount, 1.15x threshold |
+| Catalog has natural bundles | Bundle & Save (secondary) | Multi-item incentive drives AOV through quantity |
+| Both AOV and cross-sell opportunity | Both flows, different scopes | Upsell Boost on high-value categories, Bundle & Save on accessories |
+| Merchant specifies exact values | Honor merchant input | User overrides always take priority over calculated values |

package/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md

@@ -0,0 +1,148 @@
+---
+name: "Goal: Reduce Cart Abandonment"
+description: Maps cart abandonment reduction to recovery automation KPIs. Covers abandoned cart email automation activation, missing sales detection, and eligibility thresholds. Also references shipping flows that affect checkout drop-off.
+layer: goal
+references:
+  - name: "Flow: Fix Coverage Gaps"
+    path: ecommerce/flow-fix-coverage-gaps.md
+    load: false
+  - name: "Recipe: Apply Shipping Recommendations"
+    path: ecommerce/recipe-apply-shipping-recommendations.md
+    load: false
+  - name: "Setup Store Pickup Location"
+    path: ecommerce/setup-store-pickup-location.md
+    load: false
+---
+# Goal: Reduce Cart Abandonment
+
+> **Related skills** (read with `ReadFullDocsArticle` if needed):
+> - [Flow: Fix Coverage Gaps](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-fix-coverage-gaps) — shipping coverage gaps block checkout entirely
+> - [Recipe: Apply Shipping Recommendations](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/recipe-apply-shipping-recommendations)
+> - [Setup Store Pickup Location](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-store-pickup-location)
+> - [Setup Store Pickup Location](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-store-pickup-location)
+
+Reduce checkout abandonment caused by shipping friction — coverage gaps, unexpected costs, and missing free shipping options — by optimizing the delivery step of the checkout funnel.
+
+---
+
+## Business Goal
+
+The merchant wants to reduce the percentage of customers who abandon checkout, specifically at the delivery/shipping step. Shipping-related friction is the leading cause of checkout abandonment, and the delivery step conversion rate (delivery_step_cvr) is the primary metric.
+
+**Benchmark:** A healthy delivery_step_cvr is approximately 65%. Stores below this benchmark have significant shipping-related friction.
+
+---
+
+## KPIs
+
+| KPI | Definition | How to measure | Benchmark |
+|---|---|---|---|
+| Delivery step CVR | Customers completing delivery step / customers reaching delivery step | Site metrics: delivery_step_cvr | 65% |
+| Cart abandonment rate | Carts created but not converted to orders / total carts | 1 - (orders / carts) | Industry avg ~70% |
+| Free shipping qualification rate | Orders qualifying for free shipping / total orders | Track orders meeting free shipping threshold | Higher is better |
+| Revenue from recovered checkouts | Incremental revenue from improved conversion | (new_cvr - old_cvr) * checkout_sessions * AOV | - |
+
+---
+
+## Triggers
+
+Activate this goal when the merchant expresses any of the following intents:
+
+- "cart abandonment"
+- "checkout drop-off"
+- "shipping friction"
+- "delivery step"
+- "people are leaving at checkout"
+- "customers not completing orders"
+- "why are customers abandoning"
+- "checkout conversion"
+- Any request about reducing drop-off during the purchase flow
+
+---
+
+## Diagnostic Questions
+
+Before recommending actions, assess the root cause of abandonment. Ask or investigate:
+
+1. **Where are buyers dropping off?** — Is it specifically the delivery step, or payment, or earlier in the funnel?
+2. **Are shipping costs visible before checkout?** — Surprise shipping costs are the #1 abandonment driver.
+3. **Is there a free shipping option?** — Free shipping (even with a threshold) dramatically reduces abandonment.
+4. **Are there shipping coverage gaps?** — Customers in unserved regions cannot complete checkout at all.
+5. **Are shipping rates reasonable?** — Rates above 10-15% of order value cause sticker shock.
+6. **Are payment methods adequate?** — Missing payment options can look like shipping-step abandonment in metrics.
+7. **Are recovery emails enabled?** — Abandoned cart emails can recapture 5-15% of abandoned carts.
+
+---
+
+## Recommended Actions (Prioritized)
+
+Actions are ordered by impact. Address blocking issues first, then conversion drivers, then optimization.
+
+### Priority 1: Flow: Fix Shipping Coverage Gaps (Blocking)
+
+Coverage gaps are the most critical issue — if a customer's region is not covered by any shipping option, they literally cannot complete checkout.
+
+**When to use:** When delivery profiles show regions without active shipping options, inactive regions, or missing domestic coverage.
+
+**Impact:** Removes a hard blocker. Customers in uncovered regions have 0% conversion.
+
+### Priority 2: Flow: Add Free Shipping (Conversion Driver)
+
+Free shipping is the single most effective lever for reducing cart abandonment. Even with a minimum order threshold, offering a free shipping option significantly improves delivery step conversion.
+
+**When to use:** When the store has no free shipping option, or when the existing free shipping threshold is set too high relative to AOV.
+
+**Impact:** Typically improves delivery_step_cvr by 10-20 percentage points. The threshold should be calibrated to AOV (typically 1.2x-1.5x AOV).
+
+### Priority 3: Flow: Optimize Shipping Rates (Sticker Shock Reduction)
+
+High shipping rates cause sticker shock even when coverage exists. Rate optimization ensures pricing is competitive and proportional to order value.
+
+**When to use:** When shipping rates are disproportionately high relative to product prices, or when rates lack tiered/conditional pricing.
+
+**Impact:** Reduces abandonment from price sensitivity. Most effective when combined with free shipping at a threshold.
+
+---
+
+## Measurement Plan
+
+### Before optimization
+
+1. Record baseline delivery_step_cvr from site metrics
+2. Record current cart abandonment rate
+3. Identify the specific shipping configuration state:
+   - Number of active regions with shipping options
+   - Presence/absence of free shipping
+   - Average shipping rate as percentage of AOV
+
+### During optimization (weekly monitoring for 30 days)
+
+1. Track delivery_step_cvr weekly
+2. Compare week-over-week trend
+3. Monitor free shipping qualification rate (if threshold was added)
+4. Check for new coverage gaps if regions were modified
+
+### After optimization (30-day assessment)
+
+1. Calculate CVR improvement: `new_delivery_step_cvr - baseline_delivery_step_cvr`
+2. Estimate revenue recovered: `cvr_improvement * checkout_sessions * AOV`
+3. Evaluate threshold effectiveness:
+   - Free shipping qualification rate > 40% = threshold well-calibrated
+   - Free shipping qualification rate < 10% = threshold too high, consider lowering
+4. Assess whether further optimization is needed:
+   - delivery_step_cvr >= 65% = healthy, monitor quarterly
+   - delivery_step_cvr 50-65% = improving, continue optimization
+   - delivery_step_cvr < 50% = investigate non-shipping causes (payment, UX)
+
+---
+
+## Decision Matrix
+
+| Scenario | Priority Action | Rationale |
+|---|---|---|
+| Regions without shipping options | Fix Coverage Gaps (P1) | Hard blocker — 0% conversion in uncovered regions |
+| No free shipping option exists | Add Free Shipping (P2) | #1 conversion driver for delivery step |
+| Free shipping exists but threshold too high | Add Free Shipping (recalibrate) | Lower threshold to match AOV |
+| High shipping rates, free shipping exists | Optimize Shipping Rates (P3) | Reduce sticker shock for below-threshold orders |
+| delivery_step_cvr >= 65% | No immediate action needed | Already at healthy benchmark |
+| Abandonment not at delivery step | Investigate other causes | Payment methods, UX, trust signals may be the issue |

package/skills/wix-manage/references/ecommerce/goal-seasonal-revenue.md

@@ -0,0 +1,146 @@
+---
+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
+---
+# 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)
+
+Capitalize on holidays, cultural events, and seasonal moments to drive revenue spikes through time-limited promotional campaigns.
+
+---
+
+## Business Goal
+
+**Goal ID:** `SEASONAL`
+
+The merchant wants to take advantage of a specific event or season to boost sales. This is achieved through time-bound discount campaigns that create urgency and align with customer purchasing behavior during peak shopping periods.
+
+---
+
+## KPIs
+
+| KPI | Definition | How to measure |
+|---|---|---|
+| Campaign period revenue | Total revenue during the promotional window | Compare order revenue within campaign dates |
+| Conversion lift | Conversion rate during event vs baseline | Site metrics: orders / visitors during campaign vs prior period |
+| Event vs baseline comparison | Revenue during event vs same period in prior month/year | `getSiteData` revenue comparison |
+| Discount redemption rate | Orders qualifying for campaign discount / total orders in window | Track discount-attributed orders |
+| Traffic-to-sale ratio | Orders / site visitors during campaign | Site metrics during campaign window |
+
+---
+
+## Triggers
+
+Activate this goal when the merchant expresses any of the following intents:
+
+- "Black Friday"
+- "Christmas sale"
+- "seasonal"
+- "holiday discount"
+- "New Year sale"
+- "Valentine's Day"
+- "summer sale"
+- "back to school"
+- "end of season"
+- Any date-related promotion request
+- Any mention of a specific holiday or cultural event tied to a discount
+
+### Proactive Detection
+
+If `current_date` is within 30 days of a major shopping holiday, auto-suggest a seasonal campaign:
+
+| Holiday / Event | Approximate Date | Suggest Window |
+|---|---|---|
+| Valentine's Day | Feb 14 | Jan 15 - Feb 14 |
+| Easter | Variable (March/April) | 30 days before |
+| Mother's Day | 2nd Sunday in May | April 15 - May date |
+| Father's Day | 3rd Sunday in June | May 20 - June date |
+| Back to School | August | July 15 - Aug 31 |
+| Black Friday | 4th Friday in November | Nov 1 - Nov 30 |
+| Cyber Monday | Monday after Black Friday | Nov 1 - Nov 30 |
+| Christmas | Dec 25 | Nov 25 - Dec 25 |
+| Boxing Day / End of Year | Dec 26-31 | Dec 20 - Dec 31 |
+| New Year | Jan 1 | Dec 26 - Jan 7 |
+
+When proactively suggesting, frame it as an opportunity rather than a requirement:
+> "Black Friday is {N} days away. Would you like to set up a promotional campaign to capitalize on the increased shopping traffic?"
+
+---
+
+## Recommended Actions
+
+### Primary: Flow: Seasonal Promotion
+
+For planned, scheduled events where the merchant has lead time. Creates a discount with defined start and end dates aligned to the event window.
+
+**When to use:**
+- The event is more than 48 hours away
+- The merchant wants a structured campaign with specific dates
+- The promotion should run for multiple days (e.g., a week-long sale)
+
+**Key mechanics:**
+- Time-bounded discount with explicit start/end dates
+- Scope can be CATEGORY (seasonal products), ITEMS (featured products), or SITE (store-wide event)
+- Discount percentage calibrated to margin and event significance
+
+### Secondary: Flow: Run Flash Sale
+
+For quick, high-urgency promotions with short windows (24-72 hours). Creates immediate impact with deeper discounts and tighter time constraints.
+
+**When to use:**
+- The event is imminent (within 48 hours)
+- The merchant wants a short burst of urgency-driven sales
+- Flash sale format (limited time, deeper discount) suits the event
+- Last-minute seasonal opportunity
+
+**Key mechanics:**
+- Short duration (typically 24-48 hours)
+- Can use deeper discounts than standard campaigns due to limited exposure
+- Urgency messaging: "24-hour flash sale" or "ends midnight"
+
+---
+
+## Measurement Plan
+
+### Before campaign launch
+
+1. Record baseline revenue for the same period (prior week or prior year if available)
+2. Record baseline conversion rate and traffic
+3. Note the campaign window (start date, end date)
+
+### During campaign
+
+1. Monitor revenue daily against the campaign target
+2. Track conversion rate vs baseline
+3. Check inventory levels for promoted products — adjust if selling out too fast
+4. Monitor discount stacking risks if other active promotions exist
+
+### After campaign (within 7 days of end)
+
+1. Calculate campaign revenue lift: `(campaign_revenue - baseline_revenue) / baseline_revenue * 100`
+2. Compare conversion rate during campaign vs baseline
+3. Assess whether the event-specific timing maximized impact
+4. Calculate ROI: incremental revenue vs margin cost of discounts
+5. Document learnings for next seasonal event:
+   - Was the discount depth appropriate?
+   - Was the campaign window too long or too short?
+   - Which product scope performed best?
+
+---
+
+## Decision Matrix
+
+| Scenario | Recommended Flow | Rationale |
+|---|---|---|
+| Major holiday, 7+ days lead time | Seasonal Promotion | Structured multi-day campaign with planned dates |
+| Event is tomorrow or today | Flash Sale | Immediate activation, short window |
+| End-of-season clearance | Seasonal Promotion + stock mover overlap | Combine seasonal framing with inventory goals |
+| Merchant says "quick weekend sale" | Flash Sale | Short duration matches flash format |
+| Merchant specifies exact dates and discount | Honor input, choose matching flow | User overrides take priority; select flow that fits the duration |

package/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md

@@ -0,0 +1,118 @@
+---
+name: "Guardrail: Discount Conflicts"
+description: Validation rules for detecting and preventing discount stacking conflicts, coupon overlap, and unintended deep discounts before applying new promotions. Covers automatic discount rules, coupon interactions, and safe discount limits.
+layer: guardrail
+references:
+  - name: "Troubleshoot: Discount Not Applying"
+    path: ecommerce/troubleshoot-discount-not-applying.md
+    load: false
+---
+# Guardrail: Discount Conflicts
+
+> **Related skills** (read with `ReadFullDocsArticle` if needed):
+> - [Troubleshoot: Discount Not Applying](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/troubleshoot-discount-not-applying)
+
+## When to use this guardrail
+
+Run these checks **before** creating or updating any discount — whether automatic discount rule or coupon. Discount conflicts are one of the most common merchant mistakes — overlapping discounts silently stack and give customers a much deeper discount than intended. This is especially dangerous when **automatic discounts and coupons interact**, since merchants often forget that both mechanisms apply simultaneously.
+
+---
+
+## Check 1: Existing active discount rules on the same scope
+
+**Why:** Wix eCommerce stacks automatic discount rules. If a 20% catalog-wide discount and a 15% collection discount both apply to the same product, the customer may get both applied.
+
+**How to check:**
+
+1. Query all active discount rules:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
+
+**Request**:
+```json
+{
+  "query": {
+    "filter": {
+      "active": true
+    },
+    "paging": {
+      "limit": 100
+    }
+  }
+}
+```
+
+2. For each existing active rule, compare its scope against the new rule:
+   - If both target `CATALOG` scope: **conflict** — both apply to all products
+   - If new rule targets `CATALOG` and existing targets `COLLECTION`: **conflict** — catalog-wide includes that collection
+   - If both target the same `COLLECTION` ID: **conflict** — same products affected
+   - If both target the same `SPECIFIC_PRODUCTS` ID: **conflict** — same product
+
+3. If a conflict is found, warn the merchant:
+   > "There's already an active discount '{existingRuleName}' ({existingDiscount}%) that applies to the same products. Adding this new {newDiscount}% discount may stack, giving customers a combined discount. Would you like to deactivate the existing rule first, or proceed with both?"
+
+---
+
+## Check 2: Discount percentage sanity
+
+**Why:** A discount above 50% is unusual and may indicate a typo (the merchant meant 15% not 50%). A discount of 100% makes the product free.
+
+**Rules:**
+- Discount > 50%: Warn — "This discount is {percentage}% off. Are you sure? This means a $100 product would sell for ${100 - percentage}."
+- Discount = 100%: Block unless explicitly confirmed — "This would make the product free. Please confirm this is intentional."
+- Discount > 100%: Block — "A discount cannot exceed 100%."
+
+---
+
+## Check 3: Time overlap with existing promotions
+
+**Why:** Two promotions running simultaneously on overlapping products cause stacking during the overlap period.
+
+**How to check:**
+
+1. For the new rule's `activeTimeInfo` (start/end), check if any existing active rule has an overlapping time window on the same scope.
+2. Overlap exists when: `existingStart < newEnd AND existingEnd > newStart`
+3. If overlap found on the same scope: warn the merchant about the overlap period.
+
+---
+
+## Check 4: Cross-mechanism stacking (Automatic + Coupon)
+
+**Why:** Automatic discounts and coupons stack with each other at checkout. A customer with a 20% coupon buying during a 20% automatic sale gets both applied — the effective discount is much deeper than either one alone. This is the most commonly overlooked stacking issue.
+
+**How to check:**
+
+1. If you are creating an **automatic discount**: Query active coupons that target overlapping products/collections.
+2. If you are creating a **coupon**: Query active automatic discount rules that target overlapping products/collections.
+3. If overlap found, warn the merchant with the combined impact:
+   > "You have an active {automatic discount / coupon} '{name}' ({X}% off) that applies to the same products. If you create this {coupon / automatic discount}, customers will get BOTH discounts — a combined effective discount of approximately {combined}%. Is this intentional?"
+
+**Key rule:** Only one coupon can be used per checkout, but automatic discounts have no such limit. The worst case is: multiple automatic discounts + one coupon all stacking on the same product.
+
+---
+
+## Check 5: Minimum profit margin
+
+**Why:** Deep discounts on low-margin products can result in selling at a loss.
+
+**Rules:**
+- If the merchant has provided cost/margin information, verify that the discount doesn't reduce the price below cost
+- If no cost information is available, warn for discounts > 40% as a general safety threshold
+
+---
+
+## Summary: Decision matrix
+
+| Scenario | Action |
+|---|---|
+| No conflicts found | Proceed with creating the discount |
+| Scope overlap with existing active automatic discount | Warn merchant, ask to deactivate existing or confirm stacking |
+| Cross-mechanism stacking (automatic + coupon on same scope) | Warn merchant with combined effective discount percentage |
+| Discount > 50% | Warn merchant, ask for confirmation |
+| Discount = 100% | Block unless explicitly confirmed |
+| Time overlap on same scope | Warn about overlap period |
+
+## References
+
+- [Discount Rules API (Automatic Discounts)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/introduction)
+- [Coupons API](https://dev.wix.com/docs/api-reference/business-solutions/coupons/introduction)