URD: Loyalty
| Module | Version | Updated |
|---|---|---|
EXT-01 | v0.2 | 2026-06-04 |
1. Purpose
Reward repeat customers so they return more often and spend more. The module turns completed purchases into points, lets customers climb tiers, and exchange points for rewards.
2. Scope
| Included | Excluded |
|---|---|
| Earning points on completed orders | Cross-merchant point sharing |
| Tiers, rewards catalog, redemption | Paid membership billing |
| Referral & birthday rewards | Message delivery (handled by Marketing) |
3. Definitions
| Term | Definition |
|---|---|
| Point | Unit of loyalty value earned on spend; redeemable for rewards |
| Tier | Membership level (e.g. Bronze/Silver/Gold) granting benefits |
| Earning rate | Conversion of order value to points, set per merchant |
| Redemption | Spending points for a discount or reward |
4. Conceptual Model
Conceptual only - full schema lives in the developer customer-points docs.
5. Feature Catalog
The feature list of this module. Each row is one feature (a Functional Area). Detail in §6.
| Feature ID | Feature | Phase | Epic | Status | Priority |
|---|---|---|---|---|---|
PTS | Points Earning | P1 | — | Built | High |
RDM | Redemption & Tiers | P2 | — | Planned | Medium |
Status: live from Plane where mapped, otherwise registry-declared. Vocabulary mirrors Plane (state-group / phase).
6. Features
One sub-section per feature, in catalog order. Each feature keeps its description, requirements, and acceptance together. Priority = MoSCoW (Must / Should / Could / Won't).
PTS - Points Earning Planned
Feature ID: loyalty/PTS · Phase: P1 · PRDs: - · Dev: @nx/sale
What it does for users: when a customer-linked order completes payment, points are awarded automatically to the customer's balance, once per order, using the merchant's configurable earning rate.
Requirements
| ID | P | Requirement |
|---|---|---|
| URD-PTS-001 | M | Award points when an order completes payment |
| URD-PTS-002 | M | Earning must be idempotent per order (no double award) |
| URD-PTS-003 | S | Earning rate is configurable per merchant |
Acceptance
AC-PTS-01: Points awarded on completed order
| Given | When | Then |
|---|---|---|
| A customer-linked order with a non-zero earning rate | The order completes payment | Points = total × rate are added once to the customer balance |
RDM - Redemption & Tiers Planned
Feature ID: loyalty/RDM · Phase: P2 · PRDs: - · Dev: @nx/sale
What it does for users: customers spend their points for discounts at checkout, climb membership tiers based on lifetime points, and redeem from a merchant-configured rewards catalog.
Requirements
| ID | P | Requirement |
|---|---|---|
| URD-RDM-001 | S | Redeem points for a discount at checkout |
| URD-RDM-002 | C | Assign customers to tiers by lifetime points |
| URD-RDM-003 | C | Configure a rewards catalog |
Acceptance
AC-RDM-01: Redeem points for a discount
| Given | When | Then |
|---|---|---|
| A customer with a sufficient point balance | They redeem points at checkout | A discount is applied and the balance is reduced accordingly |
7. Constraints & Non-Goals
Constraints
| ID | Constraint |
|---|---|
| C-01 | Points only accrue to identified customers (anonymous sales earn nothing) |
| C-02 | A single order awards points at most once |
Non-Goals
- Cross-merchant or franchise-wide point pooling
- Marketing message delivery (owned by Marketing)
8. Version History
| Date | Author | Description | Ver |
|---|---|---|---|
| 2026-05-30 | PM | Initial stub; earning live, rest planned | v0.1 |
| 2026-06-04 | Claude (AI pair) | Reorganize by feature (Feature Spine); each feature carries its own requirements + acceptance | v0.2 |