SRV-30 — V2 — Loyalty engine (points ledger, rewards, vouchers)
Points ledger, base earning on delivery/payment, expiry job, reversals, rewards catalogue, redemptions and vouchers usable at checkout.
| Field | Details |
|---|---|
| Task code | SRV-30 |
| Phase | P4 — V2 evolutions |
| Product scope | V2 |
| Status | Planned |
| Start | Mon 25 Jan 2027 |
| Due | Thu 28 Jan 2027 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 3 person-day(s) planned · 8 from scratch · size M |
| Area · app | Server · server |
| Depends on | SRV-29 |
| Unblocks | SRV-31, SRV-44 |
| Milestones | — |
Summary
Points ledger, base earning on delivery/payment, expiry job, reversals, rewards catalogue, redemptions and vouchers usable at checkout.
Description
Advanced loyalty is V2 (cahier §4.4, §4.6, §5.5, §14.2; LOY-01…LOY-05, PRC-03). This task implements the points ledger (LoyaltyAccount, LoyaltyTransaction with EARN, BONUS, REDEEM, EXPIRE, ADJUST, REVERSAL), earning on delivery or payment according to a setting, bonuses, the expiry job, reversals when an order is cancelled or a return is received (V1 returns emit the events), the rewards catalogue and redemptions, and vouchers usable at checkout through the cart engine. It also adds the V2 pricing layer of PRC-03 — per-reseller price agreements and level-based prices on top of the three customer-type prices (PriceList, PriceListItem). Levels are no longer computed here: under change request 04 they come from qualified purchases and are configured data (SRV-45); the general earning rate here becomes the default rule of SRV-44. Out of scope: loyalty pages (DSH-21, WEB-20, mobile) and the full programme of SRV-44 to SRV-50.
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Ledger services with balance invariants and admin.loyalty.adjust (ADJUST with reason) | Anis |
| 2 | Earning rules (points per amount, earn on DELIVERED or on invoice PAID by setting) and bonuses | Anis |
| 3 | Expiry job (FIFO expiry after the configured period) and REVERSAL on order cancellation and return reception | Anis |
| 4 | Account level field read from SRV-45, with a Standard default until it lands | Anis |
| 5 | Rewards catalogue (RewardType) with admin.rewards.crud, redemptions and admin.redemptions fulfilment | Anis |
| 6 | Vouchers generated by redemption and applied by the cart engine at checkout | Anis |
| 7 | PriceList / PriceListItem agreements and level-based adjustments in the price resolver (customer-type price → agreement → level → promotions) | Anis |
| 8 | Reseller endpoints loyalty.summary, transactions, rewards, redeem, redemptions | Anis |
Deliverables
- apps/server/src/modules/loyalty/{ledger,earning,rewards,vouchers}.service.ts, jobs.ts, router.ts
- apps/server/src/modules/pricing/agreements.ts
- Prisma migration adding the V2 loyalty and price-agreement models
Acceptance criteria
- The balance always equals the sum of transactions; a cancelled order's points are reversed (LOY-02, LOY-05)
- Points expire per the configured period and appear as EXPIRE transactions (LOY-02)
- Spending points never changes the qualified purchases that drive levels (LOY-03, SRV-45)
- A voucher from a redemption reduces the cart total once and cannot be reused (LOY-04)
- A reseller with a price agreement gets the agreed price instead of their customer-type price, and promotions apply on top (PRC-03)
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| LOY-01 | Points earned per order line, credited after delivery or payment (setting), bonuses | V2 |
| LOY-02 | Points expiry, adjustments, reversal and regularisation on cancellation or return | V2 |
| LOY-03 | Configurable levels: Standard at sign-up, then levels from qualified purchases over a configurable period | V2 |
| LOY-04 | Rewards catalogue (voucher, free delivery, discount, gift, early access, commercial advantage) and redemption | V2 |
| LOY-05 | Traceable points history for the reseller and the back-office | V2 |
| PRC-03 | Per-reseller price agreements and level-based prices on top of the three customer-type prices | V2 |
API surface
| Endpoint group | Operations |
|---|---|
| Loyalty (V2) | 23 |
| Promotions & loyalty | 41 |
Test measures
- DB tests for ledger invariants under concurrent earn/redeem
- Job tests for expiry with a fake clock
- Unit tests for the extended price resolution order
Risks
- Earning rates not validated by HOCO — all values are data and the ledger is replayable
KPI
- Delivered by Thu 28 Jan 2027 within 3 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.