Loyalty (V2)
V2 loyalty programme for resellers — points and level progress, qualified purchases, history, rewards and vouchers, cashback, campaigns, missions, ranking, badges, referral, chest and wheel.
V2 — baseline contract
Loyalty is a V2 evolution (cahier §14.2, D-16). These operations enter the contract with SRV-29 and are built in SRV-30, MRA-20 and WEB-20. Until then catalog.home returns account.loyaltyPoints: null and the « Points » tile stays disabled. Earning rules, levels and expiry are HOCO's policy (D-05, D-45 to D-63); the values below are examples.
Change request 04
The operations added by HOCO's loyalty document and the letter of 6 November 2026 enter the contract with SRV-43. Status: change request 04, not yet accepted or priced by HOCO. All of these operations are built. Each stays behind its switch and answers 403 FEATURE_DISABLED while it is off. GET /loyalty/occasion returns { items }, one row per declared date. A review of an order not delivered answers 409 ORDER_NOT_DELIVERED, the status that code already had.
The « Fidélité » and « Récompenses » screens (reference screen 7, cahier §4.6, §5.5): points earned on orders, levels configured by HOCO, reached through qualified purchases over a period, rewards exchanged for points.
- Ledger, not a counter. The balance is the sum of
LoyaltyTransactionrows —EARN,BONUS,REDEEM,EXPIRE,ADJUST,REVERSAL— never edited (LOY-05, lifecycle). - Earning line by line on the eligible amount HT, without delivery fee, when the order reaches
loyalty.earnOn(DELIVEREDor invoicePAID), reversed on the lines concerned on cancellation or return (LOY-01, LOY-02, BR-40, BR-94). - Levels are configured data, computed on qualified purchases over a configurable period against thresholds validated by HOCO (LOY-03). Spending points changes nothing. They are independent of the customer type, which alone sets prices in V1.
- Rewards that are unavailable cannot be redeemed (cahier §5.5); eligibility is computed by the server and returned with each reward (LOY-04).
- Signed-in resellers only; guests get
401, other users403 PERMISSION_DENIED. When the programme is switched off (loyalty.enabled = false) every operation answers403 FEATURE_DISABLED(details.feature = "loyalty").
| Method | Path | Operation | Access | Apps | Release |
|---|---|---|---|---|---|
| GET | /loyalty/summary | loyalty.summaryPoints balance, level and qualified purchases (V2) | self | RA · RW | V2 |
| GET | /loyalty/transactions | loyalty.transactionsPoints history (V2) | self | RA · RW | V2 |
| GET | /loyalty/rewards | loyalty.rewardsRewards catalogue with eligibility (V2) | self | RA · RW | V2 |
| POST | /loyalty/rewards/{rewardId}/redeem | loyalty.redeemRedeem points for a reward (V2) | selfIdempotency-Key | RA · RW | V2 |
| GET | /loyalty/redemptions | loyalty.redemptionsMy redemptions and vouchers (V2) | self | RA · RW | V2 |
| GET | /loyalty/objective | loyalty.objectiveCurrent level, remaining conditions and next benefits (V2) | self | RA · RW | V2 |
| GET | /loyalty/levels | loyalty.levelsActive levels with conditions and benefits (V2) | self | RA · RW | V2 |
| GET | /loyalty/history | loyalty.historyCombined history of points, cashback and rewards (V2) | self | RA · RW | V2 |
| GET | /loyalty/cashback | loyalty.cashbackCashback balance and conditions of use (V2) | self | RA · RW | V2 |
| GET | /loyalty/cashback/transactions | loyalty.cashback.transactionsCashback ledger (V2) | self | RA · RW | V2 |
| GET | /loyalty/campaigns | loyalty.campaignsRunning points campaigns and Happy Days (V2) | self | RA · RW | V2 |
| GET | /loyalty/missions | loyalty.missionsMy missions with progress (V2) | self | RA · RW | V2 |
| GET | /loyalty/missions/{missionId} | loyalty.missions.getMission detail (V2) | self | RA · RW | V2 |
| GET | /loyalty/challenges | loyalty.challengesCurrent and past monthly challenges (V2) | self | RA · RW | V2 |
| GET | /loyalty/challenges/{challengeId}/ranking | loyalty.challenges.rankingRanking of a challenge, without other resellers' figures (V2) | self | RA · RW | V2 |
| GET | /loyalty/badges | loyalty.badgesMy badges and badges to earn (V2) | self | RA · RW | V2 |
| GET | /loyalty/referral | loyalty.referralMy referral code and referrals (V2) | self | RA · RW | V2 |
| GET · PUT | /loyalty/occasion | loyalty.occasionDeclare and read the occasion date (V2) | self | RA · RW | V2 |
| GET | /loyalty/chests | loyalty.chestsMy gift chests and their odds (V2) | self | RA · RW | V2 |
| POST | /loyalty/chests/{chestId}/open | loyalty.chests.openOpen a gift chest (V2) | selfIdempotency-Key | RA · RW | V2 |
| GET | /loyalty/wheel | loyalty.wheelWheel prizes, odds and my spins (V2) | self | RA · RW | V2 |
| POST | /loyalty/wheel/spins/{spinId}/spin | loyalty.wheel.spinUse one spin (V2) | selfIdempotency-Key | RA · RW | V2 |
| POST | /loyalty/reviews | loyalty.reviews.createLeave a review on a delivered order (V2) | selfIdempotency-Key | RA · RW | V2 |
Every operation can also answer 401 UNAUTHENTICATED, 403 ACCOUNT_SUSPENDED, 426 UPGRADE_REQUIRED, 429 RATE_LIMITED, 500 INTERNAL_ERROR and 503 MAINTENANCE — see the error registry.
Schemas
interface LoyaltySummary {
points: number; // spendable balance
pendingPoints: number; // estimate of open orders (« en attente »), not spendable
level: LevelRef; // { id, code, name }: configured data, not an enum
nextLevel: LevelRef | null; // null at the top level
qualifiedAmount: Money; // HT, over the level period; spending points never lowers it
qualifiedOrders: number;
amountToNextLevel: Money | null;
ordersToNextLevel: number | null; // null when the next level has no order condition
levelProgress: { currentThreshold: Money; nextThreshold: Money | null; ratio: BasisPoints }; // qualifiedAmount / nextThreshold
period: { startsOn: string | null; endsOn: string }; // YYYY-MM-DD; startsOn null when counted since sign-up
levels: { id: Uuid; code: string; name: string; minAmount: Money; minOrders: number | null; benefits: string[] }[];
earnRate: { amountHt: Money; points: number }; // general rule: 1 point per 100,00 DA HT
cashback: Money | null; // null while cashback is disabled
expiringSoon: { points: number; expiresOn: string } | null;
}
interface LoyaltyTransactionView {
id: Uuid;
type: LoyaltyTransactionType; // EARN, BONUS, REDEEM, EXPIRE, ADJUST, REVERSAL, RECALCULATION
points: number; // signed
balanceAfter: number;
label: string; // « Commande CMD-2027-000412 livrée »
order: { id: Uuid; number: string } | null;
redemptionId: Uuid | null;
expiresOn: string | null; // EARN and BONUS rows
occurredAt: Iso;
}
interface RewardView {
id: Uuid;
type: RewardType; // VOUCHER, FREE_DELIVERY, DISCOUNT, GIFT, EARLY_ACCESS, COMMERCIAL_ADVANTAGE
name: string;
description: string;
imageUrl: string | null;
costPoints: number;
minLevel: LevelRef | null;
value: { amount: Money | null; percent: BasisPoints | null }; // VOUCHER: amount HT (D-60) · DISCOUNT: percent
available: boolean; // in stock and within its dates; the stock number is never returned
conditions: string | null;
deliveryMethod: string | null;
perResellerLimit: number | null; // per period
validUntil: Iso | null;
eligibility: {
eligible: boolean;
reasons: ("INSUFFICIENT_POINTS" | "LEVEL_TOO_LOW" | "UNAVAILABLE" | "LIMIT_REACHED")[];
missingPoints: number;
};
}
interface RedemptionView {
id: Uuid;
reward: { id: Uuid; type: RewardType; name: string; imageUrl: string | null };
qty: number;
pointsSpent: number;
status: RedemptionStatus; // PENDING, FULFILLED, CANCELLED
vouchers: Voucher[]; // one single-use voucher per unit redeemed
voucher: { // the first of them
id: Uuid;
code: string; // "LIV-7K3M-9QX2"
type: "VOUCHER" | "FREE_DELIVERY" | "DISCOUNT";
value: { amount: Money | null; percent: BasisPoints | null };
expiresAt: Iso;
status: VoucherStatus; // ACTIVE, USED, EXPIRED, CANCELLED
usedOnOrder: { id: Uuid; number: string } | null;
} | null;
fulfilment: string | null; // GIFT: « Remis avec votre prochaine commande »
balanceAfter: number;
createdAt: Iso;
fulfilledAt: Iso | null;
}Operations
GET /loyalty/summary
loyalty.summary · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-03
Purpose. « Mes points de fidélité » and « Mon niveau revendeur »: balance, level, progress bar to the next level.
Request — no parameters.
Response — 200 OK: a LoyaltySummary.
{
"points": 12450,
"level": { "id": "01a60000-0000-7000-8000-000000000003", "code": "BRONZE", "name": "Bronze" },
"nextLevel": { "id": "01a60000-0000-7000-8000-000000000004", "code": "SILVER", "name": "Silver" },
"qualifiedAmount": 42000000,
"qualifiedOrders": 7,
"amountToNextLevel": 8000000,
"ordersToNextLevel": 3,
"levelProgress": { "currentThreshold": 10000000, "nextThreshold": 50000000, "ratio": 8400 },
"period": { "startsOn": "2026-06-01", "endsOn": "2027-05-31" },
"levels": [
{ "id": "01a60000-0000-7000-8000-000000000001", "code": "STANDARD", "name": "Standard", "minAmount": 0, "minOrders": null, "benefits": ["Cumul de points sur chaque commande qualifiée"] },
{ "id": "01a60000-0000-7000-8000-000000000003", "code": "BRONZE", "name": "Bronze", "minAmount": 10000000, "minOrders": null, "benefits": ["+10 % sur les points de base"] },
{ "id": "01a60000-0000-7000-8000-000000000004", "code": "SILVER", "name": "Silver", "minAmount": 50000000, "minOrders": 10, "benefits": ["+20 % sur les points de base", "Promotions exclusives"] }
],
"earnRate": { "amountHt": 10000, "points": 1 },
"cashback": null,
"expiringSoon": { "points": 1200, "expiresOn": "2027-06-30" }
}The thresholds are the document's examples, to confirm in D-49.
| Field | Notes |
|---|---|
amountToNextLevel, ordersToNextLevel, levelProgress | « Plus que 80 000 DA et 3 commandes pour atteindre le niveau Silver »; ratio = qualifiedAmount / nextThreshold in basis points. |
points vs qualifiedAmount | Separate balances: redeeming lowers points, never qualifiedAmount, so spending does not make a reseller lose their level (BR-87). |
expiringSoon | Points expiring within loyalty.expiryNoticeDays (30). |
Errors — 403 FEATURE_DISABLED.
Rules & side effects — read-only; the level is computed after each qualified order and evaluated for upkeep by loyalty.recomputeLevels; a level change sends loyalty.level_reached or loyalty.level_dropped (push, inbox).
Used by — RA-38, RW-15; home tile through catalog.home → account.loyaltyPoints.
GET /loyalty/transactions
loyalty.transactions · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-05
Purpose. « Voir l'historique »: every points movement, newest first, traceable to its order or redemption (cahier §12 « Les points sont crédités, débités et historisés correctement »).
Request — type (LoyaltyTransactionType, repeatable), from, to (YYYY-MM-DD), cursor, limit (default 20, max 100).
Response — 200 OK: { items: LoyaltyTransactionView[], nextCursor }.
{
"items": [
{ "id": "01a57352-3900-7703-b1dc-6eb798606c23", "type": "REDEEM", "points": -3000, "balanceAfter": 12450, "label": "Échange : Livraison offerte", "order": null, "redemptionId": "01a57352-3900-72ce-8e18-68d2386178eb", "expiresOn": null, "occurredAt": "2027-05-12T10:00:00Z" },
{ "id": "01a56905-8100-7d86-9fa1-964817c87083", "type": "EARN", "points": 803, "balanceAfter": 15450, "label": "Commande CMD-2027-000412 livrée", "order": { "id": "01a55f2c-7a00-7b13-8c24-3d4e5f607182", "number": "CMD-2027-000412" }, "redemptionId": null, "expiresOn": "2028-05-31", "occurredAt": "2027-05-10T10:00:00Z" },
{ "id": "01a53886-f400-7bd1-806a-1f3535fae7b0", "type": "EXPIRE", "points": -300, "balanceAfter": 14647, "label": "Points expirés (gagnés en avril 2026)", "order": null, "redemptionId": null, "expiresOn": null, "occurredAt": "2027-05-01T00:00:00Z" },
{ "id": "01a52b39-3100-71c4-9f7a-09d750551b7e", "type": "BONUS", "points": 500, "balanceAfter": 14947, "label": "Bonus de lancement du programme fidélité", "order": null, "redemptionId": null, "expiresOn": "2028-04-30", "occurredAt": "2027-04-28T10:00:00Z" }
],
"nextCursor": "eyJjIjoiMjAyNy0wNC0yOFQxMDowMDowMFoiLCJpIjoiMDFhNTJiMzkifQ"
}The EARN row is an order with 80 380,00 DA of eligible amount HT at 1 point per 100,00 DA (rounded down).
Errors — 400 VALIDATION_FAILED (unknown type, from after to), 403 FEATURE_DISABLED.
Rules & side effects — read-only; balanceAfter lets the app show the running balance without recomputing.
Used by — history of RA-38, RW-15.
GET /loyalty/rewards
loyalty.rewards · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-04
Purpose. « Récompenses disponibles »: the rewards catalogue with, for each reward, whether I can redeem it now and why not.
Request — eligibleOnly (boolean, default false), type (RewardType, repeatable), cursor, limit.
Response — 200 OK: { items: RewardView[], nextCursor }, cheapest first.
{
"items": [
{ "id": "01a49ff6-a208-7dcb-ae4e-a7708a7fe389", "type": "FREE_DELIVERY", "name": "Livraison offerte", "description": "Une livraison offerte sur votre prochaine commande, valable 90 jours.", "imageUrl": "https://cdn.hoco.dz/rewards/livraison-offerte.webp", "costPoints": 3000, "minLevel": null, "value": { "amount": null, "percent": null }, "available": true, "perResellerLimit": 4, "validUntil": null, "eligibility": { "eligible": true, "reasons": [], "missingPoints": 0 } },
{ "id": "01a49ff6-9268-7a6c-ba93-b0c8566aa0b1", "type": "GIFT", "name": "Câble USB-C HOCO", "description": "Un câble HOCO X89 offert, remis avec votre prochaine commande.", "imageUrl": "https://cdn.hoco.dz/rewards/cable-usb-c.webp", "costPoints": 6000, "minLevel": null, "value": { "amount": null, "percent": null }, "available": true, "perResellerLimit": null, "validUntil": null, "eligibility": { "eligible": true, "reasons": [], "missingPoints": 0 } },
{ "id": "01a49ff6-8e80-7770-93fe-b94b355feff6", "type": "GIFT", "name": "Chargeur HOCO 18W", "description": "Un chargeur HOCO 18W offert, remis avec votre prochaine commande.", "imageUrl": "https://cdn.hoco.dz/rewards/chargeur-18w.webp", "costPoints": 10000, "minLevel": null, "value": { "amount": null, "percent": null }, "available": true, "perResellerLimit": null, "validUntil": null, "eligibility": { "eligible": true, "reasons": [], "missingPoints": 0 } },
{ "id": "01a49ff6-9650-7037-9a23-56db872ec25d", "type": "GIFT", "name": "Power Bank HOCO 10000mAh", "description": "Une power bank HOCO J86A offerte, remise avec votre prochaine commande.", "imageUrl": "https://cdn.hoco.dz/rewards/power-bank.webp", "costPoints": 12000, "minLevel": null, "value": { "amount": null, "percent": null }, "available": true, "perResellerLimit": null, "validUntil": null, "eligibility": { "eligible": true, "reasons": [], "missingPoints": 0 } },
{ "id": "01a49ff6-9e20-7514-be23-606e20f62354", "type": "VOUCHER", "name": "Bon d'achat 2 000 DA", "description": "2 000,00 DA déduits de votre prochaine commande, réservé aux niveaux Gold et VIP.", "imageUrl": "https://cdn.hoco.dz/rewards/bon-2000.webp", "costPoints": 15000, "minLevel": { "id": "01a60000-0000-7000-8000-000000000005", "code": "GOLD", "name": "Gold" }, "value": { "amount": 200000, "percent": null }, "available": true, "perResellerLimit": 2, "validUntil": "2027-12-31T22:59:59Z", "eligibility": { "eligible": false, "reasons": ["LEVEL_TOO_LOW", "INSUFFICIENT_POINTS"], "missingPoints": 2550 } },
{ "id": "01a49ff6-9a38-703a-aff9-b053b98f7e05", "type": "GIFT", "name": "Écouteurs TWS HOCO", "description": "Une paire d'écouteurs HOCO EW41 offerte.", "imageUrl": "https://cdn.hoco.dz/rewards/ecouteurs-tws.webp", "costPoints": 18000, "minLevel": null, "value": { "amount": null, "percent": null }, "available": true, "perResellerLimit": null, "validUntil": null, "eligibility": { "eligible": false, "reasons": ["INSUFFICIENT_POINTS"], "missingPoints": 5550 } }
],
"nextCursor": null
}Errors — 400 VALIDATION_FAILED, 403 FEATURE_DISABLED.
Rules & side effects — read-only. Unavailable rewards (out of gift stock, outside their dates) are listed with available: false and UNAVAILABLE so the reseller sees the catalogue, but cannot redeem them (cahier §5.5). No gift stock quantity is exposed.
Used by — RA-39, « Récompenses disponibles » of reference screen 7, RW-15.
POST /loyalty/rewards/{rewardId}/redeem
loyalty.redeem · Access session — reseller (self), AccountStatus ACTIVE · Apps RA, RW · Idempotency-Key required · Release V2 · Requirements LOY-04
Purpose. Exchanges points for a reward; vouchers are issued at once, gifts are delivered with the next order.
Request
interface RedeemRequest {
qty?: number; // default 1, within perResellerLimit
}POST /v1/loyalty/rewards/01a49ff6-a208-7dcb-ae4e-a7708a7fe389/redeem{ "qty": 1 }Response — 201 Created: the RedemptionView.
{
"id": "01a57352-3900-72ce-8e18-68d2386178eb",
"reward": { "id": "01a49ff6-a208-7dcb-ae4e-a7708a7fe389", "type": "FREE_DELIVERY", "name": "Livraison offerte", "imageUrl": "https://cdn.hoco.dz/rewards/livraison-offerte.webp" },
"qty": 1,
"pointsSpent": 3000,
"status": "FULFILLED",
"voucher": {
"id": "01a57352-3900-7ee9-b653-a32074077342",
"code": "LIV-7K3M-9QX2",
"type": "FREE_DELIVERY",
"value": { "amount": null, "percent": null },
"expiresAt": "2027-08-10T22:59:59Z",
"status": "ACTIVE",
"usedOnOrder": null
},
"fulfilment": "Code à saisir au moment de valider votre commande.",
"balanceAfter": 12450,
"createdAt": "2027-05-12T10:00:00Z",
"fulfilledAt": "2027-05-12T10:00:00Z"
}Errors
| Status | Code | When |
|---|---|---|
| 403 | FEATURE_DISABLED | Programme switched off. |
| 403 | ACCOUNT_PENDING_VALIDATION | Account not validated. |
| 404 | NOT_FOUND | Unknown reward. |
| 422 | INSUFFICIENT_POINTS | Balance below costPoints × qty (details: { points, required, missingPoints }). |
| 422 | LOYALTY_LEVEL_TOO_LOW | Below minLevel (details: { level, minLevel }). |
| 422 | REWARD_UNAVAILABLE | Out of gift stock or outside its dates. |
| 422 | REWARD_LIMIT_REACHED | perResellerLimit for the period reached. |
Rules & side effects
- One transaction:
RewardRedemption,LoyaltyTransactionREDEEM(−pointsSpent, balance lockedFOR UPDATEso two devices cannot overspend), and per type:VOUCHER,FREE_DELIVERY,DISCOUNT→ aVoucherwith a unique code, statusFULFILLED;GIFT,COMMERCIAL_ADVANTAGE→ statusPENDING, the gift is added free to the next order or the advantage is applied by the back-office (admin.redemptions.list);EARLY_ACCESS→ flag on the account for the period,FULFILLED. - Vouchers are used at checkout: the V2
cart.checkoutbody gains an optionalvoucherCodeandcashbackAmount(see checkout, V2 additions); a used voucher records its order. - Cancelling a
PENDINGredemption (back-office) or an unused voucher writes aREVERSALthat gives the points back. - Outbox
loyalty.redeemed→ inbox and back-office queue for gifts.
Used by — « Échanger » on RA-39, RW-15.
GET /loyalty/redemptions
loyalty.redemptions · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-04
Purpose. « Mes récompenses »: my redemptions, gifts to receive and vouchers with their codes.
Request — status (repeatable), cursor, limit.
Response — 200 OK: { items: RedemptionView[], nextCursor }.
{
"items": [
{
"id": "01a57352-3900-72ce-8e18-68d2386178eb",
"reward": { "id": "01a49ff6-a208-7dcb-ae4e-a7708a7fe389", "type": "FREE_DELIVERY", "name": "Livraison offerte", "imageUrl": "https://cdn.hoco.dz/rewards/livraison-offerte.webp" },
"qty": 1,
"pointsSpent": 3000,
"status": "FULFILLED",
"voucher": { "id": "01a57352-3900-7ee9-b653-a32074077342", "code": "LIV-7K3M-9QX2", "type": "FREE_DELIVERY", "value": { "amount": null, "percent": null }, "expiresAt": "2027-08-10T22:59:59Z", "status": "ACTIVE", "usedOnOrder": null },
"fulfilment": "Code à saisir au moment de valider votre commande.",
"balanceAfter": 12450,
"createdAt": "2027-05-12T10:00:00Z",
"fulfilledAt": "2027-05-12T10:00:00Z"
},
{
"id": "01a50206-5100-78e9-93bb-33f5aa5421be",
"reward": { "id": "01a49ff6-9268-7a6c-ba93-b0c8566aa0b1", "type": "GIFT", "name": "Câble USB-C HOCO", "imageUrl": "https://cdn.hoco.dz/rewards/cable-usb-c.webp" },
"qty": 1,
"pointsSpent": 6000,
"status": "FULFILLED",
"voucher": null,
"fulfilment": "Remis avec la commande CMD-2027-000398.",
"balanceAfter": 14447,
"createdAt": "2027-04-20T10:00:00Z",
"fulfilledAt": "2027-04-24T09:30:00Z"
}
],
"nextCursor": null
}Errors — 400 VALIDATION_FAILED, 403 FEATURE_DISABLED.
Rules & side effects — read-only; voucher codes are shown in full only to their owner.
Full programme (change request 04)
Added by HOCO's loyalty document and the letter of 6 November 2026 (change request 04, not yet accepted or priced by HOCO). Every operation answers 403 FEATURE_DISABLED when its feature is off (details.feature). Amounts are integer centimes.
GET /loyalty/objective
loyalty.objective · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-21
Purpose. The personal objective of the home and RA-42.
Request — no parameters.
Response — 200 OK.
{
"level": {
"id": "01a60000-0000-7000-8000-000000000001",
"code": "STANDARD",
"name": "Standard"
},
"nextLevel": {
"id": "01a60000-0000-7000-8000-000000000002",
"code": "BRONZE",
"name": "Bronze"
},
"qualifiedAmount": 7250000,
"qualifiedOrders": 4,
"remaining": {
"amount": 2750000,
"orders": 1
},
"progress": 7250,
"nextBenefits": [
"+10 % sur les points de base"
],
"dropNotice": null
}remaining.orders is null when the next level has no order condition. progress is in basis points. qualifiedAmount is HT.
Errors — 403 FEATURE_DISABLED.
Rules & side effects — Read-only, computed on the server.
Used by — RA-42, RA-09, RW-16.
GET /loyalty/levels
loyalty.levels · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-03, LOY-20
Purpose. The levels HOCO configured, in order.
Request — no parameters.
Response — 200 OK.
{
"items": [
{
"id": "01a60000-0000-7000-8000-000000000002",
"code": "BRONZE",
"name": "Bronze",
"rank": 1,
"minAmount": 10000000,
"minOrders": null,
"pointsBonusBp": 1000,
"benefits": [
"Offres réservées au niveau Bronze"
]
}
],
"period": {
"mode": "ROLLING_MONTHS",
"months": 12
}
}Errors — 403 FEATURE_DISABLED.
Rules & side effects — Read-only.
GET /loyalty/history
loyalty.history · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-22
Purpose. One timeline over the separate ledgers.
Request — ledger (POINTS, CASHBACK, REWARDS, repeatable), from, to, cursor, limit.
Response — 200 OK.
{
"items": [
{
"id": "01a60000-0000-7000-8000-000000000010",
"ledger": "POINTS",
"type": "EARN",
"label": "Commande CMD-2027-000412 livrée",
"order": {
"id": "01a55f2c-7a00-7b13-8c24-3d4e5f607182",
"number": "CMD-2027-000412"
},
"eligibleAmount": 8038000,
"points": 803,
"cashback": null,
"balanceAfter": 15450,
"expiresOn": "2028-05-31",
"occurredAt": "2027-05-10T10:00:00Z"
}
],
"nextCursor": null
}Errors — 400 VALIDATION_FAILED, 403 FEATURE_DISABLED.
Rules & side effects — Read-only; staff identity and internal notes are never returned.
GET /loyalty/cashback
loyalty.cashback · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-14
Purpose. Balance, expiry and the limits that apply at checkout.
Request — no parameters.
Response — 200 OK.
{
"balance": 200000,
"expiringSoon": {
"amount": 50000,
"expiresOn": "2027-06-30"
},
"maxUsePercentBp": 2000,
"minOrderAmount": 1000000
}Amounts in centimes. The tax treatment is open (D-60).
Errors — 403 FEATURE_DISABLED (details.feature = "cashback").
Rules & side effects — Read-only.
GET /loyalty/cashback/transactions
loyalty.cashback.transactions · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-14
Purpose. Every cashback movement, newest first.
Request — type (CashbackTransactionType, repeatable), from, to, cursor, limit.
Response — 200 OK.
{
"items": [
{
"id": "01a60000-0000-7000-8000-000000000011",
"type": "EARN",
"amount": 200000,
"balanceAfter": 200000,
"order": {
"id": "01a55f2c-7a00-7b13-8c24-3d4e5f607182",
"number": "CMD-2027-000412"
},
"expiresOn": "2028-05-31",
"occurredAt": "2027-05-10T10:00:00Z"
}
],
"nextCursor": null
}Errors — 400 VALIDATION_FAILED, 403 FEATURE_DISABLED.
Rules & side effects — Read-only.
GET /loyalty/campaigns
loyalty.campaigns · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-10, LOY-13
Purpose. Campaigns the reseller can benefit from now.
Request — cursor, limit.
Response — 200 OK.
{
"items": [
{
"id": "01a60000-0000-7000-8000-000000000012",
"kind": "NEW_PRODUCT",
"name": "Lancement TWS",
"multiplierBp": 20000,
"endsAt": "2027-05-31T22:59:59Z",
"products": [],
"placesAvailable": true
}
],
"nextCursor": null
}placesAvailable is a boolean; the count of places left is never returned (BR-99).
Errors — 403 FEATURE_DISABLED.
Rules & side effects — Read-only; filtered by level and customer type.
GET /loyalty/missions
loyalty.missions · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-06
Purpose. Missions assigned to the reseller.
Request — status (MissionStatus, repeatable), cursor, limit.
Response — 200 OK.
{
"items": [
{
"id": "01a60000-0000-7000-8000-000000000013",
"name": "3 commandes ce mois-ci",
"cadence": "MONTHLY",
"status": "IN_PROGRESS",
"progress": {
"current": 2,
"target": 3,
"unit": "ORDERS"
},
"reward": {
"kind": "POINTS",
"points": 500
},
"endsAt": "2027-05-31T22:59:59Z"
}
],
"nextCursor": null
}Errors — 400 VALIDATION_FAILED, 403 FEATURE_DISABLED.
Rules & side effects — Read-only.
GET /loyalty/missions/{missionId}
loyalty.missions.get · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-06
Purpose. Conditions, progress and reward of one mission; the target of the SN-07, SN-22 and SN-24 deep links.
Request — path missionId.
Response — 200 OK: one item of loyalty.missions with description and conditions.
Errors — 403 FEATURE_DISABLED, 404 NOT_FOUND.
Rules & side effects — Read-only.
GET /loyalty/challenges
loyalty.challenges · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-07
Purpose. The running challenge, its criterion and prizes, and the last published ones.
Request — status, cursor, limit.
Response — 200 OK.
{
"items": [
{
"id": "01a60000-0000-7000-8000-000000000014",
"name": "Challenge de mai",
"criterion": "PURCHASE_AMOUNT",
"topN": 10,
"status": "OPEN",
"startsAt": "2027-04-30T23:00:00Z",
"endsAt": "2027-05-31T22:59:59Z",
"myRank": 14
}
],
"nextCursor": null
}Errors — 403 FEATURE_DISABLED.
Rules & side effects — Read-only.
Used by — RA-46, RW-17, RA-09.
GET /loyalty/challenges/{challengeId}/ranking
loyalty.challenges.ranking · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-07
Purpose. Top N and the reseller's own position.
Request — path challengeId.
Response — 200 OK.
{
"criterion": "PURCHASE_AMOUNT",
"refreshedAt": "2027-05-12T09:00:00Z",
"final": false,
"items": [
{
"rank": 1,
"storeName": "Phone Center Oran"
}
],
"me": {
"rank": 14,
"value": 42000000
}
}value appears only on me. Other resellers' amounts and order counts are never returned.
Errors — 403 FEATURE_DISABLED, 404 NOT_FOUND.
Rules & side effects — Read-only, refreshed by loyalty.refreshRanking.
GET /loyalty/badges
loyalty.badges · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-17
Purpose. Badges earned and those shown as goals.
Request — no parameters.
Response — 200 OK.
{
"items": [
{
"id": "01a60000-0000-7000-8000-000000000015",
"name": "Premier achat",
"imageUrl": "https://cdn.hoco.dz/badges/premier-achat.webp",
"earnedAt": "2027-03-02T10:00:00Z",
"endsAt": null,
"condition": "Première commande qualifiée"
}
]
}Errors — 403 FEATURE_DISABLED.
Rules & side effects — Read-only.
GET /loyalty/referral
loyalty.referral · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-15
Purpose. Code, link, conditions and the state of each referral. In V2, auth.signup.reseller accepts an optional referralCode.
Request — cursor, limit.
Response — 200 OK.
{
"code": "AB12CD34",
"link": "https://app.hoco.dz/r/AB12CD34",
"items": [
{
"id": "01a60000-0000-7000-8000-000000000016",
"storeName": "Mobile Plus",
"signedUpAt": "2027-04-02T10:00:00Z",
"firstQualifiedOrderAt": null,
"status": "PENDING"
}
],
"nextCursor": null
}Errors — 403 FEATURE_DISABLED.
Rules & side effects — Read-only.
GET · PUT /loyalty/occasion
loyalty.occasion · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-16
Purpose. The owner's birthday or the shop's founding date, verified by HOCO.
Request — PUT: { "type": "SHOP_FOUNDING", "date": "2014-05-20", "proofFileId": null }.
Response — 200 OK.
{
"type": "SHOP_FOUNDING",
"date": "2014-05-20",
"status": "DECLARED"
}Errors — 400 VALIDATION_FAILED, 403 FEATURE_DISABLED, 409 OCCASION_DATE_LOCKED (already verified).
Rules & side effects — A declared date pays nothing until it is VERIFIED (BR-101).
GET /loyalty/chests
loyalty.chests · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-18
Purpose. Available chests with expiry, and the odds of the table.
Request — status, cursor, limit.
Response — 200 OK.
{
"items": [
{
"id": "01a60000-0000-7000-8000-000000000017",
"status": "AVAILABLE",
"expiresAt": "2027-06-30T22:59:59Z",
"odds": [
{
"label": "500 points",
"oddsBp": 7000
},
{
"label": "Livraison offerte",
"oddsBp": 3000
}
]
}
],
"nextCursor": null
}No stock or budget figure is returned.
Errors — 403 FEATURE_DISABLED.
Rules & side effects — Read-only.
POST /loyalty/chests/{chestId}/open
loyalty.chests.open · Access session — reseller (self) · Apps RA, RW · Idempotency-Key required · Release V2 · Requirements LOY-18
Purpose. Draws one prize on the server and stores the result.
Request — path chestId, empty body.
Response — 200 OK.
{
"id": "01a60000-0000-7000-8000-000000000017",
"status": "USED",
"prize": {
"type": "POINTS",
"label": "500 points",
"conditions": null
},
"balanceAfter": 13450
}Errors — 403 FEATURE_DISABLED, 404 NOT_FOUND, 409 ENTITLEMENT_USED, 409 ENTITLEMENT_EXPIRED.
Rules & side effects — One transaction: draw among entries with stock and budget left, entitlement USED, prize applied, outbox loyalty.prize_won (BR-102).
GET /loyalty/wheel
loyalty.wheel · Access session — reseller (self) · Apps RA, RW · Idempotency-Key — · Release V2 · Requirements LOY-19
Purpose. What the wheel can give and the spins available.
Request — no parameters.
Response — 200 OK.
{
"prizes": [
{
"label": "Chargeur",
"oddsBp": 500
},
{
"label": "200 points",
"oddsBp": 9500
}
],
"spins": [
{
"id": "01a60000-0000-7000-8000-000000000018",
"expiresAt": "2027-06-30T22:59:59Z"
}
]
}Errors — 403 FEATURE_DISABLED.
Rules & side effects — Read-only.
POST /loyalty/wheel/spins/{spinId}/spin
loyalty.wheel.spin · Access session — reseller (self) · Apps RA, RW · Idempotency-Key required · Release V2 · Requirements LOY-19
Purpose. Draws the prize of one entitlement.
Request — path spinId, empty body.
Response — 200 OK.
{
"id": "01a60000-0000-7000-8000-000000000018",
"status": "USED",
"prize": {
"type": "FREE_DELIVERY",
"label": "Livraison offerte",
"conditions": "Valable 30 jours sur une commande."
}
}Errors — 403 FEATURE_DISABLED, 409 ENTITLEMENT_NOT_AVAILABLE, 409 ENTITLEMENT_USED, 409 ENTITLEMENT_EXPIRED.
Rules & side effects — As loyalty.chests.open.
POST /loyalty/reviews
loyalty.reviews.create · Access session — reseller (self) · Apps RA, RW · Idempotency-Key required · Release V2 · Requirements LOY-12
Purpose. Stores a review for moderation.
Request — { "orderId": "…", "productId": "…", "rating": 5, "comment": "…" }.
Response — 200 OK.
{
"id": "01a60000-0000-7000-8000-000000000019",
"status": "PENDING"
}Errors — 400 VALIDATION_FAILED, 403 FEATURE_DISABLED, 409 REVIEW_ALREADY_EXISTS, 422 ORDER_NOT_DELIVERED.
Rules & side effects — Status PENDING; the bonus is paid only on acceptance.
Invitations & attribution (public + reseller)
Public operations behind the delegates' invitation links and QR codes: resolving a code, attributing the app install to the inviting delegate, and the /i/ landing page that opens the right app or store.
Delegate home, profile, objectives & reports
The delegate app's read model of the day — home aggregate, profile and zones, objectives, performance and the history of visit and tour reports.