Building or debugging discount/promotion UI in the Dashboard
Investigating why a voucher or promotion isn't applying
Understanding order-level vs line-level discount precedence
Working with OrderDiscount / OrderLineDiscount objects
Debugging unit_discount_value on OrderLine
Deciding whether discounts stack or suppress each other
Building price-explanation / waterfall tooling on confirmed orders
Reconstructing how an order-level discount distributed across lines
Handling free-gift order lines (OrderLine.isGift = true)
Working on stock availability, shipping zones, warehouses, or Shop.useLegacyShippingZoneStockAvailability
Debugging why PRODUCT_VARIANT_*_IN_CHANNEL webhooks aren't firing
Building diagnostic / "doctor" tooling that explains availability problems
Auditing Dashboard copy that uses "available" / "in stock" / "purchasable"

Rule Categories

Priority	Category	Impact	Prefix
1	Discounts	CRITICAL	`discount-`
2	Stock	CRITICAL	`stock-`

Quick Reference

discount-precedence — Full precedence hierarchy, stacking rules, manual vs voucher vs promotion interactions, denormalized field semantics, known Dashboard bug
order-discount-allocation — Two-pass calculation of order-level discounts (Pass A collapses records into a single subtotal_discount; Pass B distributes proportionally across lines with last-line absorbing rounding), what the API exposes (per-line totals, per-record-at-order amounts) and what it doesn't (per-record-per-line decomposition), gift-line shape gotcha (ORDER_PROMOTION on OrderLine.discounts[] when isGift = true), reconstruction guidance for consumers

stock-availability-modes — Shop.useLegacyShippingZoneStockAvailability (3.23+), purchasability vs shippability, server queryset dispatch, mode-conditional webhooks, Dashboard UI / copy / severity rules, migration footguns, test fixtures

Read individual rule files for detailed explanations and source-level evidence:

rules/discount-precedence.md
rules/order-discount-allocation.md
rules/stock-availability-modes.md

Each rule file contains: