HOCO B2B
SRSAPI reference

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 LoyaltyTransaction rows — 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 (DELIVERED or invoice PAID), 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 users 403 PERMISSION_DENIED. When the programme is switched off (loyalty.enabled = false) every operation answers 403 FEATURE_DISABLED (details.feature = "loyalty").
MethodPathOperationAccessAppsRelease
GET/loyalty/summaryloyalty.summary
Points balance, level and qualified purchases (V2)
selfRA · RWV2
GET/loyalty/transactionsloyalty.transactions
Points history (V2)
selfRA · RWV2
GET/loyalty/rewardsloyalty.rewards
Rewards catalogue with eligibility (V2)
selfRA · RWV2
POST/loyalty/rewards/{rewardId}/redeemloyalty.redeem
Redeem points for a reward (V2)
self
Idempotency-Key
RA · RWV2
GET/loyalty/redemptionsloyalty.redemptions
My redemptions and vouchers (V2)
selfRA · RWV2
GET/loyalty/objectiveloyalty.objective
Current level, remaining conditions and next benefits (V2)
selfRA · RWV2
GET/loyalty/levelsloyalty.levels
Active levels with conditions and benefits (V2)
selfRA · RWV2
GET/loyalty/historyloyalty.history
Combined history of points, cashback and rewards (V2)
selfRA · RWV2
GET/loyalty/cashbackloyalty.cashback
Cashback balance and conditions of use (V2)
selfRA · RWV2
GET/loyalty/cashback/transactionsloyalty.cashback.transactions
Cashback ledger (V2)
selfRA · RWV2
GET/loyalty/campaignsloyalty.campaigns
Running points campaigns and Happy Days (V2)
selfRA · RWV2
GET/loyalty/missionsloyalty.missions
My missions with progress (V2)
selfRA · RWV2
GET/loyalty/missions/{missionId}loyalty.missions.get
Mission detail (V2)
selfRA · RWV2
GET/loyalty/challengesloyalty.challenges
Current and past monthly challenges (V2)
selfRA · RWV2
GET/loyalty/challenges/{challengeId}/rankingloyalty.challenges.ranking
Ranking of a challenge, without other resellers' figures (V2)
selfRA · RWV2
GET/loyalty/badgesloyalty.badges
My badges and badges to earn (V2)
selfRA · RWV2
GET/loyalty/referralloyalty.referral
My referral code and referrals (V2)
selfRA · RWV2
GET · PUT/loyalty/occasionloyalty.occasion
Declare and read the occasion date (V2)
selfRA · RWV2
GET/loyalty/chestsloyalty.chests
My gift chests and their odds (V2)
selfRA · RWV2
POST/loyalty/chests/{chestId}/openloyalty.chests.open
Open a gift chest (V2)
self
Idempotency-Key
RA · RWV2
GET/loyalty/wheelloyalty.wheel
Wheel prizes, odds and my spins (V2)
selfRA · RWV2
POST/loyalty/wheel/spins/{spinId}/spinloyalty.wheel.spin
Use one spin (V2)
self
Idempotency-Key
RA · RWV2
POST/loyalty/reviewsloyalty.reviews.create
Leave a review on a delivered order (V2)
self
Idempotency-Key
RA · RWV2

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.

FieldNotes
amountToNextLevel, ordersToNextLevel, levelProgress« Plus que 80 000 DA et 3 commandes pour atteindre le niveau Silver »; ratio = qualifiedAmount / nextThreshold in basis points.
points vs qualifiedAmountSeparate balances: redeeming lowers points, never qualifiedAmount, so spending does not make a reseller lose their level (BR-87).
expiringSoonPoints 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

StatusCodeWhen
403FEATURE_DISABLEDProgramme switched off.
403ACCOUNT_PENDING_VALIDATIONAccount not validated.
404NOT_FOUNDUnknown reward.
422INSUFFICIENT_POINTSBalance below costPoints × qty (details: { points, required, missingPoints }).
422LOYALTY_LEVEL_TOO_LOWBelow minLevel (details: { level, minLevel }).
422REWARD_UNAVAILABLEOut of gift stock or outside its dates.
422REWARD_LIMIT_REACHEDperResellerLimit for the period reached.

Rules & side effects

  1. One transaction: RewardRedemption, LoyaltyTransaction REDEEM (−pointsSpent, balance locked FOR UPDATE so two devices cannot overspend), and per type: VOUCHER, FREE_DELIVERY, DISCOUNT → a Voucher with a unique code, status FULFILLED; GIFT, COMMERCIAL_ADVANTAGE → status PENDING, 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.
  2. Vouchers are used at checkout: the V2 cart.checkout body gains an optional voucherCode and cashbackAmount (see checkout, V2 additions); a used voucher records its order.
  3. Cancelling a PENDING redemption (back-office) or an unused voucher writes a REVERSAL that gives the points back.
  4. 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.

Used by — RA-39, RW-15.

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.

Used by — RA-42, RW-16.

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.

Used by — RA-51, RW-16.

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.

Used by — RA-43, RW-16.

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.

Used by — RA-43, RW-16.

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.

Used by — RA-44, RW-16.

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.

Used by — RA-45, RW-17.

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.

Used by — RA-45, RW-17.

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.

Used by — RA-46, RW-17.

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.

Used by — RA-47, RW-17.

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.

Used by — RA-48, RW-18.

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).

Used by — RA-53, RW-18.

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.

Used by — RA-49, RW-18.

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).

Used by — RA-49, RW-18.

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.

Used by — RA-50, RW-18.

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.

Used by — RA-50, RW-18.

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.

Used by — RA-52, RW-18.

On this page