Flow: Stock Mover Clearance

Creates a discount targeting slow-moving inventory — products with high stock levels and low sales velocity. The discount depth is proportional to how overstocked the product is, with deeper discounts for the most stagnant items. Margin protection guardrails are especially important here since clearance discounts tend to push closer to cost.

Prerequisites

• Products exist in the catalog with inventory (quantity) data (siteData.hasCatalog === true, checked at context load)
• Inventory tracking enabled for target products

Required APIs

• Create Discount Rule
• Query Discount Rules

Step 1: Use pre-loaded catalog data

Catalog analytics and product data are already in conversation context — do NOT re-fetch:

• siteData.catalogAnalytics — category groups with sum(quantity), sum(ordersCount), avg(profitMargin). Loaded by the eCommerce Load Context.
• siteData.productCatalogData — per-product list sorted quantity DESC, ordersCount ASC for STOCK_MOVER goal. Loaded by the run-a-sale orchestrator Step 5.

Extract from context:

• total_quantity — sum(quantity) from the "All Products" group in siteData.catalogAnalytics
• total_orders — sum(ordersCount) from the "All Products" group
• avg_profit_margin — sets the discount ceiling
• Per-product: quantity, ordersCount, price, name, id, categoryId — from siteData.productCatalogData

Step 2: Identify slow-moving products

Calculate the velocity ratio for each product to identify overstocked items:

Select products with velocity_ratio < 0.3 as clearance candidates.

If quantity = 0 for a product, skip it (nothing to clear). If ordersCount = 0, the velocity ratio is 0 — this is the most urgent clearance case.

Step 3: Calculate discount depth

Scale the discount based on inventory urgency. Deeper discounts for more overstocked items, constrained by margin:

Margin constraint: Always verify discount <= avg_profit_margin - 15% (minMarginPct). Clearance discounts are more likely to violate margin thresholds because they are deliberately deeper.

Global cap: Do not exceed 25% unless the merchant explicitly overrides. For clearance, merchants may accept deeper discounts to free up capital and shelf space.

Step 4: Determine discount scope

Select the scope based on the distribution of slow movers:

• ITEMS (preferred for clearance): Target specific slow-moving products by ID (max 5 productIds). This is the most precise approach and avoids discounting fast sellers.
• CATEGORY: When multiple slow movers cluster in the same category, target the whole category. This is simpler but may discount some healthy-velocity products in the same category.
• SITE: Rarely appropriate for clearance — avoid discounting the entire catalog to clear a few items.

When selecting ITEMS scope, prioritize the products with the worst velocity ratios (lowest first), up to the max of 5 productIds.

Step 5: Convert category names to GUIDs (if CATEGORY scope)

If scope is CATEGORY, call getCategoryIds to convert category names to GUIDs.

• Never use category names as scope IDs — always use the GUID.
• Exclude the "All Products" system category.
• Max 3 categoryIds per discount rule.

Step 6: Run guardrail checks

Run the pre-create guardrails in Create Discount Rule → "Guardrails" before creating the rule (conflict/stacking, %-sanity, margin floor). Clearance is the most margin-sensitive case: discounts push closest to cost, so the margin-floor check (effective margin ≥ 15% unless the merchant overrides) is the one most likely to fire here — verify it per candidate product.

Step 7: Create the discount rule

Endpoint: POST https://www.wixapis.com/ecom/v1/discount-rules

Request — 20% off specific slow-moving products:

Response:

Request — clearance on an entire category:

Save the returned id and revision for later management.

Step 8: Verify the rule is active

1. Query discount rules to confirm the new rule exists and is active: true
2. Verify the correct products or category are targeted
3. Report to the merchant:

   "Clearance discount is live: {discount}% off {number_of_products} slow-moving items. These products had a velocity ratio of {avg_velocity}, indicating high stock relative to sales. Margin floor enforced — effective margin stays ≥ 15% on every targeted SKU. Monitor inventory levels — once stock clears, consider deactivating the rule."

Presentation requirement — margin guardrail line is mandatory

When generating recommendations for the merchant (whether persisted as PROPOSED via the tracking API or returned inline), every clearance recommendation MUST include explicit margin-floor language in its reasoning / why field. Examples:

• "Discount keeps effective margin ≥ 15% (minMarginPct floor)."
• "Pre-discount margin {X}%, post-discount {Y}% — above 15% breakeven floor."
• "Margin protected: 20% off does NOT push {product} below the 15% floor."

Urgency labels, stock level, capital tied up, and the "Why {N}%" velocity rationale are NOT substitutes — the merchant must see a per-item margin protection statement on every clearance line. If you cannot meet the floor at the velocity-tier discount, either reduce the discount or drop the item; never silently breach the floor.

Branching logic

Error Handling

References

• Discount Rules API