HOCO B2B
SRSRequirements

Loyalty programme

Requirements LOY-01 to LOY-26 (V2): points and earning rules, campaigns and stacking, configurable levels from qualified purchases, cashback, rewards, missions, the monthly ranking, referral, badges, gift chest and wheel, full history, back-office administration and mandatory tests.

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 D-45 to D-63, and the V1/V2 split in D-16 and D-57; settings loyalty.* are in the settings catalogue.

Change request 04: not yet accepted or priced by HOCO

LOY-08 to LOY-26 and the changes to LOY-01 to LOY-07 come from HOCO's loyalty document and its letter of 6 November 2026 (scope). They are specified as V2, in phase P4. Every number below is an example from the document until HOCO confirms it in the decision register. Rules are in BR-87 to BR-106.

IDRequirementReleasePrioritySourceApps
LOY-01Points earned per order line, credited after delivery or payment (setting), bonusesV2SHOULD§4.4, §4.6, §14.2; Client loyalty document + letter of 6 Nov 2026API
LOY-02Points expiry, adjustments, reversal and regularisation on cancellation or returnV2SHOULD§4.6; Client loyalty document + letter of 6 Nov 2026API · BO
LOY-03Configurable levels: Standard at sign-up, then levels from qualified purchases over a configurable periodV2SHOULD§4.6; Client loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-04Rewards catalogue (voucher, free delivery, discount, gift, early access, commercial advantage) and redemptionV2SHOULD§4.6, §5.5; Client loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-05Traceable points history for the reseller and the back-officeV2SHOULD§5.5, §12API · BO · RA · RW
LOY-06Missions and challenges: daily, weekly, monthly, seasonal; commercial, interaction, surprise and personalisedV2SHOULDClient doc 03 (18 Oct 2026); Client loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-07Monthly ranking: configurable criterion and Top N, reviewed results, prizes and home highlightV2COULDClient doc 03 (18 Oct 2026); Client loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-08Earning rules: barème by product, category, brand, quantity or amount, set in the back-officeV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-09Order-value bonuses and bonuses on selected productsV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-10Occasion campaigns and Happy Days with Algiers time windowsV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-11Campaign stacking and the calculation orderV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO
LOY-12First-order bonus and bonus on accepted reviewsV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-13New-product campaign for the first N buyersV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-14Cashback balance, earning and use at checkoutV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-15Referral of new resellers with fraud controlsV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-16Birthday bonus on a verified dateV2COULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-17Badges: conditions, display, permanent or temporaryV2COULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-18Gift chest with configured prizes, odds and budgetV2COULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-19Wheel of fortune, optional, one spin per entitlementV2COULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-20Level upkeep and drop with noticeV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-21Personal objective: progress to the next level on the homeV2SHOULDClient loyalty document + letter of 6 Nov 2026API · RA · RW
LOY-22Full history: separate ledgers, one combined viewV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW
LOY-23Back-office administration: every rule without a developer, reseller view, manual adjustmentsV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO
LOY-24Programme dashboardV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO
LOY-25Rule versioning: new operations only, or recalculationV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO
LOY-26Mandatory tests before the programme is deliveredV2SHOULDClient loyalty document + letter of 6 Nov 2026API · BO · RA · RW

LOY-01 — Points earned per order

ReleasePrioritySourceAppsOwner tasks
V2SHOULDcahier §4.4, §4.6, §14.2; Client loyalty document + letter of 6 Nov 2026APISRV-30, SRV-44, DSH-21, MRA-20

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

Rules

  1. Base points come line by line from the barème of LOY-08. The general rule defaults to loyalty.pointsPerAmount, 1 point per 10 000 centimes (100 DA). The eligible amount (BR-88) is HT, after promotions, without delivery fees, excluded brands, categories or products.
  2. Trigger loyalty.earnOn: DELIVERED (default) or PAID (invoice fully paid), chosen by HOCO. Until then the points show as en attente; pressing « Commander » gives no final points, and a cancelled, refused or incomplete order gives none (document §2.2).
  3. Bonuses (BONUS): LOY-09, LOY-10, LOY-12 and LOY-13, configured in BO-72 and BO-74; never on replacement orders created by after-sales.
  4. One EARN transaction per order, idempotent on the order id.

Acceptance criteria

  • A delivered order with an eligible amount of 125 000,00 DA HT credits 1 250 points under the default rule; replaying the event credits nothing more.

Data — LoyaltyAccount, LoyaltyTransaction, Order, Setting.

Interfaces

LOY-02 — Expiry, adjustments and reversals

ReleasePrioritySourceAppsOwner tasks
V2SHOULDcahier §4.6; Client loyalty document + letter of 6 Nov 2026API · BOSRV-30, SRV-44

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; the daily job loyalty.expirePoints (01:30) writes EXPIRE transactions; redemptions consume the oldest points first; a notification goes out loyalty.expiryNoticeDays (30) before the expiry of loyalty.expiryNoticeMinPoints (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 attached to the affected lines (LoyaltyCalculation), not a share of the order. A full return removes all the points of the order; a change to an order recalculates on the final products and amounts. Bonuses tied to a threshold are checked again (BR-94).
  4. If the points were already spent, loyalty.regularisationMode applies. The default is ALLOW_NEGATIVE: the balance may go negative and redemptions are blocked until it is positive again (§4.6 « Les points annulés ou remboursés doivent être régularisés »). The operation is recorded and no earlier entry is erased (document §2.2).

Acceptance criteria

  • Returning products that earned 625 of an order's 1 250 points writes a reversal of 625 points.
  • An adjustment without reason → 422 REASON_REQUIRED.

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

Interfaces

LOY-03 — Configurable levels from qualified purchases

ReleasePrioritySourceAppsOwner tasks
V2SHOULDcahier §4.6; Client loyalty document + letter of 6 Nov 2026API · BO · RA · RWSRV-45, SRV-30, DSH-22, DSH-21, WEB-21, WEB-20, MRA-21, MRA-20, DES-31, DES-30

Statement — Every reseller should start at Standard at sign-up and move up through levels configured by HOCO, from their qualified purchases over a configurable period. Levels no longer come from points.

Rules

  1. Levels are configured data (LoyaltyLevelDefinition), not a fixed enum: HOCO can create, rename, reorder, enable or disable them (Bronze, Silver, Gold, VIP, Diamond or others) with no developer. Standard is the entry level and always exists. Whether Diamond replaces VIP or is added is D-58.
  2. A level is reached when the condition is met: qualified amount, optionally with a minimum number of qualified orders, both required (AND rule). Example: 500 000 DA and 10 orders.
  3. The period is configurable (loyalty.levelPeriodMode): since sign-up, the last 12 months, or another number of months.
  4. Qualified purchases are a separate balance (QualifiedPurchaseEntry, BR-88). Spending points never reduces them. Returns and cancellations do.
  5. Example thresholds to confirm in D-49: Standard from sign-up; Bronze from 100 000 DA; Silver from 500 000 DA; Gold from 1 500 000 DA; VIP from 5 000 000 DA.
  6. Each level carries its benefits: a points bonus (examples +10 %, +20 %, +30 %, D-51), exclusive offers (PRM-08), priority on new products, and for the top levels preferential prices through PRC-03 if HOCO sets them.
  7. An upgrade applies at once after a qualified order: level changed, benefits active, loyalty.level_reached sent, LoyaltyLevelChange written. Upkeep and drops are LOY-20.
  8. The reseller sees level, progress and what is missing (LOY-21). Levels can target promotions (PRM-02).
  9. The V1 enum LoyaltyLevel on PromotionAudience and in segment criteria is replaced by LoyaltyLevelDefinition (SRV-45).

Acceptance criteria

  • A new reseller is Standard. With 72 500,00 DA qualified and Bronze at 100 000,00 DA they see 27 500,00 DA missing; the order that reaches the threshold upgrades them at once.
  • A reseller who spends 5 000 points keeps the same qualified purchases and level.
  • With a Silver condition of 500 000 DA and 10 orders, a reseller at 600 000 DA with 8 orders stays Bronze.

Data — LoyaltyAccount, LoyaltyLevelDefinition, LoyaltyLevelChange, QualifiedPurchaseEntry.

Interfaces

LOY-04 — Rewards catalogue and redemption

ReleasePrioritySourceAppsOwner tasks
V2SHOULDcahier §4.6, §5.5; Client loyalty document + letter of 6 Nov 2026API · BO · RA · RWSRV-30, DSH-21, WEB-20, MRA-20, DES-30, SRV-29

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

Rules

  1. A Reward has a RewardType, image, name, points cost, conditions, delivery method, stock kept in the back-office, minimum level, validity window and active flag. Resellers see availability only, « Disponible » or « Indisponible », never the stock number (BR-99; the document's « Stock disponible » is read this way).
  2. Redemption checks, in order: account active; reward active, in its window and in stock (422 REWARD_UNAVAILABLE — §5.5 « Les récompenses indisponibles ne doivent pas pouvoir être réclamées »); level (422 LOYALTY_LEVEL_TOO_LOW); limit per reseller (422 REWARD_LIMIT_REACHED); balance ≥ cost and not negative (422 INSUFFICIENT_POINTS). It then writes a REDEEM transaction and a RewardRedemption atomically (idempotent).
  3. VOUCHER, FREE_DELIVERY, DISCOUNT create a single-use Voucher (default validity 90 days) applied at checkout; GIFT is fulfilled by the back-office with the next order; EARLY_ACCESS grants visibility of new products; COMMERCIAL_ADVANTAGE is a free-text benefit fulfilled by the back-office.
  4. Example voucher barème, 1 point = 1 DA, to confirm in D-46: 500 points = 500 DA; 1 000 points = 1 000 DA; 2 000 points = 2 000 DA. Example gifts, to confirm in D-47: cable 500 points; HOCO charger 1 000; phone holder 2 000; earphones 3 000; power bank 5 000; smart watch 10 000.
  5. Each voucher states whether it covers all or part of an order, the minimum order, stacking with other discounts or cashback, expiry, and whether several can be used on one order (D-46). The default is one voucher per order.
  6. A redemption cancelled before use restores the points (REVERSAL).
  7. A reseller may keep their points for a bigger reward. The app shows balance, usable points, points close to expiry, rewards available now and what is missing for a chosen reward.

Acceptance criteria

  • Redeeming a 1 000-point reward with 2 500 points leaves 1 500 and a voucher; redeeming an out-of-stock reward → 422 REWARD_UNAVAILABLE.
  • The API never returns the stock number of a reward to a reseller.

Data — Reward, RewardRedemption, Voucher, LoyaltyTransaction.

Interfaces

LOY-05 — Traceable points history

ReleasePrioritySourceAppsOwner tasks
V2SHOULDcahier §5.5, §12API · BO · RA · RWSRV-30, MRA-20

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; the nightly job loyalty.reconcileLedgers compares it with the stored balance. LOY-22 extends this to cashback and rewards.
  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

LOY-06 — Missions and challenges

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient doc 03 (18 Oct 2026); Client loyalty document + letter of 6 Nov 2026API · BO · RA · RWSRV-47, DSH-23, WEB-21, MRA-21, DES-31

Statement — The loyalty programme should offer missions and challenges, daily, weekly, monthly or seasonal, that earn a reward (document 03, SN-07, SN-08, SN-22, SN-24; smart notifications; loyalty document §6).

Rules

  1. A Mission has a name, description, cadence (MissionCadence: DAILY, WEEKLY, MONTHLY, SEASONAL, ONE_OFF), period, condition (MissionCondition), reward (points or a prize), progress and status (MissionStatus). It can target levels, customer types or a segment.
  2. Example conditions from the loyalty document: 3 qualified orders in the month for 500 points (progress 2/3); products from 5 categories for 1 000 points; 300 000 DA of qualified purchases in the month for 1 500 points; 20 units of a model for points or a gift.
  3. Document 03's kinds stay as default examples: 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), surprise (one random mission a week) and personnalisées (built from the reseller's category history).
  4. Conditions are evaluated by the server on qualified orders and events; progress updates after each one. The reward is paid once, on a key (mission, reseller, period); a repeated event pays nothing (BR-93).
  5. Completing a mission notifies SN-08. A mission reward is cancelled if the order that completed it is cancelled or returned and the condition is no longer met (BR-94).
  6. The loyalty document brings the cadence and the review reward into V2 (LOY-12), which supersedes the later placement of D-42. Academy missions (videos, quiz) stay later (D-40).

Not built yet. Surprise weekly missions: the back-office has no way to create them, and they are not in the phase that built missions. Personalised missions are built.

Acceptance criteria

  • A reseller with the mission « 3 commandes ce mois-ci » sees 2/3 and, when the third order qualifies, gets 500 points once.
  • A mission with a period ended stops counting and shows Expirée.

Data — Mission, MissionProgress, LoyaltyTransaction.

Interfaces

LOY-07 — Monthly ranking: configurable Top N

ReleasePrioritySourceAppsOwner tasks
V2COULDClient doc 03 (18 Oct 2026); Client loyalty document + letter of 6 Nov 2026API · BO · RA · RWSRV-47, DSH-23, WEB-21, MRA-21, DES-31

Statement — The system could rank resellers each month on a criterion chosen by HOCO and reward a configurable Top N. The loyalty document's Top 10 supersedes the Top 3; document 03's content stays as the default example.

Rules

  1. A Challenge sets the period, the criterion (ChallengeCriterion: PURCHASE_AMOUNT, ORDER_COUNT, PRODUCT_QUANTITY, PURCHASE_GROWTH, WEIGHTED_SCORE), topN (document: 10) and the prizes per rank.
  2. WEIGHTED_SCORE is document 03's score: purchase volume, number of orders and activity in the app, weights and ties in D-42.
  3. Default prizes, document 03's example: 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 ». The loyalty document's example: 1st a voucher or a large gift, 2nd a power bank, 3rd a smart watch, 4th to 10th points or gifts. Final prizes are set in the back-office (D-54).
  4. During the month the ranking is refreshed and shows its criterion. Cancelled and non-qualified orders are left out, and an order counts once.
  5. At the end of the month the challenge closes, results are frozen, a loyalty.validate holder reviews them (fraud, returns, unpaid invoices), then publishes. Prizes and winners are recorded in ChallengeResult.
  6. The ranking shows rank and store name only. It never shows another reseller's amounts or order counts, since commercial data stays private (D-54).

Acceptance criteria

  • With topN = 10, on publication the ten winners receive their prizes and the first appears on every reseller's home for the month.
  • A cancelled order leaves the ranking at the next refresh, and a reseller sees no other reseller's figures.

Data — Challenge, ChallengeResult, Voucher, Badge.

Interfaces

Full programme (change request 04)

Source: HOCO's loyalty document, updated by the letter of 6 November 2026. Status: change request 04, not yet accepted or priced by HOCO. See scope.

LOY-08 — Earning rules and barème

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§2.1; letter §1.3)API · BO · RA · RWSRV-44, DSH-22, WEB-21, MRA-21, DES-31

Statement — Each eligible order line should earn points from a barème that HOCO configures by product, category, brand, quantity or amount, with no developer involved.

Rules

  1. A rule of kind EARNING has a scope (EarningRuleScope: ALL, CATEGORY, BRAND, PRODUCT), a basis (EarningBasis: AMOUNT points per amount, QUANTITY points per unit), a value, optional dates, and the customer types and levels it applies to.
  2. Points are computed line by line on the products really in the order, not on the order total (document §2.1). The most specific active rule wins: PRODUCT, then BRAND, then CATEGORY (the deepest category), then ALL (BR-90). Brand before category is an assumption to confirm in D-45.
  3. Example values from the document, to confirm in D-45: general rule 10 points per 1 000 DA; chargers 1 point per 100 DA; TWS 2 points per 100 DA.
  4. The amount is the line's eligible amount (BR-88): HT, after promotions, without delivery fees. Excluded brands, categories and products earn nothing.
  5. Before the order reaches the earning status the points are an estimate shown as en attente; the final calculation runs on the final products and amounts (BR-89).

Acceptance criteria

  • An order with 10 000,00 DA of chargers (1 point per 100 DA) and 10 000,00 DA of TWS (2 points per 100 DA) earns 100 + 200 = 300 points before any bonus.
  • A back-office user creates a brand rule, activates it, and the next delivered order uses it without a release.

Data — LoyaltyRule, LoyaltyRuleVersion, LoyaltyCalculation, LoyaltyTransaction.

Interfaces

LOY-09 — Order-value and selected-product bonuses

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§2.3, §2.5)API · BO · RA · RWSRV-44, DSH-22, WEB-21, MRA-21

Statement — HOCO should be able to add points when an order reaches a value tier and when selected products are bought.

Rules

  1. ORDER_VALUE_BONUS rule: tiers of eligible amount with a fixed bonus. Example tiers, to confirm in D-45: from 100 000 DA +500, from 300 000 DA +1 500, from 500 000 DA +3 000. Only the highest tier reached applies, once per order, unless the rule says otherwise.
  2. PRODUCT_BONUS rule: a product, a group of products or a launch period, with a fixed bonus or a multiplier, start and end dates and an optional cap per reseller and overall (document examples: HOCO X126 +200 points; double points on a new model).
  3. Whether a bonus stacks with another is set on the rule (LOY-11).
  4. After a partial return the tier is evaluated again on the amount kept (BR-94).

Acceptance criteria

  • An order of 320 000,00 DA eligible earns its base points plus 1 500 points, once, written as a separate BONUS entry.
  • A selected-product bonus stops at its end date or when its cap is reached.

Data — LoyaltyRule, LoyaltyCalculation, LoyaltyTransaction.

Interfaces

LOY-10 — Occasion campaigns and Happy Days

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§2.6, §10)API · BO · RA · RWSRV-44, DSH-22, WEB-21, MRA-21, DES-31

Statement — HOCO should be able to run time-boxed points campaigns: occasions such as Ramadan, and Happy Days such as double points on Fridays.

Rules

  1. LoyaltyCampaign of kind OCCASION or HAPPY_DAYS: name, start and end (or recurring days and hours), products or categories, eligible levels, multiplier or fixed bonus, condition, stacking mode.
  2. Examples from the document: Ramadan ×2; ×3 for 15 days on chosen products; +500 points on a condition; Friday ×2; weekend ×3; 24 hours on chosen products. All are examples, none is a default.
  3. Time windows are computed in Africa/Algiers. The order's reference time is Order.submittedAt, so an order submitted inside the window keeps the campaign even if it is delivered later. Assumption to confirm in D-53.
  4. The job loyalty.applyCampaignSchedule opens and closes campaigns; no campaign applies outside its window.
  5. The reseller sees active campaigns, their end time and the products concerned (RA-44); loyalty.double_points_started announces a ×2 or more campaign (SN-05).

Acceptance criteria

  • A Happy Day ending at 23:59 Algiers time gives no multiplier to an order submitted at 00:01.
  • A campaign limited to Gold gives nothing to a Silver reseller.

Data — LoyaltyCampaign, LoyaltyCalculation, LoyaltyTransaction.

Interfaces

LOY-11 — Stacking and calculation order

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§2.3, §2.6, §4.3)API · BOSRV-44, DSH-22

Statement — When several rules apply to the same line, the result should follow a stacking mode and a calculation order that HOCO sets, and it should be traceable.

Rules

  1. Stacking mode per campaign (CampaignStackingMode): STACK (allowed with the others), BEST_ONLY (the strongest wins), PRIORITY (the lowest priority number wins, ties broken by the highest result).
  2. Calculation order, the default of BR-91: base points per line → campaign multiplier → level bonus → fixed bonuses. The document gives this only as a proposal, so HOCO confirms it in D-53.
  3. Each calculation stores its steps and rule versions in LoyaltyCalculation, so the back-office can explain any number.

Acceptance criteria

  • 100 base points, ×2 campaign, Bronze +10 %: 100 × 2 = 200, then 200 + 10 % = 220 points.
  • Two campaigns in BEST_ONLY on one product, ×2 and ×3: the line earns ×3 only.

Data — LoyaltyCampaign, LoyaltyCalculation, Setting.

Interfaces

LOY-12 — First-order and review bonuses

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§2.4, §2.7)API · BO · RA · RWSRV-48, DSH-23, WEB-21, MRA-21, DES-31

Statement — A new reseller should earn a bonus on their first qualified order, and HOCO should be able to reward genuine, accepted reviews.

Rules

  1. FIRST_ORDER_BONUS (example +500 points): once per eligible account, on the first order reaching the earning status. Cancelled orders do not count. The entitlement key is the reseller, and the phone uniqueness of CRM-03 plus a check on Reseller duplicates blocks a second bonus through another account.
  2. REVIEW_BONUS (example +100 points): paid only when the review is accepted (ReviewStatus ACCEPTED) by a loyalty.validate holder, for a delivered order of the same account, once per order and product unless the rule allows otherwise.
  3. Reviews are private to HOCO by default: nothing is published to other resellers. Publication is D-63. The PRD exclusion of social features stays.
  4. Fake or duplicate reviews are refused with a reason and earn nothing.

Acceptance criteria

  • A first order cancelled before delivery earns nothing; the next delivered order earns the bonus once.
  • A review refused in BO-81 writes no ledger entry; an accepted one writes one BONUS entry, and a second acceptance on the same order and product writes none.

Data — LoyaltyRule, ProductReview, LoyaltyTransaction.

Interfaces

LOY-13 — New-product campaign for the first N buyers

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§9)API · BO · RA · RWSRV-44, SRV-48, DSH-22, WEB-21, MRA-21

Statement — When a collection or a model arrives, HOCO should be able to reward the first N resellers who buy it during a launch window.

Rules

  1. LoyaltyCampaign of kind NEW_PRODUCT: products, maxBeneficiaries (example 50), multiplier (example ×2), period (example 15 days).
  2. A reseller takes a place when their order is confirmed (VALIDATED, ORD-14); the place is final once the order reaches the earning status, and it is freed if the order is cancelled or refused. Taking the place at confirmation is an assumption to confirm in D-53.
  3. LoyaltyCampaignBeneficiary records the rank and date, unique on (campaign, reseller), so one reseller counts once.
  4. The campaign ends automatically at its end date or when the last place is taken.
  5. Resellers see « Places disponibles » or « Complet », never the number of places left, in line with STK-07 and BR-99.

Acceptance criteria

  • With 50 places, the 51st distinct reseller gets no multiplier and the campaign shows « Complet ».
  • Two orders from one reseller take one place.

Data — LoyaltyCampaign, LoyaltyCampaignBeneficiary.

Interfaces

LOY-14 — Cashback balance and use at checkout

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§5)API · BO · RA · RWSRV-46, DSH-22, DSH-24, WEB-21, MRA-21, DES-31

Statement — The reseller should hold a cashback balance, separate from points, earned on eligible orders and usable on later orders under HOCO's conditions.

Rules

  1. CASHBACK rule: rate on the eligible amount (example 2 %), validity, maximum use per order (example 20 % of the order), minimum order amount, excluded products, stacking with vouchers and discounts. All values are examples for D-48.
  2. Cashback has its own append-only ledger CashbackTransaction and its own balance (BR-87).
  3. Use at checkout: cart.checkout gains an optional cashbackAmount in V2. The server checks balance, cap, minimum, validity, exclusions and stacking, in that order, and answers 422 CASHBACK_NOT_APPLICABLE with the reason.
  4. No order is confirmed automatically (ORD-14): a USE entry holds the amount at SUBMITTED, and a RELEASE entry gives it back if the order is refused or cancelled.
  5. A cancelled or returned order removes the cashback it generated; if it was already spent, the regularisation rule applies (BR-94).
  6. Not to activate before D-60: how cashback appears on invoices and how VAT treats it needs an accountant's review. Until then loyalty.cashback.enabled stays false.

Acceptance criteria

  • An eligible order of 100 000,00 DA at 2 % adds 2 000,00 DA of cashback once it reaches the earning status.
  • With a 20 % cap, an order of 50 000,00 DA accepts at most 10 000,00 DA of cashback.
  • A refused order gives its held cashback back and the history shows both entries.

Data — LoyaltyAccount, CashbackTransaction, LoyaltyRule, Order.

Interfaces

LOY-15 — Referral (parrainage)

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§7)API · BO · RA · RWSRV-48, DSH-23, WEB-21, MRA-21, DES-31

Statement — A reseller should be able to bring a new reseller, and both should be rewarded once the new account is valid and has a first qualified order.

Rules

  1. Each loyalty account has a referral code; sign-up accepts an optional referralCode in V2 (loyalty.referral). It does not replace delegate attribution (BR-73).
  2. Example rewards, for D-54: sponsor +1 000 points, new reseller +500 points. Condition: account validated and first qualified order reached the earning status.
  3. Referral records sponsor, new reseller, sign-up date, first qualified order date and ReferralStatus (En attente, Validée, Refusée).
  4. Nothing is paid at sign-up. Unique on the new reseller, so one account is referred once; self-referral and a shared phone, address or store are flagged for review in BO-79.
  5. A first order later cancelled or fully returned reverses both rewards (BR-94).

Acceptance criteria

  • A referral stays En attente after sign-up and pays nothing until the first qualified order.
  • A second referral claim on the same new reseller is refused.

Data — Referral, LoyaltyAccount, LoyaltyTransaction.

Interfaces

LOY-16 — Birthday bonus

ReleasePrioritySourceAppsOwner tasks
V2COULDClient loyalty document + letter of 6 Nov 2026 (§8)API · BO · RA · RWSRV-48, DSH-23, WEB-21, MRA-21

Statement — HOCO could reward the owner's birthday or the shop's founding date when the date is verified.

Rules

  1. OccasionType: OWNER_BIRTHDAY, SHOP_FOUNDING, and ACCOUNT_ANNIVERSARY (document 03, SN-15, the account's validation date). HOCO chooses which are active in the BIRTHDAY rule (D-62).
  2. The reward is points, a coupon, free delivery or a chosen gift (examples: +500 points); the rule sets its validity and the limit of once a year.
  3. The system never invents a date. OWNER_BIRTHDAY and SHOP_FOUNDING pay only with status VERIFIED; a missing, declared or rejected date pays nothing. ACCOUNT_ANNIVERSARY is a system date and needs no proof.
  4. The owner's birth date is personal data: it follows SEC-08 and the retention table, only the day and month are shown outside BO-81, and resellers may leave it empty.

Acceptance criteria

  • A reseller with no verified date gets no bonus on any day.
  • A reseller with a verified date gets one bonus that year, even if the job runs twice.

Data — OccasionDate, LoyaltyRule, LoyaltyTransaction, Voucher.

Interfaces

LOY-17 — Badges

ReleasePrioritySourceAppsOwner tasks
V2COULDClient loyalty document + letter of 6 Nov 2026 (§12)API · BO · RA · RWSRV-47, DSH-23, WEB-21, MRA-21, DES-31

Statement — The system could award badges for achievements and show them on the reseller's account.

Rules

  1. A Badge has a name, an image, a condition, a display flag, BadgeValidity (PERMANENT, TEMPORARY with a number of days) and an optional benefit.
  2. Examples: Top Revendeur, Client fidèle (12 months of qualified activity), Meilleure croissance, Expert TWS, Premier achat, Parrain actif, Champion du mois. Document 03's Meilleur Revendeur and Top 3 Revendeur stay as ranking examples (LOY-07).
  3. ResellerBadge keeps the date earned and the end date. A temporary badge ends by date, it is never deleted.
  4. A badge is symbolic unless HOCO attaches a benefit.

Acceptance criteria

  • A reseller meeting the condition receives the badge once, and it appears on RA-47.
  • A temporary badge disappears from display at its end date and stays in the history.

Data — Badge, ResellerBadge.

Interfaces

LOY-18 — Gift chest (coffre cadeau)

ReleasePrioritySourceAppsOwner tasks
V2COULDClient loyalty document + letter of 6 Nov 2026 (§13)API · BO · RA · RWSRV-49, DSH-23, WEB-21, MRA-21, DES-31

Statement — After a configured condition, the reseller could receive a gift chest that opens once and gives one prize from a table HOCO controls.

Rules

  1. A PrizeTable of kind CHEST holds the opening condition, the entries (PrizeType: POINTS, COUPON, NEXT_ORDER_BONUS, PRODUCT, FREE_DELIVERY), the odds, the stock and budget of each entry, the number of chests allowed and their validity.
  2. A qualified event creates a PrizeEntitlement, unique on (table, source). The draw runs on the server at opening, inside a transaction, and only among entries with stock and budget left. The odds of a table add up to 100 %.
  3. A chest opens once; the result is stored in the entitlement and in the reward history.
  4. The chest cannot bypass reward conditions or hand out an unavailable prize (document §13). When no entry is left the entitlement is not created, or the fallback entry applies.
  5. The odds and rules are shown to the reseller before opening.
  6. Not to activate before D-61: purchase-linked random prizes need a legal check. Until then loyalty.chest.enabled stays false.

Acceptance criteria

  • Opening the same chest twice, even on two devices, gives one prize; the second call replays or fails with 409 ENTITLEMENT_USED.
  • A prize whose stock is exhausted is never drawn.

Data — PrizeTable, PrizeTableEntry, PrizeEntitlement, Voucher, LoyaltyTransaction.

Interfaces

LOY-19 — Wheel of fortune (roue de la chance)

ReleasePrioritySourceAppsOwner tasks
V2COULDClient loyalty document + letter of 6 Nov 2026 (§14)API · BO · RA · RWSRV-49, DSH-23, WEB-21, MRA-21, DES-31

Statement — As an optional feature, a qualified order over an amount set by HOCO could give one spin of a wheel with configured prizes and odds.

Rules

  1. A PrizeTable of kind WHEEL, same model and same draw rules as LOY-18. Prizes: points, coupon, a charger, free delivery, bonus points on the next order (document examples).
  2. One spin per qualified entitlement; an entitlement cannot be reused; a spin expires at its validity date; the wheel does not open without a valid entitlement.
  3. Every result is stored. Each prize has its conditions of use, shown with the result.
  4. The animation only displays the result the server already drew.
  5. Not to activate before D-61, for the same reason as the chest. loyalty.wheel.enabled stays false by default.

Acceptance criteria

  • A reseller without an entitlement sees no wheel, and the call answers 409 ENTITLEMENT_NOT_AVAILABLE.
  • A used spin cannot be replayed; the same Idempotency-Key returns the same result.

Data — PrizeTable, PrizeTableEntry, PrizeEntitlement.

Interfaces

LOY-20 — Level upkeep and drop

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§4.5)API · BO · RA · RWSRV-45, DSH-22, WEB-21, MRA-21

Statement — HOCO should choose whether a level is kept for good or must be maintained by yearly activity, with a stated notice before any drop.

Rules

  1. Per level (LevelRetentionMode): PERMANENT, or ACTIVITY_REQUIRED with an evaluation period, upkeep conditions, drop conditions, a notice period and an application date.
  2. loyalty.recomputeLevels evaluates upkeep. A drop goes down one level at a time and always follows loyalty.level_drop_warning, sent at the start of the notice period. Example from the document: a Gold reseller whose activity falls over 12 months moves to Silver.
  3. Each change writes a LoyaltyLevelChange with reason, old and new level, and rule version. Changes are never silent.
  4. A level changed by hand follows BR-105.

Acceptance criteria

  • A Gold reseller below the upkeep condition is warned first, and only moves to Silver on the announced date.
  • Reaching the condition again during the notice cancels the drop.

Data — LoyaltyLevelDefinition, LoyaltyLevelChange, QualifiedPurchaseEntry.

Interfaces

LOY-21 — Personal objective

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§4.4, §15)API · RA · RWSRV-45, WEB-21, MRA-21, DES-31

Statement — The reseller's home should show their level, qualified purchases, what is missing for the next level and what they gain there.

Rules

  1. loyalty.objective returns current level, qualified amount, qualified order count, each remaining condition, progress and the next level's benefits.
  2. When the next level also needs a minimum order count, both conditions appear. Example: « Il vous reste 27 500 DA et une commande qualifiée pour atteindre Bronze. »
  3. Progress updates after each qualified order, and excludes cancelled or returned orders under the rules.
  4. The progress bar is computed on the server; the apps never compute it.

Acceptance criteria

  • Standard, 72 500,00 DA qualified, Bronze at 100 000,00 DA: 27 500,00 DA missing and 72,5 % shown.
  • A return of 10 000,00 DA lowers the qualified amount and moves the bar back.

Data — LoyaltyAccount, LoyaltyLevelDefinition, QualifiedPurchaseEntry.

Interfaces

LOY-22 — Full history

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§17)API · BO · RA · RWSRV-50, DSH-24, WEB-21, MRA-21

Statement — Every point, cashback amount, voucher and reward should be recorded, in separate ledgers that can also be read in one combined view.

Rules

  1. Each entry carries date and time, type, order reference, eligible amount, calculation rule and version, points or cashback earned or used, balance after, expiry date, reason of a correction and the staff user, where they apply.
  2. Points (LoyaltyTransaction), cashback (CashbackTransaction) and rewards (RewardRedemption, PrizeEntitlement) stay separate. loyalty.history and admin.loyalty.accounts.history merge them by date.
  3. Ledgers are append-only: a correction is a new entry, never an edit or a deletion.
  4. The reseller never sees staff identity or internal notes; the back-office does.

Acceptance criteria

  • For one reseller, the sum of each ledger equals the balance shown, and web, app and back-office show the same entries.
  • A manual correction shows its reason and author in the back-office only.

Data — LoyaltyTransaction, CashbackTransaction, RewardRedemption, PrizeEntitlement, QualifiedPurchaseEntry, LoyaltyCalculation.

Interfaces

LOY-23 — Back-office administration of the programme

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§18, §19; letter §1.3)API · BOSRV-50, DSH-22, DSH-23, DSH-24

Statement — An administrator should be able to create, change, enable or disable every rule of the programme, and follow and correct any reseller's account, without a developer.

Rules

  1. Every feature has its own switch and its own settings: barèmes, level bonuses and thresholds, level period, cashback, missions, referral, challenges, rewards and prizes. No commercial value lives in code (document §19).
  2. BO-83 finds a reseller and shows level, qualified purchases, points, cashback, rewards received, progress and all ledgers.
  3. Manual adjustments of points, cashback or qualified purchases need loyalty.update, a written reason, and write both a ledger entry and an AuditLog row (BR-105).
  4. Roles follow the permissions matrix: rules loyalty.administer; rankings, referrals, reviews and recalculations loyalty.validate. Who holds them is D-56.

Acceptance criteria

  • A new Diamond level is created, activated and shown in the apps with no release.
  • An adjustment without a reason → 422 REASON_REQUIRED.

Data — LoyaltyRule, LoyaltyLevelDefinition, LoyaltyCampaign, AuditLog.

Interfaces

LOY-24 — Programme dashboard

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§18; letter §1.3)API · BOSRV-50, DSH-24

Statement — The back-office should give a programme dashboard with enrolment, balances, costs and results.

Rules

  1. Indicators: enrolled resellers; resellers per level; points earned, used and expired; cashback earned and used; most used rewards; most active resellers; mission and challenge results; cost of rewards and offers; points usage rate; resellers who moved up or down.
  2. Filters: period, wilaya, customer type, level. Cost is an estimate in centimes HT from the values configured on rewards and prizes.
  3. Figures come from the nightly aggregate loyalty.dashboardAggregates and show their calculation time. Purchase prices stay behind pricing.view.

Acceptance criteria

  • Totals earned, used and expired on the dashboard match the ledgers for the same period.
  • A user without loyalty.view gets 403 PERMISSION_DENIED.

Data — LoyaltyTransaction, CashbackTransaction, LoyaltyLevelChange, RewardRedemption.

Interfaces

LOY-25 — Rule versioning and recalculation

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§19)API · BOSRV-50, DSH-22

Statement — Every rule change should be kept as a version and should state whether it applies to new operations only or triggers a recalculation of past operations.

Rules

  1. Saving a rule writes a LoyaltyRuleVersion with author, date, before and after values and RuleChangeScope: NEW_OPERATIONS_ONLY (default) or RECALCULATE.
  2. RECALCULATE needs a LoyaltyRecalculation: a period, a preview of the impact (resellers, points, cashback, level changes), then a run by a loyalty.validate holder.
  3. A recalculation never edits history: it appends RECALCULATION entries with the rule version and can be traced back as a whole.
  4. Each ledger entry stores the version that produced it, so past results stay explainable.

Acceptance criteria

  • Changing a barème with NEW_OPERATIONS_ONLY leaves past entries and balances unchanged.
  • A recalculation preview changes nothing; running it appends entries whose sum equals the preview.

Data — LoyaltyRuleVersion, LoyaltyRecalculation, LoyaltyTransaction, CashbackTransaction.

Interfaces

LOY-26 — Mandatory tests before launch

ReleasePrioritySourceAppsOwner tasks
V2SHOULDClient loyalty document + letter of 6 Nov 2026 (§19, §20)API · BO · RA · RWQA-04, SRV-50

Statement — Before delivery, the team should prove the cases of document §20 end to end, and each rule should be testable before it is activated.

Rules

  1. The cases below are mandatory and are run in QA-04 on staging, on the reseller web, the reseller app and the back-office.
  2. admin.loyalty.simulate tests a rule on a sample order and reseller, with no ledger entry.
  3. The three surfaces show the same data (document §19, rule 8).

Acceptance criteria

  • A qualified order earns the correct points.
  • A Bronze reseller's level bonus is computed correctly.
  • A cancelled order earns no final points.
  • A partial return removes only the points of the returned products.
  • A reseller who spends points sees the balance fall, and qualified purchases unchanged.
  • A reseller reaching the Bronze threshold has level and benefits updated automatically.
  • A completed mission pays once only.
  • A referral pays nothing before its conditions are met.
  • After a Happy Days campaign ends, points are no longer multiplied.
  • A used chest or wheel entitlement cannot be used again.
  • Points close to expiry appear in the app and are notified, according to the settings.

Data — All the loyalty models.

Interfaces

On this page