18 — Loyalty

Programs, rules, multipliers, POS earn/redeem

CEO Summary

Loyalty programs drive repeat visits. Earn points on purchase; redeem as POS tender. Business value: Customer retention, spend increase. Key metrics: Active members, points issued/redeemed, redemption rate. If this breaks: POS cannot apply loyalty; customers lose points visibility.

Architecture

flowchart TB subgraph client [Client] POS[POS] Admin[Admin] end subgraph api [API] LR[loyalty.routes] LMR[loyaltyManagement.routes] POSR[pos.routes] end subgraph svc [Services] LS[loyalty.service] LPS[loyaltyPoints.service] LMS[loyaltyManagement.service] end subgraph db [Tenant DB] Programs[(LoyaltyPrograms)] Accounts[(LoyaltyAccounts)] Events[(LoyaltyEvents / audit_events)] end POS --> POSR Admin --> LR Admin --> LMR LR --> LS LMR --> LMS POSR --> LPS LS --> Programs LS --> Events LPS --> Accounts LPS --> Events

Overview

Loyalty programs define earn rules (points per dollar) and redemption rules. Customers earn on purchase; redeem at POS.

Base path: /api/loyalty, /api/loyalty-management
Auth: requireSessionAuth, tenantResolver
Feature gate: checkFeatureAccess('loyalty')

File Structure

backend/
├── routes/
│   ├── loyalty.routes.js           # Grant, redeem, balance
│   ├── loyaltyManagement.routes.js # Program CRUD
│   └── admin.programs.routes.js    # Admin programs
├── services/
│   ├── loyalty.service.js
│   ├── loyaltyPoints.service.js    # Earn/redeem logic
│   └── loyaltyManagement.service.js
└── models/
    ├── loyaltyProgram.model.js
    ├── loyaltyAccount.model.js
    └── loyaltyEvent.model.js

API Endpoints

Method	Path	Purpose
POST	/api/loyalty/grant	Manager grants points (customerId, points, reason)
POST	/api/loyalty/redeem	Redeem points (customerId, points, orderId, reason)
GET	/api/loyalty/balance/:customerId	Get customer balance
POST	/api/pos/carts/:id/tender/loyalty	POS tender: apply loyalty redemption

Database Schema

Table	Purpose
LoyaltyPrograms	Program config: earn rules, multipliers
LoyaltyAccounts	Customer balance per program
LoyaltyEvents / audit_events	Events: loyalty.grant, loyalty.redeem

Program Structure

Programs define rules (earn per dollar, category multipliers). Accounts hold customer points. Events log earn/redeem.

POS Integration

Earn: Points on sale (rules, multipliers). Redeem: POST /api/pos/carts/:id/tender/loyalty — deduct points, add to cart payments. See 06 — POS & Invoicing.

Integration Points

System	Connection
POS	Tender type: loyalty
Customers	customerId links to Customers
Analytics	posAnalytics.service, customerAnalytics — loyalty events
Audit	audit_events for loyalty.grant, loyalty.redeem

Key Paths

Path	Purpose
`backend/routes/loyalty.routes.js`	Grant, redeem, balance
`backend/services/loyaltyPoints.service.js`	Earn/redeem logic
`backend/models/loyaltyAccount.model.js`	Customer balance