05 — Promotions, Volume Bundles & Pricing Engine Specification

1. Declarative Promotion Engine Architecture

Liquor retail relies heavily on dynamic, rule-based pricing to incentivize volume purchases: mixed-case wine discounts, craft beer mix-and-match bundles, happy-hour specials, and loyalty rewards.

Design Principles

1. Sub-5ms Execution in Memory: Promotion rules are evaluated locally inside the POS client memory whenever an item is added, removed, or quantity-modified in the cart. The checkout flow never waits on an API call to re-price a basket.
2. Transparent Discount Stacking Hierarchy: Liquor stores must avoid "double dipping" where an already deeply discounted item receives another 15% case discount. Clear priority rules dictate whether discounts combine or take the best available price.
3. Receipt Clarity: Every applied discount must show explicitly under its respective line item on both the customer screen and printed receipt.

┌────────────────────────────────────────────────────────────────────────┐
│                        ACTIVE CART LINE ITEMS                          │
└───────────────────────────────────▲────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼────────────────────────────────────┐
│                      RULE EVALUATION PIPELINE                          │
├────────────────────────────────────────────────────────────────────────┤
│ Step 1: Base Price Lookup & Fixed Item Deals                           │
│ Step 2: Bundle & Mix-and-Match Grouping (Pick-6 Beer Cans)             │
│ Step 3: Volume & Case Thresholds (6+ or 12+ Wine Bottles)              │
│ Step 4: Stacking & Exclusion Filter (Exclude Red-Tags & Allocated)    │
│ Step 5: Customer Loyalty Rewards & Senior/Military Discounts           │
└───────────────────────────────────▲────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼────────────────────────────────────┐
│                    FINAL PRICED BASKET + AUDIT TAGS                    │
└────────────────────────────────────────────────────────────────────────┘

2. Liquor Store Discount Archetypes

1. Mixed-Case Wine Discount

• The Rule: Customers receive 10% off when buying 6 or more 750ml wine bottles, and 15% off when buying 12 or more (full case).
• Exclusion Criteria (Crucial for Margins):
  • Wines marked on_sale = true (red-tag specials) do not receive an additional 10% discount, but do count toward the quantity threshold.
  • Ultra-premium or allocated bottles (e.g. Opus One, Caymus Special Selection, Silver Oak) marked exclude_from_case_discount = true neither receive the discount nor count toward the threshold.
  • 1.75L magnum bottles or 3L box wines do not qualify unless specifically tagged.

interface CartItem {
  productId: number;
  category: string;
  volumeMl: number;
  unitPrice: number;
  isOnSale: boolean;
  excludeCaseDiscount: boolean;
  quantity: number;
}

function evaluateWineCaseDiscount(cart: CartItem[]): DiscountResult[] {
  // Filter eligible wine items
  const eligibleItems = cart.filter(
    item => item.category === 'Wine' && 
            item.volumeMl === 750 && 
            !item.excludeCaseDiscount
  );

  const totalBottles = eligibleItems.reduce((acc, item) => acc + item.quantity, 0);

  let discountRate = 0;
  if (totalBottles >= 12) {
    discountRate = 0.15; // 15% Case Discount
  } else if (totalBottles >= 6) {
    discountRate = 0.10; // 10% Half-Case Discount
  }

  if (discountRate === 0) return [];

  // Apply discount only to non-sale bottles
  return eligibleItems
    .filter(item => !item.isOnSale)
    .map(item => ({
      productId: item.productId,
      discountName: totalBottles >= 12 ? '15% Wine Case Discount' : '10% Wine Half-Case Discount',
      amountOffPerUnit: Number((item.unitPrice * discountRate).toFixed(2))
    }));
}

2. Craft Beer "Pick-6" Mix-and-Match Bundle

• The Problem: Customers love selecting 6 different craft beer single cans from the cooler. Ringing them up at regular individual retail prices (e.g. $2.75 to $3.50 each = $19.50) discourages discovery, while discounting them manually creates cashier errors.
• The Solution:
  • Tag participating craft singles with mix_and_match_group = 'craft_pick_6'.
  • When any multiple of 6 items from this group is in the cart, the system bundles them into a flat $12.99 Bundle.
  • The discount difference is distributed proportionally across the 6 lines so COGS and revenue remain mathematically accurate.

3. Volume Tier Breaks (Single vs. 4-Pack vs. Case)

• When items are not packaged as a single unit or when customers buy loose units:
  • 1 Single Can: $3.25
  • 4 Single Cans: $11.49 ($2.87/can)
  • 24 Cans (Case): $49.99 ($2.08/can)
• The POS automatically detects when the threshold is crossed and applies the tier pricing.

3. Scheduled & Timed Happy Hour Pricing

Liquor stores often run time-bounded promotions (e.g., "Friday Afternoon Growler Fill Special" or "College Night 10% Off Craft Beer between 4 PM and 7 PM on Thursdays").

Rule Schema

CREATE TABLE promotional_rules (
    id SERIAL PRIMARY KEY,
    name VARCHAR(150) NOT NULL,
    discount_type VARCHAR(50) NOT NULL,    -- 'percentage', 'flat_bundle', 'fixed_amount_off'
    discount_value NUMERIC(10, 2) NOT NULL,
    
    -- Target Matching
    target_category_id INT REFERENCES categories(id),
    target_tag VARCHAR(50),                -- e.g. 'craft_pick_6', 'wine_750ml'
    min_quantity_threshold INT DEFAULT 1,
    
    -- Schedule Constraints
    days_of_week INT[] DEFAULT '{0,1,2,3,4,5,6}', -- 0=Sun, 6=Sat
    start_time TIME DEFAULT '00:00:00',
    end_time TIME DEFAULT '23:59:59',
    start_date DATE,
    end_date DATE,
    
    -- Stacking & Exclusions
    exclude_sale_items BOOLEAN DEFAULT TRUE,
    priority_level INT DEFAULT 10,
    is_active BOOLEAN DEFAULT TRUE
);

4. Customer Loyalty, Phone Lookup & Wholesale Accounts

1. Zero-Friction Cashier Lookup

• Entering customer phone numbers must never disrupt scanning.
• Cashier presses F1 or types phone: 9705551234 in the main input bar.
• System resolves customer in under 20ms and displays name, loyalty tier, and available reward balance on the header HUD.

2. Wholesale / Commercial Accounts (B2B Liquor Orders)

• Local bars, catering companies, and charity events often purchase wholesale alcohol from retail package stores.
• Wholesale features:
  • Tax-Exempt Status: Automatically suppresses sales tax when a verified state resale permit is attached.
  • Custom Price Sheets: Automatic assignment of Wholesale Tier (Cost + 12%) across the entire transaction.
  • Invoice Terms: Ability to tender sale as AR_House_Account (Accounts Receivable Net 15/30) rather than immediate credit card tender.