Loyalty programme

This area covers the V2 loyalty programme (cahier §4.4 « Les points de fidélité sont crédités après livraison ou paiement selon le paramétrage », §4.6, §5.5, §12 scenario Fidélité, §14.2). It is not part of V1; its design is prepared in DES-30 and built after generalisation. Apps: reseller app and web, back-office, API. Server module: loyalty (V2). Policy values are open in D-05 and the V1/V2 split in D-16; settings loyalty.* are in the settings catalogue.

ID	Requirement	Release	Priority	Source	Apps
LOY-01	Points earned per order, credited after delivery or payment (setting), bonuses	V2	SHOULD	§4.4, §4.6, §14.2	API
LOY-02	Points expiry, adjustments and reversal on cancellation or refund	V2	SHOULD	§4.6	API · BO
LOY-03	Levels Bronze, Silver, Gold, VIP over a period with client-validated thresholds	V2	SHOULD	§4.6	API · BO · RA · RW
LOY-04	Rewards catalogue (voucher, free delivery, discount, gift, early access) and redemption	V2	SHOULD	§4.6, §5.5	API · BO · RA · RW
LOY-05	Traceable points history for the reseller and the back-office	V2	SHOULD	§5.5, §12	API · BO · RA · RW
LOY-06	Missions and challenges: commercial, interaction, weekly and monthly challenges, surprise and personalised missions	V2	SHOULD	Client doc 03 (18 Oct 2026)	API · BO · RA · RW
LOY-07	Top 3 resellers of the month: ranking, vouchers, badges and home highlight	V2	COULD	Client doc 03 (18 Oct 2026)	API · BO · RA · RW

LOY-01 — Points earned per orderCopy Anchor Link

Statement — The system should credit loyalty points per order once the order is delivered or paid (setting), plus configured bonuses.

Rules

1. Points = floor(eligible amount ÷ loyalty.pointsPerAmount) — default 1 point per 10 000 centimes (100 DA); eligible amount = order total TTC after discounts, excluding delivery fees and excluded brands or categories.
2. Trigger loyalty.earnOn: DELIVERED (default) or PAID (invoice fully paid). Until then the points show as en attente.
3. Bonuses (BONUS): first order, campaigns (e.g. ×2 on a brand for a period), configured in BO-53; never on replacement orders created by after-sales.
4. One EARN transaction per order, idempotent on the order id.

Acceptance criteria

• A delivered order of 125 000,00 DA (delivery fee excluded) credits 1 250 points; replaying the event credits nothing more.

Data — LoyaltyAccount, LoyaltyTransaction, Order, Setting.

Interfaces

• Screens: RA-38 Loyalty · BO-53 Loyalty settings & levels
• Endpoints: admin.loyalty.settings

LOY-02 — Expiry, adjustments and reversalsCopy Anchor Link

Statement — Points should expire after a configured period, be adjustable with a reason, and be reversed when the order is cancelled, returned or credited.

Rules

1. Expiry: points expire loyalty.pointsValidityMonths (12) after the end of the month they were earned; a monthly job (1st, 03:00) writes EXPIRE transactions; redemptions consume the oldest points first; a notification 30 days before expiry of 500 points or more.
2. Adjustments (ADJUST) by loyalty.update holders with a mandatory reason, audited.
3. Reversal (REVERSAL): cancellation after credit, return reception or credit note removes the points earned on the affected amount (pro rata). If points were already spent the balance may go negative; redemptions are then blocked until it is positive again (§4.6 « Les points annulés ou remboursés doivent être régularisés »).

Acceptance criteria

• Returning half of an order that earned 1 250 points writes a reversal of 625 points.
• An adjustment without reason → 400 VALIDATION_FAILED.

Data — LoyaltyTransaction, LoyaltyAccount, ReturnRequest, CreditNote, AuditLog.

Interfaces

• Screens: BO-53 Loyalty settings & levels
• Endpoints: admin.loyalty.adjust

LOY-03 — Levels Bronze, Silver, Gold, VIPCopy Anchor Link

Statement — The system should compute each reseller's level (LoyaltyLevel) from points earned over a rolling period with thresholds validated by HOCO.

Rules

1. Level = highest level whose threshold ≤ points earned (EARN + BONUS − REVERSAL) over the last loyalty.levelPeriodMonths (12). Placeholder thresholds for the design only: Silver 5 000, Gold 15 000, VIP 40 000 (loyalty.levelThresholds, to validate).
2. Upgrades apply at once; downgrades are evaluated on the 1st of each month, one level at a time.
3. The reseller sees level, progress and points missing (« Plus que 2 550 pts pour atteindre le niveau Gold », reference screen 6); levels can target promotions (PRM-02).

Acceptance criteria

• A reseller at 12 450 points with Gold at 15 000 sees Silver and 2 550 points missing; earning 2 550 points upgrades them at once.

Data — LoyaltyAccount, LoyaltyTransaction, Setting.

Interfaces

• Screens: RA-38 Loyalty · BO-53 Loyalty settings & levels · RW-15 Loyalty, rewards & packs
• Endpoints: loyalty.summary · admin.loyalty.settings

LOY-04 — Rewards catalogue and redemptionCopy Anchor Link

Statement — Resellers should exchange points for rewards: voucher, free delivery, discount, gift or early access.

Rules

1. A Reward has a RewardType, points cost, quantity available, minimum level, validity window and active flag.
2. Redemption checks, in order: account active; reward active, in its window and in stock (409 REWARD_UNAVAILABLE — §5.5 « Les récompenses indisponibles ne doivent pas pouvoir être réclamées »); level (409 REWARD_LEVEL_REQUIRED); balance ≥ cost (409 LOYALTY_INSUFFICIENT_POINTS). It then writes a REDEEM transaction and a RewardRedemption atomically (idempotent).
3. VOUCHER, FREE_DELIVERY, DISCOUNT create a single-use Voucher (valid 90 days) applied at checkout; GIFT is fulfilled by the back-office with the next order; EARLY_ACCESS grants visibility of new products.
4. A redemption cancelled before use restores the points (REVERSAL).

Acceptance criteria

• Redeeming a 6 000-point reward with 12 450 points leaves 6 450 and a voucher; redeeming an out-of-stock reward → 409 REWARD_UNAVAILABLE.

Data — Reward, RewardRedemption, Voucher, LoyaltyTransaction.

Interfaces

• Screens: RA-39 Rewards & redemption · BO-54 Rewards & redemptions · RW-15 Loyalty, rewards & packs
• Endpoints: loyalty.rewards · loyalty.redeem · loyalty.redemptions · admin.rewards.crud · admin.redemptions.list

LOY-05 — Traceable points historyCopy Anchor Link

Statement — Every points movement should be visible, with its reason, to the reseller and the back-office.

Rules

1. The ledger is append-only: type (LoyaltyTransactionType), points (signed), balance after, label, related order, reward or user, time. Balance = sum of the ledger; a nightly check compares it with the stored balance.
2. The reseller sees their own history with filters; the back-office sees any reseller's with the actor of manual entries, and can export it.

Acceptance criteria

• For a reseller, the sum of the history equals the displayed balance; an adjustment shows its author and reason in the back-office only.

Data — LoyaltyTransaction, LoyaltyAccount.

Interfaces

• Screens: RA-38 Loyalty · BO-54 Rewards & redemptions
• Endpoints: loyalty.transactions

LOY-06 — Missions and challengesCopy Anchor Link

Statement — The loyalty programme should offer missions and challenges that earn bonus points (HOCO's document 03, SN-07, SN-08, SN-22, SN-24; smart notifications).

Rules

1. Mission kinds: commerciales (first order of the month +200 points, 5 orders in the month +500, purchases above 5 000 000 DA in the month +700, a product bought for the first time, purchases from 3 different categories), interaction (rate the last order +50, enable notifications), challenges (3 orders in 7 days, the monthly objective, Flash Challenge: buy the chosen product today), surprise (one random mission a week, unknown in advance) and personnalisées (built from the reseller's category history).
2. Each mission has a condition evaluated by the server on orders and events, a period, a reward in points (BONUS transaction) and a status (assigned, completed, expired); completing it notifies SN-08.
3. Academy missions (videos, quiz), product reviews and the Daily / Weekly / Monthly cadence are later (D-40, D-42).

Acceptance criteria

• A reseller with the mission « 5 commandes ce mois-ci » who has their fifth order delivered in the month gets 500 points once.

Data — V2 mission model (to design with SRV-29), LoyaltyTransaction.

LOY-07 — Top 3 resellers of the monthCopy Anchor Link

Statement — The system could rank resellers each month and reward the top three (SN-27).

Rules

1. Score over the calendar month from purchase volume (delivered orders TTC), number of orders and activity in the app; weights, eligibility and ties are D-42.
2. Prizes proposed by HOCO: 1st — voucher 20 000 DA, badge « Meilleur Revendeur », shown on the home page for a month; 2nd — 10 000 DA, « Top Revendeur »; 3rd — 5 000 DA, « Top 3 Revendeur ». Vouchers are Voucher rewards.
3. The back-office reviews the ranking before publication (fraud, returns, unpaid invoices).

Acceptance criteria

• On the 1st of the month the reviewed ranking is published, the three winners receive their voucher and badge, and the first appears on every reseller's home for the month.

Data — V2 Voucher, Reward, RewardRedemption, ranking snapshot.