# Product Requirements Document

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (not assumptions)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
Empower resale store owners to run flexible, branded "Comeback Cash" promotional campaigns that reward customers on both buy and sales transactions, driving repeat visits and increasing customer lifetime value through automated coupon generation, SMS reminders, and seamless POS-integrated redemption.

### Problem Statement
Resale store owners currently have limited tools to create customer loyalty incentives that span both sides of their business (buying items FROM customers and selling items TO customers). The existing Receipt Coupon system is text-only with no redemption tracking, while the Loyalty Coupon system focuses on seller marketing without flexible event-based programs. Store owners cannot:
- Run "Kohl's Cash" style tiered earning programs (spend $X, earn $Y)
- Create time-boxed promotional events with automatic start/end dates
- Track coupon generation and redemption across both transaction types
- Offer "double-up" incentives for high-value transactions
- Remind customers via SMS when their earned coupons become redeemable

This results in missed opportunities to drive repeat business, inconsistent promotional execution, and no visibility into campaign effectiveness.

### Value Proposition
Comeback Cash provides a unified, flexible coupon platform that:
- **Drives Repeat Visits**: Customers earn rewards they must return to redeem, creating a built-in reason to come back
- **Spans Both Sides**: Works for both buy transactions (sellers bringing items) and sales transactions (customers purchasing)
- **Automates Campaigns**: Event-based programs run themselves with configurable start/end dates and SMS reminders
- **Integrates Seamlessly**: POS systems receive real-time settings updates and can POST new coupons automatically
- **Provides Visibility**: Track generation, redemption rates, and campaign ROI in one place
- **Offers Flexibility**: Configure tiered earning, flat rewards, minimum purchases, double-up options, and expiration windows

## User Personas

### Primary Persona: Store Owner/Manager (Campaign Creator)
- **Demographics:** Age 30-55, owns or manages a resale/consignment store, moderate technical expertise, comfortable with web-based admin tools
- **Goals:**
  - Increase customer return rate and average transaction value
  - Run seasonal promotional campaigns with minimal ongoing effort
  - Understand which promotions drive the best ROI
  - Compete with larger retailers' loyalty programs (Kohl's Cash, etc.)
- **Pain Points:**
  - Current coupon system requires manual tracking and has no visibility into effectiveness
  - Cannot easily run time-limited "events" without remembering to turn things on/off
  - No way to incentivize both buy-side sellers AND sales-side customers in a unified program
  - POS doesn't automatically sync with coupon settings, leading to errors

### Secondary Personas

#### Store Employee (Coupon Redeemer)
- **Demographics:** Age 18-35, part-time or full-time retail employee, basic technical skills, uses workspace daily
- **Goals:**
  - Quickly validate and redeem customer coupons during checkout
  - Avoid errors that upset customers or require manager intervention
  - Understand what the customer's coupon is worth without extensive training
- **Pain Points:**
  - No quick way to scan/lookup coupon codes during busy periods
  - Unclear which coupons are valid vs. expired
  - Manual processes slow down checkout

#### Customer (Coupon Recipient)
- **Demographics:** Age 25-65, shops at resale stores for value, varying technical comfort
- **Goals:**
  - Earn rewards for shopping/selling at their favorite resale store
  - Remember when their coupons are valid and not miss the redemption window
  - Easily use earned rewards without confusion
- **Pain Points:**
  - Forgets about earned coupons or loses paper receipts
  - Doesn't know when redemption period starts/ends
  - Confusion about minimum purchase requirements

#### POS System (Integration Consumer)
- **Demographics:** N/A - software system
- **Goals:**
  - Receive current coupon program parameters in real-time
  - POST newly generated coupons to the server when customers qualify
  - Stay synchronized with server-side coupon settings
- **Pain Points:**
  - No real-time notification when settings change
  - Must poll for updates or risk using stale parameters

## User Journey Maps

### Primary User Journey: Store Owner Creates Sales-Side Campaign ("Fashion Financial Aid")
1. **Awareness:** Store owner wants to run a back-to-school promotion similar to Kohl's Cash. Sees competitors offering "spend and get" promotions.
2. **Consideration:** Evaluates paper coupon tracking (error-prone), third-party loyalty apps (expensive, separate system), or building on existing infrastructure. Needs something integrated with their POS.
3. **Adoption:** Discovers Comeback Cash in workspace settings. Sees it can handle both buy and sales sides independently with flexible parameters. Creates first "event."
4. **Usage:**
   - Owner accesses Comeback Cash settings in workspace admin
   - Creates new "Sales-Side Event" named "Fashion Financial Aid August"
   - Sets parameters: Spend $75+ in August → Earn $30 off $60+ in September
   - Enables "double-up" option for purchases over $150
   - Sets event start date (Aug 1) and end date (Aug 31)
   - Sets redemption window (Sep 1 - Sep 30)
   - Enables SMS reminder option
   - Saves and POS receives real-time Ably notification
5. **Retention:** Owner sees redemption reports showing 40% return rate, calculates ROI, plans next seasonal event.

### Secondary User Journeys

#### Journey: Customer Earns and Redeems Sales-Side Comeback Cash
1. **Earning:** Customer makes $85 purchase in August. POS calculates eligibility, generates unique coupon code, POSTs to server.
2. **Notification:** Customer provides phone number. Receipt shows earned coupon. SMS scheduled for Sep 1: "Your $30 Comeback Cash is now redeemable!"
3. **Reminder:** Customer receives SMS on Sep 1 with coupon code and expiration date.
4. **Redemption:** Customer returns in September, presents coupon code at checkout. Employee scans barcode in workspace, system validates, applies $30 discount to $65 purchase.
5. **Completion:** Coupon marked as redeemed in system. Customer sees success confirmation.

#### Journey: Store Owner Creates Buy-Side Campaign ("Seller Appreciation")
1. **Awareness:** Owner wants to encourage sellers to return as buyers after selling items.
2. **Setup:**
   - Creates "Buy-Side Event" named "Seller Appreciation Q4"
   - Sets coupon value: $10 (flat amount - every completed buy transaction earns this)
   - Sets minimum purchase for redemption: $30+ (pre-tax)
   - Sets earning window (Oct 1 - Dec 31)
   - Sets redemption window (same period - immediate use allowed)
   - **Note:** No minimum payout threshold configured - ANY completed buy transaction qualifies
3. **Execution:** Seller brings in items (regardless of payout amount), completes buy transaction, receives $10 coupon automatically.
4. **Cross-sell:** Seller browses store, finds items, uses coupon on same visit or returns later.

#### Journey: Employee Redeems Coupon at Checkout
1. **Trigger:** Customer presents coupon code (paper receipt, phone screenshot, or verbal code)
2. **Access:** Employee clicks "Redeem Coupon" in workspace sidebar (or uses keyboard shortcut)
3. **Scan:** Quick-action modal opens with barcode input focused. Employee scans code or types manually.
4. **Validation:** System checks: Is code valid? Is it within redemption window? Is minimum purchase met? Has it been used?
5. **Result:**
   - **Valid:** Green confirmation with discount amount. Employee applies to transaction.
   - **Invalid:** Red error with specific reason (expired, already used, minimum not met).
6. **Completion:** Coupon marked as redeemed with timestamp and store info.

#### Journey: POS System Synchronizes Settings
1. **Initialization:** POS app starts, calls GET `/api/:typeNum/comeback-cash/settings` to fetch current parameters
2. **Configuration:** POS stores settings locally for offline operation capability
3. **Real-time Update:** Store owner changes campaign settings in workspace
4. **Notification:** Server publishes Ably event `coupon:settings:updated` on store channel
5. **Sync:** POS receives event, calls GET endpoint to refresh settings
6. **Generation:** During qualifying transaction, POS generates unique code locally, POSTs to server

## Feature Requirements

### Must Have Features

#### Feature 1: Event Configuration (Sales-Side)
- **User Story:** As a store owner, I want to create sales-side Comeback Cash events with flexible earning rules so that I can run promotions similar to Kohl's Cash.
- **Acceptance Criteria:**
  - [ ] Can create named events with start and end dates for the earning period
  - [ ] Can configure earning threshold (spend $X to earn coupon) - based on pre-tax subtotal, excluding any Comeback Cash discounts
  - [ ] Can configure coupon value (earn $Y amount)
  - [ ] Can configure minimum purchase requirement for redemption (must spend $Z pre-tax to use)
  - [ ] Can set redemption window (valid from date A to date B)
  - [ ] Can enable/disable double-up option (spend 2X threshold, earn 2X coupon)
  - [ ] Can configure refund policy: "forfeit coupon on return" OR "reinstate coupon on return"
  - [ ] Can have multiple events (only one active sales-side event at a time)
  - [ ] Events automatically activate and deactivate based on configured dates

#### Feature 2: Event Configuration (Buy-Side)
- **User Story:** As a store owner, I want to create buy-side Comeback Cash events so that sellers who bring items are incentivized to return as buyers.
- **Acceptance Criteria:**
  - [ ] Can create named buy-side events with start and end dates
  - [ ] Trigger type: any completed buy transaction earns a coupon (no minimum payout threshold)
  - [ ] Can configure coupon value (flat amount - same value for all qualifying transactions)
  - [ ] Can configure minimum purchase requirement for redemption (pre-tax subtotal)
  - [ ] Can set redemption window
  - [ ] Can configure refund policy: "forfeit coupon on return" OR "reinstate coupon on return"
  - [ ] Buy-side and sales-side events are configured independently
  - [ ] Can have multiple events (only one active buy-side event at a time)

**Important Distinction:** Buy-side events differ from sales-side in that they do NOT have tiered earning thresholds. Any completed buy transaction (customer selling items to the store) earns the configured flat coupon amount, regardless of payout value. This simplifies the incentive: "Bring in items, get a coupon."

#### Feature 3: Coupon Generation API (POS Integration)
- **User Story:** As a POS system, I want to POST newly generated coupons to the server so that coupons are tracked centrally.
- **Acceptance Criteria:**
  - [ ] POST `/api/:typeNum/comeback-cash/coupons` endpoint accepts coupon data
  - [ ] Accepts: coupon code, customer phone (optional), transaction amount, transaction type (buy/sale), event ID
  - [ ] Server validates code uniqueness and event eligibility
  - [ ] Returns success with coupon details or error with specific reason
  - [ ] CSRF protection or API key authentication

#### Feature 4: Settings Retrieval API (POS Integration)
- **User Story:** As a POS system, I want to GET current Comeback Cash settings so that I know the active program parameters.
- **Acceptance Criteria:**
  - [ ] GET `/api/:typeNum/comeback-cash/settings` returns current active events
  - [ ] Response includes all parameters needed for POS to determine eligibility
  - [ ] Response indicates which events are currently active vs. scheduled vs. ended
  - [ ] Supports authentication via API key or session

#### Feature 5: Real-Time Settings Sync (Ably Integration)
- **User Story:** As a POS system, I want to receive real-time notifications when Comeback Cash settings change so that I always have current parameters.
- **Acceptance Criteria:**
  - [ ] When settings are saved, server publishes `coupon:settings:updated` event via Ably
  - [ ] Event includes event ID and action type (created, updated, deleted, activated, deactivated)
  - [ ] POS can subscribe to store channel and listen for coupon events
  - [ ] Event payload is lightweight (POS should call GET endpoint for full details)

#### Feature 6: Coupon Redemption Interface (Workspace)
- **User Story:** As a store employee, I want to quickly scan or enter a coupon code to validate and redeem it so that checkout is fast and accurate.
- **Acceptance Criteria:**
  - [ ] Accessible from workspace sidebar or keyboard shortcut
  - [ ] Opens quick-action modal with auto-focused barcode input
  - [ ] Supports barcode scanner input (USB keyboard emulation)
  - [ ] Supports manual code entry
  - [ ] Displays validation result within 1 second
  - [ ] Shows coupon value, minimum purchase, and expiration for valid coupons
  - [ ] Shows specific error reason for invalid coupons (expired, used, not found, minimum not met)
  - [ ] One-click to mark as redeemed
  - [ ] Redeemed coupons cannot be redeemed again

#### Feature 7: Coupon Database (Store-Level)
- **User Story:** As a store, I want coupons stored in my store database so that coupon data is isolated per store.
- **Acceptance Criteria:**
  - [ ] Coupon tables created at store database level (not central)
  - [ ] Stores coupon code, value, status, customer info, timestamps
  - [ ] Tracks earning transaction details
  - [ ] Tracks redemption transaction details
  - [ ] Supports querying by status, date range, customer

### Should Have Features

#### Feature 8: SMS Reminder System
- **User Story:** As a customer, I want to receive an SMS when my Comeback Cash becomes redeemable so that I don't forget to use it.
- **Acceptance Criteria:**
  - [ ] Customer phone number captured during coupon generation
  - [ ] SMS sent on redemption period start date
  - [ ] SMS includes coupon code, value, and expiration date
  - [ ] Uses existing SMS infrastructure (Twilio/Vonage)
  - [ ] Opt-in during coupon generation (customer provides number)

#### Feature 9: Admin Reporting Dashboard
- **User Story:** As a store owner, I want to see Comeback Cash performance metrics so that I can evaluate campaign effectiveness.
- **Acceptance Criteria:**
  - [ ] View coupons generated by event
  - [ ] View redemption rate (redeemed / generated)
  - [ ] View total discount given
  - [ ] Filter by date range and event
  - [ ] Export report data

#### Feature 10: Tiered Earning Structure (Kohl's Cash Style)
- **User Story:** As a store owner, I want to configure tiered earning levels so that higher spenders earn proportionally more.
- **Acceptance Criteria:**
  - [ ] Configure multiple tiers: spend $50 earn $10, spend $100 earn $25, spend $150 earn $40
  - [ ] System applies highest applicable tier
  - [ ] Tiers are configurable per event

### Could Have Features

#### Feature 11: Customer Coupon Lookup Portal
- **User Story:** As a customer, I want to look up my earned coupons online so that I can see what I have available.
- **Acceptance Criteria:**
  - [ ] Public page accessible via link or phone number lookup
  - [ ] Shows all earned coupons for that phone number
  - [ ] Shows status (pending, active, redeemed, expired)

#### Feature 12: Automatic Expiration Processing
- **User Story:** As a system, I want to automatically mark expired coupons so that the database stays accurate.
- **Acceptance Criteria:**
  - [ ] Background job runs daily
  - [ ] Updates status of expired coupons
  - [ ] Optional: Send "last chance" SMS before expiration

#### Feature 13: Coupon Stacking Rules
- **User Story:** As a store owner, I want to control whether multiple Comeback Cash coupons can be used in one transaction.
- **Acceptance Criteria:**
  - [ ] Configuration option: allow/disallow stacking
  - [ ] If disallowed, redemption interface shows warning when customer has multiple coupons

### Won't Have (This Phase)

- **Cross-Store Redemption:** Coupons are valid only at the issuing store. Multi-store redemption is out of scope.
- **Points System:** This is a coupon system, not a points accumulation system. No earning/burning points.
- **Mobile App Integration:** Focus is on POS and workspace. Native mobile app features are out of scope.
- **Automated A/B Testing:** No built-in experimentation framework for comparing campaign variants.
- **Integration with External Loyalty Programs:** No FiveStars or other third-party loyalty integration.
- **Gift Card Functionality:** Comeback Cash is discount coupons only, not stored value cards.

## Detailed Feature Specifications

### Feature: Event Configuration System
**Description:** The Event Configuration System allows store owners to create, manage, and schedule Comeback Cash promotional events. Each store can have independent buy-side and sales-side events running simultaneously. Events define the rules for earning coupons and the windows during which they can be redeemed.

**User Flow:**
1. Store owner navigates to Comeback Cash settings in workspace admin
2. System displays current events (active, scheduled, ended) for both buy-side and sales-side
3. Owner clicks "Create New Event" and selects type (Buy-Side or Sales-Side)
4. Owner fills in event details:
   - Event name (e.g., "Fashion Financial Aid August 2025")
   - Earning period start/end dates
   - Redemption period start/end dates
   - Earning rules (threshold amounts, coupon values)
   - Double-up option (sales-side only)
   - Minimum purchase for redemption
5. System validates inputs (dates logical, values positive, no overlap with active events)
6. Owner saves event
7. System stores event, publishes Ably notification, displays confirmation

**Business Rules:**
- Rule 1: Only one sales-side event can be active at any time. Scheduled events cannot have overlapping earning periods.
- Rule 2: Only one buy-side event can be active at any time. Same overlap rules apply.
- Rule 3: Earning period must be before or equal to redemption period start (customers earn then redeem).
- Rule 4: Redemption period must end after earning period (can overlap if immediate redemption allowed).
- Rule 5: **Sales-Side Only:** When double-up is enabled, customer spending 2x the threshold earns 2x the coupon value. Spending 3x earns 2x (not 3x) - double-up caps at 2x. Buy-side does NOT support double-up (every transaction earns exactly one coupon).
- Rule 6: Events auto-activate at midnight on earning period start date (store timezone).
- Rule 7: Events auto-deactivate at 11:59 PM on earning period end date.
- Rule 8: Coupons generated during earning period remain valid until redemption period end, regardless of event status.
- Rule 9: Minimum purchase for redemption must be greater than or equal to coupon value to prevent "free money."
- Rule 10: Editing an active event only affects future coupon generation; existing coupons retain their original terms.
- Rule 11: **Refund Policy** - Store owner configures per event: either (a) coupon is forfeited on return, or (b) coupon is reinstated to active status for reuse.
- Rule 12: **Coupon Transferability** - Coupons are bearer instruments. Anyone with the code can redeem it. No phone number verification required at redemption.
- Rule 13: **Sales-Side Transaction Amount Changes** - POS determines final eligibility. Server accepts whatever POS posts. If customer removes items and final amount drops below threshold, POS should NOT post the coupon.
- Rule 14: **Minimum Purchase Threshold** - All minimum purchase thresholds for redemption are pre-tax (merchandise subtotal only).
- Rule 15: **Sales-Side Earning Calculation** - Earning thresholds (tiered) are calculated on net transaction amount AFTER any Comeback Cash discounts are applied. Customer using $30 coupon on $85 transaction has $55 net (does not qualify for $75 threshold).
- Rule 16: **Buy-Side Earning (NO Threshold)** - Buy-side events do NOT have earning thresholds. ANY completed buy transaction (customer selling items to the store) earns the flat configured coupon value, regardless of payout amount. "Bring in items = get a coupon."
- Rule 17: **No Maximum Coupon Value Limit** - Store owners configure coupon values as needed for their business. No system-enforced maximum.
- Rule 18: **No Manual Coupon Creation** - All coupons must originate from valid POS transactions. No manual/service recovery coupon creation in workspace.

**Edge Cases:**
- Scenario 1: Owner tries to create overlapping events → System shows validation error, prevents save.
- Scenario 2: Owner sets redemption end before earning end → System warns but allows (immediate redemption scenario).
- Scenario 3: Owner tries to delete event with unredeemed coupons → System warns, requires confirmation. Existing coupons remain valid (soft delete event, retain coupon data).
- Scenario 4: Timezone boundary - earning period crosses midnight → Use store's configured timezone, not UTC.
- Scenario 5: Customer qualifies for coupon but POS is offline → POS generates coupon locally, POSTs when back online. Server validates event was active at transaction time.
- Scenario 6: Double-up enabled mid-event → Only applies to transactions after the change.
- Scenario 7: Customer returns items purchased with coupon → Based on event's refund policy setting: coupon forfeited OR reinstated.
- Scenario 8: Customer shares coupon code with friend → Allowed. Coupons are bearer instruments with no identity verification.
- Scenario 9: Customer removes items at register, total drops below threshold → POS decides whether to issue coupon. Server accepts POS decision.
- Scenario 10: Customer uses $30 Comeback Cash coupon on $85 purchase, tries to earn new coupon → Net amount is $55, below $75 threshold. No new coupon earned.
- Scenario 11: Coupon code collision over time (same code from different events) → Include event ID prefix or timestamp component in code generation to prevent.
- Scenario 12: Customer earns coupon but loses phone/changes number → Not an issue - coupon is bearer instrument, phone only used for SMS reminder (optional).

## Success Metrics

### Key Performance Indicators

- **Adoption:** 50%+ of active stores create at least one Comeback Cash event within 3 months of launch
- **Engagement:** Average of 2+ events created per store per quarter among adopters
- **Quality:** <1% coupon validation errors (invalid codes, system errors); >95% redemption attempts complete within 3 seconds
- **Business Impact:**
  - 25%+ redemption rate (coupons redeemed / coupons generated)
  - 15%+ increase in repeat customer visits during redemption periods (compared to baseline)
  - Average order value during redemption visits exceeds minimum purchase by 20%+

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `comeback_cash.event_created` | event_id, event_type (buy/sale), store_id, earning_threshold, coupon_value, earning_start, earning_end, redemption_start, redemption_end, double_up_enabled | Track event configuration patterns |
| `comeback_cash.event_activated` | event_id, event_type, store_id, timestamp | Monitor auto-activation reliability |
| `comeback_cash.coupon_generated` | coupon_code, event_id, store_id, transaction_amount, transaction_type, customer_phone_provided, coupon_value | Track coupon generation volume |
| `comeback_cash.coupon_validated` | coupon_code, store_id, validation_result (valid/expired/used/not_found/minimum_not_met), response_time_ms | Monitor validation accuracy and performance |
| `comeback_cash.coupon_redeemed` | coupon_code, event_id, store_id, redemption_amount, discount_applied, days_until_expiration | Track redemption patterns |
| `comeback_cash.settings_synced` | store_id, trigger (ably/manual_refresh), success, latency_ms | Monitor POS sync reliability |
| `comeback_cash.sms_reminder_sent` | coupon_code, store_id, delivery_status | Track SMS reminder effectiveness |

---

## Constraints and Assumptions

### Constraints
- **Technical Platform:** Must integrate with existing PHP/Slim stack, MySQL multi-store architecture, and Ably real-time infrastructure
- **Database Architecture:** Coupon data must be at store level (kiosk_{typeNum} databases), not central database
- **SMS Infrastructure:** Must use existing Twilio/Vonage SMS system; no new SMS provider integration
- **POS Dependency:** POS system must be modified to support coupon generation and sync; coordination with POS development required
- **Authentication:** API endpoints must support both session-based auth (workspace) and API key auth (POS)
- **Barcode Format:** Must accommodate existing barcode scanner hardware; codes should be alphanumeric, human-readable length (8-12 chars)

### Assumptions
- **User Behavior:** Store owners will configure events in advance, not last-minute; most will use simple single-tier configurations initially
- **POS Capability:** POS system can generate unique coupon codes locally and POST to server; POS has Ably connectivity
- **SMS Opt-in:** Customers will opt-in to SMS reminders at meaningful rates (>30%) when offered during checkout
- **Transaction Timing:** Buy and sale transactions occur within POS operating hours; no 24/7 operation considerations
- **Network Reliability:** Stores have reasonably stable internet; offline-first design for POS is "should have" not "must have"
- **Existing Infrastructure:** Ably channels are already set up per store; migration system is functional and tested

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| POS development delays block feature launch | High | Medium | Design API contract first; allow phased rollout (workspace redemption first, POS generation second) |
| Coupon code collisions across stores | Medium | Low | Use store prefix in code generation; validate uniqueness on POST |
| SMS delivery failures cause customer complaints | Medium | Medium | Provide fallback (email, coupon visible in customer portal); track delivery rates |
| Store owners create confusing overlapping events | Medium | Medium | Enforce "one active event per type" rule; clear UI showing event timeline |
| High coupon fraud (employees creating fake coupons) | High | Low | Require valid source transaction for each coupon; audit logging; redemption tied to employee ID |
| Performance issues with high coupon volume | Medium | Low | Index key query fields; consider Redis caching for validation endpoint |
| Timezone confusion causes activation issues | Medium | Medium | Store timezone prominently; show "activates in X hours" preview; use store's configured timezone consistently |

## Open Questions

- [x] Should coupon codes be generated by POS or server? → **Decision: POS generates, server validates and stores**
- [x] Should we allow multiple coupons per transaction (stacking)? → **Decision: "Could Have" feature, not MVP**
- [x] How should refunds be handled? → **Decision: Store owner configures per event (forfeit OR reinstate)**
- [x] Should coupons be transferable? → **Decision: Yes, bearer instruments (anyone with code can redeem)**
- [x] What about transaction amount changes after coupon qualification? → **Decision: POS decides, server accepts**
- [x] Should we allow manual coupon creation? → **Decision: No, POS transactions only**
- [x] Pre-tax or post-tax for minimum purchase threshold? → **Decision: Pre-tax (merchandise subtotal)**
- [x] Does earning threshold include coupon discounts? → **Decision: No, net amount after discounts**
- [x] Is there a maximum coupon value to prevent abuse? → **Decision: No system limit, owner decides**
- [ ] What is the exact coupon code format? (8-char alphanumeric, QR code, etc.) - needs POS team input
- [ ] How will the barcode be printed on receipts? Does POS have receipt customization? - needs POS team input
- [ ] Should SMS reminder be sent at a specific time of day or midnight? - needs UX decision
- [ ] Should expired coupons be automatically purged or retained for reporting? - needs data retention policy input

---

## Supporting Research

### Competitive Analysis
- **Kohl's Cash:** Industry-leading "spend and get" program. Earn period followed by redemption window. Simple tiers ($50/$100/$150 earn $10/$20/$30). Drives 25%+ return visits during redemption.
- **JCPenney Rewards:** Points-based system with certificate rewards. More complex than coupon-based, lower customer understanding.
- **Stage Stores:** Tiered discount coupons printed on receipts. Limited tracking, no digital redemption.
- **Resale Industry:** Most competitors use paper coupons with no digital tracking. Opportunity for differentiation.

**Key Learnings:**
- Simple "spend X, get Y" messaging outperforms complex point calculations
- Time-limited redemption windows create urgency
- SMS/push notifications dramatically increase redemption rates
- Minimum purchase requirements ensure profitability

### User Research
- **Existing Data:** Receipt Coupon feature has low visibility - customers often forget paper coupons
- **Store Owner Feedback:** Desire for "Kohl's Cash style" promotions mentioned in support tickets
- **Employee Input:** Request for faster coupon lookup during busy periods (current manual process is slow)

### Market Data
- 68% of consumers say loyalty programs make them more likely to continue doing business (Bond Loyalty Report)
- Coupon redemption rates average 2-8% for digital coupons, 0.5-1% for paper (Valassis)
- SMS marketing has 98% open rate vs 20% for email (Mobile Marketing Association)
- Resale market growing 25% annually, with customer retention as key differentiator (ThredUp Resale Report)