HOCO B2B
Team tasksAnis

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.

FieldDetails
Task codeSRV-30
PhaseP4 — V2 evolutions
Product scopeV2
StatusPlanned
StartMon 25 Jan 2027
DueThu 28 Jan 2027
ResponsibleAnis — Full-stack developer
Co-responsible—
Effort3 person-day(s) planned · 8 from scratch · size M
Area · appServer · server
Depends onSRV-29
UnblocksSRV-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

#SubtaskOwner
1Ledger services with balance invariants and admin.loyalty.adjust (ADJUST with reason)Anis
2Earning rules (points per amount, earn on DELIVERED or on invoice PAID by setting) and bonusesAnis
3Expiry job (FIFO expiry after the configured period) and REVERSAL on order cancellation and return receptionAnis
4Account level field read from SRV-45, with a Standard default until it landsAnis
5Rewards catalogue (RewardType) with admin.rewards.crud, redemptions and admin.redemptions fulfilmentAnis
6Vouchers generated by redemption and applied by the cart engine at checkoutAnis
7PriceList / PriceListItem agreements and level-based adjustments in the price resolver (customer-type price → agreement → level → promotions)Anis
8Reseller endpoints loyalty.summary, transactions, rewards, redeem, redemptionsAnis

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

RequirementTitleRelease
LOY-01Points earned per order line, credited after delivery or payment (setting), bonusesV2
LOY-02Points expiry, adjustments, reversal and regularisation on cancellation or returnV2
LOY-03Configurable levels: Standard at sign-up, then levels from qualified purchases over a configurable periodV2
LOY-04Rewards catalogue (voucher, free delivery, discount, gift, early access, commercial advantage) and redemptionV2
LOY-05Traceable points history for the reseller and the back-officeV2
PRC-03Per-reseller price agreements and level-based prices on top of the three customer-type pricesV2

API surface

Endpoint groupOperations
Loyalty (V2)23
Promotions & loyalty41

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.

On this page