orion/app/modules/loyalty/docs/index.md

Loyalty Programs

Stamp-based and points-based loyalty programs with Google Wallet and Apple Wallet integration. Includes anti-fraud features like staff PINs, cooldown periods, and daily limits.

Overview

Aspect	Detail
Code	loyalty
Classification	Optional
Dependencies	customers
Status	Active

Features

• loyalty_stamps — Stamp-based loyalty (collect N, get reward)
• loyalty_points — Points-based loyalty (earn per euro spent)
• loyalty_hybrid — Combined stamps and points programs
• loyalty_cards — Digital loyalty card management
• loyalty_enrollment — Customer enrollment flow
• loyalty_staff_pins — Staff PIN verification
• loyalty_anti_fraud — Cooldown periods, daily limits, lockout protection
• loyalty_google_wallet — Google Wallet pass integration
• loyalty_apple_wallet — Apple Wallet pass integration
• loyalty_stats — Program statistics
• loyalty_reports — Loyalty reporting

Permissions

Permission	Description
loyalty.view_programs	View loyalty programs
loyalty.manage_programs	Create/edit loyalty programs
loyalty.view_rewards	View rewards
loyalty.manage_rewards	Manage rewards

Data Model

See Data Model for full entity relationships.

• LoyaltyProgram — Program configuration (type, targets, branding)
• LoyaltyCard — Customer cards with stamp/point balances
• LoyaltyTransaction — Immutable audit log of all operations
• StaffPin — Hashed PINs for fraud prevention
• MerchantLoyaltySettings — Admin-controlled merchant settings
• AppleDeviceRegistration — Apple Wallet push notification tokens

Pages & Navigation

See Pages & Navigation for the full cross-persona page matrix, URL patterns, sidebar navigation, and shared component architecture.

All personas share the same page set with scope-appropriate access:

Page	Admin	Merchant	Store	Storefront
Program	Any merchant	Own	Own	Public
Analytics	Any merchant	Multi-store	Store-scoped	--
Cards/Members	Any merchant	All stores	Store-scoped	Own card
Transactions	Any merchant	Store filter	Store-scoped	Own history
Staff PINs	Read-only	Full CRUD	Full CRUD	--
Settings	Edit	Read-only	--	--
Terminal	--	--	POS	--

API Endpoints

Store Endpoints (/api/v1/store/loyalty/)

Method	Endpoint	Description
GET	/program	Get store's loyalty program
POST	/program	Create loyalty program
PUT	/program	Update loyalty program
DELETE	/program	Delete loyalty program
GET	/stats	Get program statistics
GET	/stats/merchant	Get merchant-wide statistics
GET	/cards	List customer cards
POST	/cards/enroll	Enroll customer in program
POST	/stamp	Add stamp to card
POST	/stamp/redeem	Redeem stamps for reward
POST	/stamp/void	Void stamps
POST	/points/earn	Earn points from purchase
POST	/points/redeem	Redeem points for reward
POST	/points/void	Void points
POST	/cards/{id}/points/adjust	Manual point adjustment (owner)
*	/pins/*	Staff PIN management (list, create, update, delete, unlock)

Merchant Endpoints (/api/v1/merchants/loyalty/)

Method	Endpoint	Description
GET/POST/PATCH/DELETE	/program	Program CRUD
GET	/stats	Merchant-wide statistics
GET	/cards	List cards across all stores
GET	/cards/{id}	Card detail
GET	/cards/{id}/transactions	Card transaction history
GET	/transactions	Merchant-wide transactions
*	/pins/*	Staff PIN management across stores
GET	/settings	Loyalty settings (read-only)
GET	/locations	Store list for filter dropdowns

Admin Endpoints (/api/v1/admin/loyalty/)

Method	Endpoint	Description
GET	/programs	List all loyalty programs
GET	/programs/{id}	Get specific program
GET	/stats	Platform-wide statistics
GET	/merchants/{mid}/cards	Merchant's cards (on behalf)
GET	/merchants/{mid}/cards/{cid}	Card detail (on behalf)
GET	/merchants/{mid}/transactions	Merchant's transactions
GET	/merchants/{mid}/pins	Merchant's PINs (read-only)
GET	/merchants/{mid}/locations	Merchant's stores
GET	/merchants/{mid}/stats	Merchant statistics
GET/PATCH	/merchants/{mid}/settings	Merchant settings
GET	/wallet-status	Wallet integration status
*	/debug/*	Wallet debug endpoints (super admin)

Storefront Endpoints (/api/v1/storefront/loyalty/)

Method	Endpoint	Description
GET	/card	Get customer's loyalty card
GET	/transactions	Transaction history
POST	/enroll	Self-enrollment
GET	/program	Public program info

Scheduled Tasks

Task	Schedule	Description
loyalty.sync_wallet_passes	Hourly	Sync cards that missed real-time updates
loyalty.expire_points	Daily 02:00	Expire points for inactive cards

Configuration

Environment variables (prefix: LOYALTY_):

Variable	Default	Description
LOYALTY_DEFAULT_COOLDOWN_MINUTES	15	Cooldown between stamps
LOYALTY_MAX_DAILY_STAMPS	5	Max stamps per card per day
LOYALTY_PIN_MAX_FAILED_ATTEMPTS	5	PIN lockout threshold
LOYALTY_PIN_LOCKOUT_MINUTES	30	PIN lockout duration
LOYALTY_DEFAULT_POINTS_PER_EURO	10	Points earned per euro
LOYALTY_GOOGLE_ISSUER_ID	—	Google Wallet issuer ID
LOYALTY_GOOGLE_SERVICE_ACCOUNT_JSON	—	Google service account path
LOYALTY_APPLE_*	—	Apple Wallet certificate paths

Additional Documentation

• Data Model — Entity relationships and database schema
• Business Logic — Anti-fraud system, wallet integration, enrollment flow
• Pages & Navigation — Cross-persona page matrix, URL patterns, shared components
• User Journeys — Detailed user journey flows with dev/prod URLs
• Program Analysis — Business analysis and platform vision
• UI Design — Admin and store interface mockups and implementation roadmap