What is Reward Points?

Reward Points is a customer-loyalty primitive: earn on purchase (and other configured events), redeem at checkout for a discount on a future order. The platform tracks every credit and debit in the points_transactions table — every balance number you see is a sum-of-transactions.

                ┌──────────────────────────────┐
                │         Customer earns       │
                │    purchase, signup, review, │
                │    referral, birthday        │
                └──────────────┬───────────────┘
                               │ event → reward_listener
                               ▼
                ┌──────────────────────────────┐
                │   points_transactions row    │
                │   type=earn, points=+100     │
                └──────────────┬───────────────┘
                               │
                               ▼
                ┌──────────────────────────────┐
                │     Customer redeems         │
                │     at checkout, up to       │
                │     max_redeem_percentage    │
                └──────────────┬───────────────┘
                               │ → row type=redeem, points=-N
                               ▼
                ┌──────────────────────────────┐
                │  expiry_days cron sweeps     │
                │  unredeemed points after N   │
                └──────────────────────────────┘

What's stored

• reward_config — single-row tenant config: points_per_unit, redemption_rate, min_redeem_points, max_redeem_percentage, expiry_days.
• points_transactions — append-only ledger. Each row is a credit (positive points) or debit (negative). Type column distinguishes earn, redeem, expire, adjust, bonus.
• Bonus points (signup, review, referral, birthday) are set in reward_config and paid as bonus rows with a unique key, so each one pays once. Referrals use reward_referral_codes and reward_referrals.
• point_rates — per-object overrides for product / category / vendor (custom points_per_unit for specific objects).

A user's "balance" = sum of points for that user, after subtracting expired ones. Computed on read; no materialised counter.

What's distinct from Wallet, Vouchers, Gift Certs

Reward Points is the only one that auto-credits based on customer behaviour. The others are merchant-issued.

Accounting note

Earned reward points are a contingent liability for accounting purposes (you owe the customer value if they redeem). Recognise as expense at redemption, NOT at issuance. Match this to the points_transactions ledger — type = redeem rows are the trigger for recognition.