Files

Samir Boulahtit f141cc4e6a docs: migrate module documentation to single source of truth

Move 39 documentation files from top-level docs/ into each module's
docs/ folder, accessible via symlinks from docs/modules/. Create
data-model.md files for 10 modules with full schema documentation.
Replace originals with redirect stubs. Remove empty guide stubs.

Modules migrated: tenancy, billing, loyalty, marketplace, orders,
messaging, cms, catalog, inventory, hosting, prospecting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-08 23:38:37 +01:00

4.3 KiB

Raw Blame History

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

API Endpoints

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

Method	Endpoint	Description
`GET`	`/program`	Get store's loyalty program
`POST`	`/program`	Create loyalty program
`PATCH`	`/program`	Update loyalty program
`GET`	`/stats`	Get program 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`	`/points`	Earn points from purchase
`POST`	`/points/redeem`	Redeem points for reward
`*`	`/pins/*`	Staff PIN management

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

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

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

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
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

4.3 KiB Raw Blame History