URD: Loyalty
| Module | EXT-01 | Version | v0.2 |
|---|---|---|---|
| Status | Planned | Date | 2026-06-04 |
Business documentation. This URD is Loyalty's feature list - each feature below is one Functional Area (
<AREA>). The same<AREA>keys the feature's PRDs (PRD-<AREA>-NNN) and tests (TC-<AREA>-NNN), and each feature is listed in the Delivery feature catalog. See the Feature Spine convention.
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. Mirrored in the Delivery feature catalog.
| Feature ID | Feature | Phase | 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 |