Promotions

Promotions are where a POS stops being transactional and becomes revenue-driving. Discounts = manual price reduction Promotions = rule-driven pricing behavior Promotions are a rule engine problem, not just a pricing field. Here is what you need to add for Pricing & Promotions → Promotions. What “Promotion” means (business meaning) A promotion is a pricing rule that automatically applies when conditions are met. Examples: Buy 2 get 1 free 20% off shoes Spend $100 → get $10 off Buy from collection → discount applies Happy hour pricing Bundle pricing Loyalty promotion Key difference from discounts: 👉 Promotion is automatic 👉 Promotion has conditions 👉 Promotion has lifecycle (schedule, targeting) Core concept (very important) Promotion = Condition → Benefit Every promotion rule must define: Eligibility (condition) Reward (benefit) This simple mental model prevents chaos. What you must support (promotion types — MVP) Start with the most common retail ones: Line promotions % off category / product fixed amount off item price override rule buy X qty → % off Cart promotions spend threshold discount fixed cart discount Bundle basic buy X get Y free (very important retail) You don’t need advanced stacking yet — but schema must allow. What you must track (data) For each promotion: name scope (line/cart) condition definition (structured) benefit definition (structured) priority stacking rules (later) schedule (start/end) channels (POS / online later) locations usage limits status And per application: which rule applied which lines affected discount amount generated Database additions (recommended architecture)

1. Promotion rule table promotion id business_id name type (line/cart/bundle) priority stackable (bool) start_at end_at status created_by
2. Promotion condition definition There are 2 approaches: A) JSON condition (recommended MVP) B) normalized rule engine tables (Phase 2) MVP: promotion.condition_json Examples: category = shoes qty >= 2 cart_total >= 100 This keeps flexibility early.
3. Promotion benefit definition Also JSON: promotion.benefit_json Examples: percent_discount: 20 amount_discount: 10 free_item: variant_id override_price: X
4. Promotion application tracking (very important) When a promotion fires: promotion_application id promotion_id sale_id sale_line_id (nullable) amount_generated created_at This is required for reporting + auditing. Backend functionality you need Promotion evaluation service (core engine) When cart changes: fetch active promotions evaluate conditions calculate benefits generate discount applications respect priority This service will be reused everywhere. Endpoints CRUD promotions preview promotion impact (huge UX win) evaluate promotions for cart Frontend screens (PWA) Admin side (MVP promotion builder) Keep simple: Create promotion: name scope (line/cart) choose condition type category product cart total qty threshold choose benefit schedule locations Avoid “rule builder UI complexity” early. POS UX Cashier should see: promotion badge on item cart message: “Promotion applied” preview savings explanation (very important for trust) Apparel importance (huge) Promotions are extremely common in apparel: seasonal sales collection markdown waves bundle promotions size clearance color clearance multi-buy deals If FlowPOS handles promotions cleanly → strong differentiation. Reports (Metabase — critical) Promo revenue impact Promo margin impact Promo usage frequency Top performing promotions Discount leakage by promotion Promo vs non-promo sales Bundle performance These are strategic dashboards. MVP vs Phase 2 ✅ MVP promotions promotion table with JSON condition/benefit line + cart promotions buy X get Y basic promotion_application table evaluation service schedule support priority support 🚀 Phase 2 (real promo engine) rule builder UI stacking strategies customer segment targeting coupon codes loyalty integration promotion simulation advanced bundles channel targeting AI promo optimization Biggest edge cases (important) Promotions + manual discounts stacking Returns must restore promotion logic Exchange with promo items Bundle returns (very tricky) Promo rounding differences Multi-location promo differences Overlapping promotions These must be considered early. Architecture insight for FlowPOS (important) Promotions sit on top of: price lists discounts variants inventory signals customer segmentation (future) If you model: promotion promotion_application JSON rule definition You can evolve into a real engine without breaking schema. That is the correct early design. If you want, next I can give you: Minimal Kysely schema for promotions ⭐ recommended Promotion evaluation algorithm (POS friendly) ⭐ very useful Bundle promotion design (hard but valuable) Markdown lifecycle (apparel gold feature) Price list + promotion precedence model How promotions interact with suggested replenishment (advanced insight)