HOCO B2B
SRSAPI referenceBack-office endpoints

Promotions & loyalty

Back-office promotion operations — promotions with scope, targeting, schedule, caps and stacking, their status and simulation, banners and daily offers, and the V2 packs and loyalty programme.

These operations run the offers of cahier §4.6: daily offers, scheduled promotions and temporary discounts on products, categories or brands, targeting by wilaya, segment, level, brand or volume, configurable stacking, home banners, and — in V2 — profitable packs and the loyalty programme (points, levels Bronze/Silver/Gold/VIP, rewards). Screens: promotions list and editor (BO-49, BO-50), banners (BO-51), V2 packs, loyalty settings and rewards (BO-52 to BO-54). Statuses: Lifecycles › Promotion; pricing rules: BR-64 to BR-69.

Pricing order (V1). The reseller's price is the variant price of their customerType; promotions apply on top (BR-07). promotions.stackingMode (BEST_ONLY default, or STACK_BY_PRIORITY) decides how several eligible promotions combine.

Who uses it. The Administrateur commercial (cahier §3: « promotions »); the Super administrateur.

PermissionUnlocks on this page
promotions.viewPromotions, banners, packs (read), preview
promotions.create · promotions.update · promotions.deleteCreate · edit · delete drafts
promotions.validateSchedule, activate, pause, archive
loyalty.view · loyalty.create · loyalty.update · loyalty.delete · loyalty.validate · loyalty.administerV2 loyalty: read · rewards · adjustments and fulfilment · delete rewards · publish rankings, decide referrals, reviews and dates, run recalculations · programme rules and settings

Audit. CREATE, UPDATE, DELETE and STATUS_CHANGE rows on Promotion, Banner, Pack, Reward; V2 adjustments as UPDATE on LoyaltyAccount with the reason.

Conventions: lists return Page<T> = { items, total, page, pageSize } (responses); money in centimes, percentages in basis points; timestamps UTC, schedules evaluated in Africa/Algiers; editable records carry version. 401, 429 and 500 apply everywhere and are not repeated.

MethodPathOperationAccessAppsRelease
GET · POST · PATCH · DELETE/admin/promotions[/{promotionId}]admin.promotions.crud
Promotions (type, value, scope, targeting, schedule, cap, stacking)
promotions.*BOV1
POST/admin/promotions/{promotionId}/statusadmin.promotions.setStatus
Schedule, activate, pause, end now, archive
promotions.validateBOV1
GET/admin/promotions/{promotionId}/historyadmin.promotions.history
Creation, edits and status changes of a promotion
promotions.viewBOV1
POST/admin/promotions/overlapsadmin.promotions.overlaps
Promotions that cover the same products during the same dates
promotions.viewBOV1
POST/admin/promotions/previewadmin.promotions.preview
Simulate a promotion on a sample cart and reseller
promotions.viewBOV1
GET · POST · PATCH · DELETE/admin/banners[/{bannerId}]admin.banners.crud
Banners and daily offers
promotions.*BOV1
PUT/admin/banners/orderadmin.banners.reorder
Reorder the banners of a placement in one call
promotions.updateBOV1
GET · POST · PATCH · DELETE/admin/packs[/{packId}]admin.packs.crud
Packs (V2)
promotions.*BOV2
GET · PUT/admin/loyalty/settingsadmin.loyalty.settings
Programme switches, earning trigger, expiry, regularisation (V2)
loyalty.administerBOV2
POST/admin/loyalty/accounts/{resellerId}/adjustmentsadmin.loyalty.adjust
Manual points adjustment with reason (V2)
loyalty.updateBOV2
POST/admin/loyalty/accounts/{resellerId}/leveladmin.loyalty.setLevel
Manual level change with reason (V2)
loyalty.updateBOV2
POST/admin/loyalty/prize-entitlements/{entitlementId}/fulfiladmin.loyalty.prizeTables.fulfil
Record a physical prize as handed over (V2)
loyalty.updateBOV2
GET/admin/loyalty/campaigns/{campaignId}/beneficiariesadmin.loyalty.campaigns.beneficiaries
Places of a first-N campaign, in order (V2)
loyalty.viewBOV2
GET · POST · PATCH · DELETE/admin/rewards[/{rewardId}]admin.rewards.crud
Rewards catalogue (V2)
loyalty.*BOV2
GET · POST/admin/redemptions[/{redemptionId}/fulfil]admin.redemptions.list
Redemptions to fulfil (V2)
loyalty.updateBOV2
POST/admin/redemptions/{redemptionId}/canceladmin.redemptions.cancel
Cancel a pending redemption or an unused voucher (V2)
loyalty.updateBOV2
GET/admin/loyalty/dashboardadmin.loyalty.dashboard
Programme dashboard indicators (V2)
loyalty.viewBOV2
GET/admin/loyalty/accountsadmin.loyalty.accounts.list
Search loyalty accounts (V2)
loyalty.viewBOV2
GET/admin/loyalty/accounts/{resellerId}admin.loyalty.accounts.get
One reseller's loyalty account (V2)
loyalty.viewBOV2
GET/admin/loyalty/accounts/{resellerId}/historyadmin.loyalty.accounts.history
Combined history with actors and calculation steps (V2)
loyalty.viewBOV2
POST/admin/loyalty/accounts/{resellerId}/cashback-adjustmentsadmin.loyalty.cashback.adjust
Manual cashback adjustment with reason (V2)
loyalty.update
Idempotency-Key
BOV2
POST/admin/loyalty/accounts/{resellerId}/qualified-purchase-adjustmentsadmin.loyalty.purchases.adjust
Manual qualified-purchase adjustment with reason (V2)
loyalty.update
Idempotency-Key
BOV2
GET · POST · PATCH · DELETE/admin/loyalty/rules[/{ruleId}]admin.loyalty.rules.crud
Earning, bonus, cashback and birthday rules (V2)
loyalty.*BOV2
POST/admin/loyalty/rules/{ruleId}/statusadmin.loyalty.rules.setStatus
Enable, schedule, pause or end a rule (V2)
loyalty.administerBOV2
GET/admin/loyalty/rules/{ruleId}/versionsadmin.loyalty.rules.versions
Versions of a rule (V2)
loyalty.viewBOV2
POST/admin/loyalty/simulateadmin.loyalty.simulate
Test the rules on a sample order, no ledger entry (V2)
loyalty.viewBOV2
GET · POST/admin/loyalty/recalculations[/{recalculationId}]admin.loyalty.recalculations
Preview and run a recalculation (V2)
loyalty.validate
Idempotency-Key
BOV2
GET · POST · PATCH · DELETE/admin/loyalty/levels[/{levelId}]admin.loyalty.levels.crud
Configured levels (V2)
loyalty.*BOV2
GET · POST · PATCH · DELETE/admin/loyalty/campaigns[/{campaignId}]admin.loyalty.campaigns.crud
Occasions, Happy Days, selected products, new-product campaigns (V2)
loyalty.*BOV2
POST/admin/loyalty/campaigns/{campaignId}/statusadmin.loyalty.campaigns.setStatus
Schedule, activate, pause or end a campaign (V2)
loyalty.administerBOV2
GET · POST · PATCH · DELETE/admin/loyalty/missions[/{missionId}]admin.loyalty.missions.crud
Missions (V2)
loyalty.*BOV2
GET · POST · PATCH · DELETE/admin/loyalty/challenges[/{challengeId}]admin.loyalty.challenges.crud
Monthly challenges (V2)
loyalty.*BOV2
POST/admin/loyalty/challenges/{challengeId}/publishadmin.loyalty.challenges.publish
Publish reviewed results and award prizes (V2)
loyalty.validate
Idempotency-Key
BOV2
GET · POST · PATCH · DELETE/admin/loyalty/badges[/{badgeId}]admin.loyalty.badges.crud
Badges (V2)
loyalty.*BOV2
GET/admin/loyalty/referralsadmin.loyalty.referrals.list
Referrals with fraud flags (V2)
loyalty.viewBOV2
POST/admin/loyalty/referrals/{referralId}/decisionadmin.loyalty.referrals.decide
Accept or refuse a flagged referral (V2)
loyalty.validate
Idempotency-Key
BOV2
GET · POST · PATCH · DELETE/admin/loyalty/prize-tables[/{tableId}]admin.loyalty.prizeTables.crud
Chest and wheel prize tables (V2)
loyalty.*BOV2
GET/admin/loyalty/reviewsadmin.loyalty.reviews.list
Reviews to moderate (V2)
loyalty.viewBOV2
POST/admin/loyalty/reviews/{reviewId}/decisionadmin.loyalty.reviews.decide
Accept or refuse a review (V2)
loyalty.validate
Idempotency-Key
BOV2
GET/admin/loyalty/occasionsadmin.loyalty.occasions.list
Declared dates to verify (V2)
loyalty.viewBOV2
POST/admin/loyalty/occasions/{occasionId}/decisionadmin.loyalty.occasions.verify
Verify or refuse a declared date (V2)
loyalty.validate
Idempotency-Key
BOV2

Schemas

Promotion

interface Promotion {
  id: Uuid;
  name: string;                       // internal
  label: string;                      // shown to resellers, ≤ 60: "ACEFAST −10 % novembre"
  description?: string;
  type: PromotionType;                // PERCENT_OFF | AMOUNT_OFF | FIXED_PRICE | FREE_DELIVERY
  value: number | null;               // PERCENT_OFF: bp (1–9000); AMOUNT_OFF: Money HT per unit; FIXED_PRICE: Money HT per unit; FREE_DELIVERY: null
  fixedPrices: { SUPER_GROS: Money; DEMI_GROS: Money; DETAIL: Money } | null;   // FIXED_PRICE with one unit price HT per customer type (contract 1.1.0); null = `value` for every type
  isDailyOffer: boolean;              // shown in the "Offre du jour" carousel with a countdown
  status: PromotionStatus;
  startsAt: Iso; endsAt: Iso;
  scope: { kind: "ALL" | "BRANDS" | "CATEGORIES" | "PRODUCTS" | "VARIANTS"; ids: Uuid[] };   // PromotionScope
  audience: {                         // PromotionAudience; empty = every signed-in reseller
    wilayaCodes: string[]; segmentIds: Uuid[]; customerTypes: CustomerType[]; resellerIds: Uuid[];
    loyaltyLevelIds: Uuid[];          // V2, LoyaltyLevelDefinition (the V1 contract's enum LoyaltyLevel migrates with SRV-45)
  };
  conditions: { minQtyPerLine?: number; minOrderAmountTtc?: Money };   // volume targeting (cahier §4.6 « volume »)
  stockCap?: number;                  // max units sold under the promotion
  perResellerCap?: number;            // max units per reseller
  usedUnits: number;
  priority: number;                   // higher first (STACK_BY_PRIORITY)
  stackable: boolean;
  notifyResellers: boolean;           // promotion.started push at activation
  stats: { orders: number; units: number; discountTotalHt: Money };
  createdBy: UserSummary; createdAt: Iso; updatedAt: Iso; version: number;
}

Banner

interface Banner {
  id: Uuid;
  title: string;                      // internal
  placement: "HOME_HERO" | "HOME_DAILY_OFFER" | "CATALOG_TOP" | "PROMOTIONS_TOP";   // BannerPlacement
  image: FileRef;                     // BANNER_IMAGE, public, 1200 × 500 recommended
  imageMobile?: FileRef;
  link: { kind: "NONE" | "PRODUCT" | "CATEGORY" | "BRAND" | "PROMOTION" | "URL"; targetId?: Uuid; url?: string };   // BannerLinkKind
  audience: Promotion["audience"] & { guests: boolean };   // guests: shown in guest mode (no prices)
  startsAt: Iso; endsAt: Iso;
  status: PromotionStatus;            // same lifecycle as promotions
  countdown: boolean;
  sortOrder: number;
  promotionId?: Uuid;                 // follows the promotion's status when linked
  createdAt: Iso; updatedAt: Iso; version: number;
}

Promotions

GET /admin/promotions

admin.promotions.crud (list) · Permission promotions.view · Apps BO · Release V1 · Requirements PRM-01

Purpose. Lists promotions with status, type, date and target filters.

Request

QueryTypeValues / defaultNotes
statusPromotionStatus[]repeatable
typePromotionType[]repeatable
isDailyOfferboolean
activeOnstring (date)Running that day
brandId / categoryId / productIdUuidScope contains it
segmentId / wilayaCodeUuid / stringAudience contains it
qstringmin 2 charsName, label
sort / order / page / pageSizestartsAt (default), endsAt, priority, name · desc · 1 · 25 (max 200)

Response 200 OK — Page<Promotion>

{
  "items": [
    {
      "id": "01930050-2b3c-7d4e-9f5a-6b7c8d9e0f1a", "name": "ACEFAST novembre", "label": "ACEFAST −10 % novembre",
      "type": "PERCENT_OFF", "value": 1000, "isDailyOffer": false, "status": "ACTIVE",
      "startsAt": "2026-10-31T23:00:00Z", "endsAt": "2026-11-30T22:59:59Z",
      "scope": { "kind": "BRANDS", "ids": ["01928a01-2b3c-7d4e-9f5a-6b7c8d9e0f12"] },
      "audience": { "wilayaCodes": [], "segmentIds": [], "customerTypes": ["DEMI_GROS", "DETAIL"], "resellerIds": [], "loyaltyLevelIds": [] },
      "conditions": { "minQtyPerLine": 5 }, "stockCap": 500, "perResellerCap": 50, "usedUnits": 86,
      "priority": 10, "stackable": false, "notifyResellers": true,
      "stats": { "orders": 14, "units": 86, "discountTotalHt": 1806000 },
      "createdBy": { "id": "01929e55-2c3d-7e4f-9a1b-2c3d4e5f6a7b", "displayName": "Nadia Belkacem" },
      "createdAt": "2026-10-28T10:00:00Z", "updatedAt": "2026-10-31T08:00:00Z", "version": 3
    }
  ],
  "total": 12, "page": 1, "pageSize": 25
}

Errors

StatusCodeWhen
403PERMISSION_DENIEDCaller lacks promotions.view

Rules & side effects

  1. Read-only.

Used by BO-49

GET /admin/promotions/{promotionId}

admin.promotions.crud (get) · Permission promotions.view · Apps BO · Release V1 · Requirements PRM-01

Purpose. One promotion with its stats and the names behind scope and audience ids (scopeItems, audienceItems).

Response 200 OK — a Promotion.

Errors

StatusCodeWhen
404NOT_FOUNDUnknown promotion

Rules & side effects

  1. Read-only.

Used by BO-50

POST /admin/promotions

admin.promotions.crud (create) · Permission promotions.create · Apps BO · Release V1 · Requirements PRM-01 · PRM-02 · PRM-03

Purpose. Creates a promotion in DRAFT.

Request — the Promotion writable fields (name, label, description, type, value, isDailyOffer, startsAt, endsAt, scope, audience, conditions, stockCap, perResellerCap, priority, stackable, notifyResellers):

{
  "name": "Offre du jour câbles", "label": "Câble X14 à 300 DA", "type": "FIXED_PRICE", "value": 30000, "isDailyOffer": true,
  "startsAt": "2026-11-05T07:00:00Z", "endsAt": "2026-11-05T22:59:59Z",
  "scope": { "kind": "VARIANTS", "ids": ["0192b210-5e6f-7a8b-9c0d-1e2f3a4b5c6d"] },
  "audience": { "wilayaCodes": ["31"], "segmentIds": [], "customerTypes": [], "resellerIds": [], "loyaltyLevelIds": [] },
  "conditions": {}, "stockCap": 300, "perResellerCap": 40, "priority": 20, "stackable": false, "notifyResellers": true
}

Response 201 Created — the Promotion (status DRAFT, version 1).

Errors

StatusCodeWhen
400VALIDATION_FAILEDValue invalid for the type (PERCENT_OFF 1–90 %, AMOUNT_OFF positive and below the lowest unit price in scope, FIXED_PRICE positive, FREE_DELIVERY without value), fixedPrices on another type than FIXED_PRICE, endsAt not after startsAt, empty scope ids
403PERMISSION_DENIEDCaller lacks promotions.create
404NOT_FOUNDUnknown id in scope or audience

Rules & side effects

  1. A FIXED_PRICE above a customer-type price never increases the price (the lower price wins, BR-65). Audit CREATE.
  2. Contract 1.1.0 — a FIXED_PRICE may carry fixedPrices: { SUPER_GROS, DEMI_GROS, DETAIL } (all three, each > 0): each customer type gets its own promotional price, and value may then be null. Without fixedPrices, the single value applies to every type, as before. The reseller catalog shows each reseller the price of its own type.
  3. SRV-42 — name (internal) and label (shown to resellers) are stored apart; notifyResellers defaults to false. perResellerCap limits the units one reseller buys under the promotion over its whole life: the cart prices at most the units the reseller has left (the rest at the type price, like the stock cap — BR-67), and checkout consumes them atomically with the stock cap: a limit spent in between answers 409 CART_CHANGED with the re-priced cart. Refused and cancelled orders give the units back. The catalog cards do not check the per-reseller limit; the cart does.

Used by BO-50

PATCH /admin/promotions/{promotionId}

admin.promotions.crud (update) · Permission promotions.update · Apps BO · Release V1 · Requirements PRM-01 · PRM-03

Purpose. Edits a promotion — fully while DRAFT, partially once scheduled or running.

Request — any writable field plus version, e.g. { "endsAt": "2026-12-15T22:59:59Z", "stockCap": 800, "version": 3 }.

Response 200 OK — the updated Promotion.

Errors

StatusCodeWhen
400VALIDATION_FAILEDAs for creation
403PERMISSION_DENIEDCaller lacks promotions.update
404NOT_FOUNDUnknown promotion
409PROMOTION_NOT_EDITABLEField locked for the status — details: { status, lockedFields }: SCHEDULED must go back to DRAFT; ACTIVE/PAUSED only accept a later endsAt, a higher stockCap or perResellerCap, label and description; ENDED/ARCHIVED nothing
409VERSION_CONFLICTStale version

Rules & side effects

  1. Submitted orders keep the promotion they were priced with; carts are re-priced at their next read. Audit UPDATE.

Used by BO-50

DELETE /admin/promotions/{promotionId}

admin.promotions.crud (delete) · Permission promotions.delete · Apps BO · Release V1 · Requirements PRM-01

Purpose. Deletes a promotion still in DRAFT (others are archived).

Response 204 No Content

Errors

StatusCodeWhen
404NOT_FOUNDUnknown promotion
409PROMOTION_NOT_EDITABLENot DRAFT — archive it with setStatus

Rules & side effects

  1. Audit DELETE.

Used by BO-49

POST /admin/promotions/{promotionId}/status

admin.promotions.setStatus · Permission promotions.validate · Apps BO · Release V1 · Requirements PRM-01

Purpose. Schedules, activates now, unschedules, pauses, resumes or archives a promotion.

Request

interface SetPromotionStatusBody { to: "SCHEDULED" | "ACTIVE" | "DRAFT" | "PAUSED" | "ARCHIVED"; version: number }
{ "to": "SCHEDULED", "version": 1 }

Response 200 OK — the Promotion with its new status (ACTIVE directly when to: SCHEDULED and startsAt has passed).

Errors

StatusCodeWhen
403PERMISSION_DENIEDCaller lacks promotions.validate
404NOT_FOUNDUnknown promotion
409PROMOTION_TRANSITION_NOT_ALLOWEDMove not in the table (e.g. ENDED → ACTIVE, resume after endsAt)
422VALIDATION_FAILEDScheduling guards fail (value, dates, empty scope)

Rules & side effects

  1. SCHEDULED → ACTIVE at startsAt and ACTIVE/PAUSED → ENDED at endsAt or when the cap is consumed are automatic (job promotions.applySchedule, every minute); the engine checks dates itself at every pricing.
  2. Audit STATUS_CHANGE.
  3. Notifications: at activation with notifyResellers → promotion.started to the target audience (PROMOTIONAL, opt-outs and quiet hours respected). A daily offer (daily_offer.published) and a flash sale (flash_sale.started) announce themselves whatever the flag.

Used by BO-49 · BO-50

POST /admin/promotions/preview

admin.promotions.preview · Permission promotions.view · Apps BO · Release V1 · Requirements PRM-04

Purpose. Simulates pricing on a sample cart for a given reseller — with a saved promotion or an unsaved draft — and explains eligibility (cahier §5.5 « Une promotion doit respecter ses dates, son stock et sa cible »).

Request

interface PromotionPreviewBody {
  promotionId?: Uuid;                 // or
  draft?: Partial<Promotion>;         // the editor's unsaved values
  resellerId?: Uuid;                  // a reseller, or
  customerType?: CustomerType;        // a customer type outside any reseller; neither = a guest (contract 1.1.0)
  lines: { variantId: Uuid; quantity: number }[];   // 1–50
  at?: Iso;                           // default now
}
{ "promotionId": "01930050-2b3c-7d4e-9f5a-6b7c8d9e0f1a", "resellerId": "0192f4b8-61c2-7a3e-9b10-1f2e3d4c5b6a", "lines": [{ "variantId": "0192b215-7a8b-7c9d-8e0f-1a2b3c4d5e6f", "quantity": 10 }, { "variantId": "0192b210-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "quantity": 20 }] }

Response 200 OK

{
  "reseller": { "id": "0192f4b8-61c2-7a3e-9b10-1f2e3d4c5b6a", "storeName": "Phone Store El Bahia", "customerType": "DEMI_GROS", "wilayaCode": "31" },
  "viewer": { "kind": "RESELLER", "customerType": "DEMI_GROS" },
  "priceLocked": false,
  "eligibility": { "eligible": true, "reasons": [] },
  "lines": [
    { "variantId": "0192b215-7a8b-7c9d-8e0f-1a2b3c4d5e6f", "sku": "AF-A29-50W-WH", "quantity": 10, "basePrice": { "ht": 210000, "ttc": 249900, "vatRate": 1900 }, "applied": [{ "promotionId": "01930050-2b3c-7d4e-9f5a-6b7c8d9e0f1a", "label": "ACEFAST −10 % novembre", "amountHt": 210000 }], "lineTotalHt": 1890000 },
    { "variantId": "0192b210-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "sku": "HC-X14-CC-1M-BK", "quantity": 20, "basePrice": { "ht": 35000, "ttc": 41650, "vatRate": 1900 }, "applied": [], "notApplied": [{ "promotionId": "01930050-2b3c-7d4e-9f5a-6b7c8d9e0f1a", "reason": "OUT_OF_SCOPE" }], "lineTotalHt": 700000 }
  ],
  "totals": { "subtotalHt": 2800000, "discountTotal": 210000, "deliveryFee": 0, "vatTotal": 492100, "totalTtc": 3082100, "currency": "DZD" },
  "capRemaining": { "stockCap": 414, "perReseller": 50 }
}

Field notes. Contract 1.1.0: the preview runs for a reseller (resellerId, reseller present), for a customer type (customerType: its prices, audiences other than customer types are not met) or for a guest (neither: priceLocked: true, amounts at 0, eligibility from dates, audience and scope only). viewer says which. capRemaining.perReseller is what the previewed reseller may still buy under perResellerCap (the limit itself for a customer type or a guest; null without a limit). Ineligibility reasons: NOT_STARTED, ENDED, PAUSED, AUDIENCE_WILAYA, AUDIENCE_SEGMENT, AUDIENCE_CUSTOMER_TYPE, AUDIENCE_RESELLER, OUT_OF_SCOPE, MIN_QTY, MIN_ORDER_AMOUNT, CAP_REACHED, RESELLER_CAP_REACHED, LOST_TO_BETTER_PROMOTION.

Errors

StatusCodeWhen
400VALIDATION_FAILEDNeither or both of promotionId / draft, both resellerId and customerType, empty lines
403PERMISSION_DENIEDCaller lacks promotions.view
404NOT_FOUNDUnknown promotion, reseller or variant
422CUSTOMER_TYPE_REQUIREDThe reseller has no customer type yet

Rules & side effects

  1. Uses the cart pricing engine; writes nothing, consumes no cap.

Used by BO-50

Banners

GET /admin/banners

admin.banners.crud (list) · Permission promotions.view · Apps BO · Release V1 · Requirements PRM-05

Purpose. Lists banners and daily-offer slides by placement.

Request — placement[], status[], activeOn, sort (sortOrder default, startsAt), page / pageSize.

Response 200 OK — Page<Banner>

{
  "items": [
    {
      "id": "01930060-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "title": "Hero ACEFAST GaN", "placement": "HOME_HERO",
      "image": { "id": "01930060-2b3c-7d4e-9f5a-6b7c8d9e0f1a", "url": "https://cdn.hoco.dz/banners/acefast-gan-1200.webp", "mimeType": "image/webp", "size": 142880, "purpose": "BANNER_IMAGE" },
      "link": { "kind": "PROMOTION", "targetId": "01930050-2b3c-7d4e-9f5a-6b7c8d9e0f1a" },
      "audience": { "wilayaCodes": [], "segmentIds": [], "customerTypes": [], "resellerIds": [], "loyaltyLevelIds": [], "guests": true },
      "startsAt": "2026-10-31T23:00:00Z", "endsAt": "2026-11-30T22:59:59Z", "status": "ACTIVE", "countdown": false, "sortOrder": 1,
      "promotionId": "01930050-2b3c-7d4e-9f5a-6b7c8d9e0f1a", "createdAt": "2026-10-30T10:00:00Z", "updatedAt": "2026-10-30T10:00:00Z", "version": 1
    }
  ],
  "total": 5, "page": 1, "pageSize": 25
}

Errors

StatusCodeWhen
403PERMISSION_DENIEDCaller lacks promotions.view

Rules & side effects

  1. Read-only.

Used by BO-51

GET /admin/banners/{bannerId}

admin.banners.crud (get) · Permission promotions.view · Apps BO · Release V1 · Requirements PRM-05

Purpose. One banner. Response 200 OK — a Banner.

Errors

StatusCodeWhen
404NOT_FOUNDUnknown banner

Rules & side effects

  1. Read-only.

Used by BO-51

POST /admin/banners

admin.banners.crud (create) · Permission promotions.create · Apps BO · Release V1 · Requirements PRM-05

Purpose. Creates a banner (image, link target, targeting, schedule, order).

Request

{ "title": "Offre du jour X14", "placement": "HOME_DAILY_OFFER", "imageFileId": "01930061-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "link": { "kind": "PRODUCT", "targetId": "0192b210-4d5e-7f60-8a1b-2c3d4e5f6a70" }, "audience": { "wilayaCodes": ["31"], "guests": false }, "startsAt": "2026-11-05T07:00:00Z", "endsAt": "2026-11-05T22:59:59Z", "countdown": true, "sortOrder": 1, "promotionId": "01930062-3c4d-7e5f-8a6b-7c8d9e0f1a2b" }

Response 201 Created — the Banner (status SCHEDULED when startsAt is in the future, ACTIVE otherwise — banners need no separate activation; DRAFT with "draft": true).

Errors

StatusCodeWhen
400VALIDATION_FAILEDURL link not https, targetId missing for a typed link, endsAt before startsAt
403PERMISSION_DENIEDCaller lacks promotions.create
404NOT_FOUNDUnknown link target or promotion
422FILE_NOT_READY · FILE_PURPOSE_MISMATCHImage not uploaded or not BANNER_IMAGE

Rules & side effects

  1. A banner linked to a promotion is hidden while the promotion is not ACTIVE (BR-68). Audit CREATE.
  2. SRV-42 — every field is stored: imageMobileFileId (BANNER_IMAGE, checked like the image), the full audience (loyalty levels excepted, V2), countdown (default: the linked promotion is a daily offer), and draft: true (status DRAFT, never served to resellers or guests until a PATCH sets ACTIVE or PAUSED). audience.guests defaults to true only for an untargeted banner.

Used by BO-51

PATCH /admin/banners/{bannerId}

admin.banners.crud (update) · Permission promotions.update · Apps BO · Release V1 · Requirements PRM-05

Purpose. Edits, reorders, pauses or archives a banner (status: PAUSED | ACTIVE | ARCHIVED).

Request — partial fields plus version, e.g. { "sortOrder": 2, "version": 1 }.

Response 200 OK — the updated Banner.

Errors

StatusCodeWhen
404NOT_FOUNDUnknown banner
409PROMOTION_TRANSITION_NOT_ALLOWED · VERSION_CONFLICTStatus move not allowed · stale version

Rules & side effects

  1. Audit UPDATE.

Used by BO-51

DELETE /admin/banners/{bannerId}

admin.banners.crud (delete) · Permission promotions.delete · Apps BO · Release V1 · Requirements PRM-05

Purpose. Deletes a banner. Response 204 No Content.

Errors

StatusCodeWhen
404NOT_FOUNDUnknown banner

Rules & side effects

  1. The image file stays 30 days then is purged. Audit DELETE.

Used by BO-51

PUT /admin/banners/order

admin.banners.reorder · Permission promotions.update · Apps BO · Release V1 · Requirements PRM-05 · Added in contract 1.1.0 (SRV-41)

Purpose. Saves the order of a placement's banners in one call (BO-51 drag and drop, or the up / down arrows), instead of one sortOrder edit per banner.

Request

{ "placement": "HOME_CAROUSEL", "ids": ["01930e10-…-c", "01930e10-…-a", "01930e10-…-b"] }

ids lists every non-archived banner of the placement (paused, scheduled and ended included), the first shown first.

Response 200 OK

{ "placement": "HOME_CAROUSEL", "items": [ { "id": "01930e10-…-c", "sortOrder": 10, "version": 1793518200000 }, { "id": "01930e10-…-a", "sortOrder": 20, "version": 1793518200000 }, { "id": "01930e10-…-b", "sortOrder": 30, "version": 1793518200000 } ] }

Errors

StatusCodeWhen
400VALIDATION_FAILEDids misses a banner of the placement, names another one, or repeats one (field ids)
403PERMISSION_DENIEDCaller lacks promotions.update

Rules & side effects

  1. sortOrder becomes 10, 20, 30… in the given order, in one transaction; each moved banner gets an audit UPDATE (sortOrder from → to) and a new version.

Used by BO-51

Packs (V2)

V2

Contract reserved; not built in V1 (cahier §14.2 « packs rentables », PRM-06).

Pack (V2): { id, name, description, image: FileRef, items: [{ variantId, quantity }], price: Price (pack price per customer type: { superGros, demiGros, detail } HT), referenceTotalHt, savingBps, status: PromotionStatus, startsAt, endsAt, audience, stockCap, version }; added to the cart as a unit (cart.packs.add).

GET /admin/packs

admin.packs.crud (list) · Permission promotions.view · Apps BO · Release V2 · Requirements PRM-06

Purpose. Lists packs. Request — status[], q, page / pageSize. Response 200 OK — Page<Pack>.

Errors

StatusCodeWhen
403PERMISSION_DENIEDCaller lacks promotions.view

Rules & side effects

  1. Read-only.

Used by BO-52

GET /admin/packs/{packId}

admin.packs.crud (get) · Permission promotions.view · Apps BO · Release V2 · Requirements PRM-06

Purpose. One pack. Response 200 OK — a Pack.

Errors

StatusCodeWhen
404NOT_FOUNDUnknown pack

Rules & side effects

  1. Read-only.

Used by BO-52

POST /admin/packs

admin.packs.crud (create) · Permission promotions.create · Apps BO · Release V2 · Requirements PRM-06

Purpose. Creates a pack. Request — e.g. { "name": "Pack voiture", "items": [{ "variantId": "0192b21a-9c0d-7e1f-a2b3-4c5d6e7f8a9b", "quantity": 10 }, { "variantId": "0192b210-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "quantity": 20 }], "price": { "superGros": 1050000, "demiGros": 1150000, "detail": 1290000 }, "startsAt": "2027-01-01T00:00:00Z", "endsAt": "2027-01-31T22:59:59Z" }. Response 201 Created — the Pack (DRAFT).

Errors

StatusCodeWhen
400VALIDATION_FAILEDFewer than 2 items, pack price not below the items' total
403PERMISSION_DENIEDCaller lacks promotions.create

Rules & side effects

  1. Audit CREATE.

Used by BO-52

PATCH /admin/packs/{packId}

admin.packs.crud (update) · Permission promotions.update · Apps BO · Release V2 · Requirements PRM-06

Purpose. Edits a pack (same locking rules as promotions). Response 200 OK — the Pack.

Errors

StatusCodeWhen
409PROMOTION_NOT_EDITABLE · VERSION_CONFLICTLocked field · stale version

Rules & side effects

  1. Audit UPDATE.

Used by BO-52

DELETE /admin/packs/{packId}

admin.packs.crud (delete) · Permission promotions.delete · Apps BO · Release V2 · Requirements PRM-06

Purpose. Deletes a draft pack. Response 204 No Content.

Errors

StatusCodeWhen
409PROMOTION_NOT_EDITABLENot DRAFT

Rules & side effects

  1. Audit DELETE.

Used by BO-52

Loyalty (V2)

V2

Contract reserved; not built in V1 (cahier §4.6, §14.2 « Fidélité avancée »). Rules: BR-40 to BR-44 and BR-87 to BR-106.

GET /admin/loyalty/settings

admin.loyalty.settings (get) · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-01 · LOY-02 · LOY-23

Purpose. Programme switches, earning trigger, expiry and regularisation. Rules and levels have their own operations (admin.loyalty.rules.crud, admin.loyalty.levels.crud).

Response 200 OK

{ "enabled": false, "earnOn": "DELIVERED", "pointsPerAmount": { "amount": 10000, "points": 1 }, "excludedCategoryIds": [], "pointsValidityMonths": 12, "levelPeriodMode": "ROLLING_MONTHS", "levelPeriodMonths": 12, "regularisationMode": "ALLOW_NEGATIVE", "features": { "cashback": false, "missions": false, "challenges": false, "referral": false, "badges": false, "chest": false, "wheel": false }, "version": 1 }

Errors

StatusCodeWhen
403PERMISSION_DENIEDCaller lacks loyalty.view

Rules & side effects

  1. Read-only; values mirror the loyalty.* settings of the catalogue.

Used by BO-53

PUT /admin/loyalty/settings

admin.loyalty.settings (update) · Permission loyalty.administer · Apps BO · Release V2 · Requirements LOY-01 · LOY-02 · LOY-23

Purpose. Replaces the programme settings (same shape as the read, with version and a reason).

Response 200 OK — the stored settings.

Errors

StatusCodeWhen
400VALIDATION_FAILEDRatio ≤ 0, value out of range
403PERMISSION_DENIEDCaller lacks loyalty.administer
409VERSION_CONFLICTStale version

Rules & side effects

  1. Apply to operations from now on; a change to past operations goes through admin.loyalty.recalculations. Audit UPDATE per changed key.

Used by BO-53

POST /admin/loyalty/accounts/{resellerId}/adjustments

admin.loyalty.adjust · Permission loyalty.update · Apps BO · Release V2 · Requirements LOY-02

Purpose. Manual points adjustment with a reason (cahier §4.6 « ajustements »).

Request — { "points": -150, "reason": "Points d'une commande retournée non annulés automatiquement." } (points ≠ 0).

Response 201 Created — { "transaction": { "id": "…", "type": "ADJUST", "points": -150, "reason": "…", "at": "2027-02-03T09:00:00Z" }, "balance": 2310 }

Errors

StatusCodeWhen
403PERMISSION_DENIEDCaller lacks loyalty.update
404NOT_FOUNDUnknown reseller
409LOYALTY_DISABLEDProgramme disabled
422INSUFFICIENT_POINTS · REASON_REQUIREDBalance would become negative through a manual debit · empty reason

Rules & side effects

  1. Appends a LoyaltyTransaction ADJUST; audit UPDATE with the reason.

Used by BO-83 · BO-11

GET /admin/rewards

admin.rewards.crud (list) · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-04

Purpose. The rewards catalogue: Reward { id, name, type: RewardType, pointsCost, value?: Money, stock?, minLevelId?: Uuid, conditions?, deliveryMethod?, validityDays, active, image?, version }. Response 200 OK — Page<Reward>.

Errors

StatusCodeWhen
403PERMISSION_DENIEDCaller lacks loyalty.view

Rules & side effects

  1. Read-only.

Used by BO-54

GET /admin/rewards/{rewardId}

admin.rewards.crud (get) · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-04

Purpose. One reward. Response 200 OK — a Reward.

Errors

StatusCodeWhen
404NOT_FOUNDUnknown reward

Rules & side effects

  1. Read-only.

Used by BO-54

POST /admin/rewards

admin.rewards.crud (create) · Permission loyalty.create · Apps BO · Release V2 · Requirements LOY-04

Purpose. Adds a reward. Request — e.g. { "name": "Bon d'achat 2 000 DA", "type": "VOUCHER", "pointsCost": 2000, "value": 200000, "validityDays": 60, "stock": 100 }. Response 201 Created — the Reward.

Errors

StatusCodeWhen
400VALIDATION_FAILEDvalue missing for VOUCHER / DISCOUNT, cost ≤ 0

Rules & side effects

  1. Audit CREATE.

Used by BO-54

PATCH /admin/rewards/{rewardId}

admin.rewards.crud (update) · Permission loyalty.update · Apps BO · Release V2 · Requirements LOY-04

Purpose. Edits or deactivates a reward. Response 200 OK — the Reward.

Errors

StatusCodeWhen
409VERSION_CONFLICTStale version

Rules & side effects

  1. Unavailable rewards cannot be redeemed (cahier §5.5). Audit UPDATE.

Used by BO-54

DELETE /admin/rewards/{rewardId}

admin.rewards.crud (delete) · Permission loyalty.delete · Apps BO · Release V2 · Requirements LOY-04

Purpose. Deletes a never-redeemed reward. Response 204 No Content.

Errors

StatusCodeWhen
409RESOURCE_IN_USEAlready redeemed — deactivate it

Rules & side effects

  1. Audit DELETE.

Used by BO-54

GET /admin/redemptions

admin.redemptions.list (list) · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-04

Purpose. Redemptions to fulfil (RedemptionStatus PENDING, FULFILLED, CANCELLED). Request — status[], rewardType[], resellerId, page / pageSize. Response 200 OK — Page<{ id, reseller, reward, points, status, requestedAt, fulfilledAt?, voucherCode? }>.

Errors

StatusCodeWhen
403PERMISSION_DENIEDCaller lacks loyalty.view

Rules & side effects

  1. Read-only (reading relaxed from the bundle's loyalty.update — Assumption).

Used by BO-54

POST /admin/redemptions/{redemptionId}/fulfil

admin.redemptions.list (fulfil) · Permission loyalty.update · Apps BO · Release V2 · Requirements LOY-04

Purpose. Marks a redemption fulfilled (gift handed over, early access granted). Request — { "note": "Remis par le délégué le 3 février." }. Response 200 OK — the redemption with status FULFILLED.

Errors

StatusCodeWhen
404NOT_FOUNDUnknown redemption
409REDEMPTION_NOT_PENDINGNot PENDING

Rules & side effects

  1. Audit STATUS_CHANGE; reseller notified (in-app).

Used by BO-54

POST /admin/redemptions/{redemptionId}/cancel

admin.redemptions.list (cancel) · Permission loyalty.update · Apps BO · Release V2 · Requirements LOY-04

Purpose. Cancels a PENDING redemption, or one whose vouchers are all unused: the points come back as a REVERSAL (LOY-04 rule 6). Request — { "reason": "Rupture de stock du cadeau." }. Response 200 OK — the redemption with status CANCELLED.

Errors — 404 NOT_FOUND, 409 REDEMPTION_NOT_PENDING (a voucher used or expired, a gift already handed over), 422 REASON_REQUIRED.

Full programme (change request 04)

Not yet accepted or priced by HOCO

The operations below come from HOCO's loyalty document and the letter of 6 November 2026. They enter the contract with SRV-43. Every change writes an AuditLog row.

GET /admin/loyalty/dashboard

admin.loyalty.dashboard · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-24

Purpose. Indicators of LOY-24. Query: from, to, wilayaCode, customerType, levelId.

Response 200 OK — { enrolled, perLevel[], points { earned, used, expired }, cashback { earned, used }, topRewards[], topResellers[], missions, challenges, estimatedCost, usageRateBp, levelMoves { up, down }, computedAt }.

Errors — 403 PERMISSION_DENIED.

Used by BO-82

GET /admin/loyalty/accounts

admin.loyalty.accounts.list · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-23

Purpose. Finds a reseller's account. Query: q, levelId, page, pageSize, sort, order.

Response 200 OK — Page<LoyaltyAccountRow>.

Errors — 403 PERMISSION_DENIED.

Used by BO-83

GET /admin/loyalty/accounts/{resellerId}

admin.loyalty.accounts.get · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-23

Purpose. Level, qualified purchases, points, cashback, rewards and progress.

Response 200 OK — { reseller, level, qualifiedAmount, qualifiedOrders, points, cashback, rewards[], objective, levelHistory[] }.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND.

Used by BO-83 · BO-11

GET /admin/loyalty/accounts/{resellerId}/history

admin.loyalty.accounts.history · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-22 · LOY-11

Purpose. As loyalty.history, with the actor, the reason, the rule version and the steps of each calculation.

Response 200 OK — Page<LoyaltyHistoryRow>.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND.

Used by BO-83

POST /admin/loyalty/accounts/{resellerId}/cashback-adjustments

admin.loyalty.cashback.adjust · Permission loyalty.update · Apps BO · Release V2 · Requirements LOY-14 · LOY-23 · Idempotency-Key required

Purpose. { "amount": -50000, "reason": "…" } (amount ≠ 0, centimes).

Response 201 Created — the CashbackTransaction and the balance.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND, 422 REASON_REQUIRED.

Rules & side effects — Appends ADJUST, audit UPDATE (BR-105).

Used by BO-83

POST /admin/loyalty/accounts/{resellerId}/qualified-purchase-adjustments

admin.loyalty.purchases.adjust · Permission loyalty.update · Apps BO · Release V2 · Requirements LOY-23 · Idempotency-Key required

Purpose. Corrects the qualified amount or order count.

Response 201 Created — the QualifiedPurchaseEntry; the level is computed again.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND, 422 REASON_REQUIRED.

Rules & side effects — Appends ADJUSTMENT, audit UPDATE (BR-105).

Used by BO-83

GET · POST · PATCH · DELETE /admin/loyalty/rules[/{ruleId}]

admin.loyalty.rules.crud · Permission loyalty.* · Apps BO · Release V2 · Requirements LOY-08 · LOY-09 · LOY-12 · LOY-14 · LOY-16 · LOY-23

Purpose. LoyaltyRule { id, kind, name, scope, basis, value, config, status, startsAt, endsAt, version }. PATCH needs changeScope (RuleChangeScope) and version. DELETE applies to drafts; a used rule is archived. changeScope: "RECALCULATE" keeps the new version; past orders change only through a recalculation.

Response 200 OK or 201 Created — the rule.

Errors — 403 PERMISSION_DENIED, 400 VALIDATION_FAILED, 409 VERSION_CONFLICT.

Rules & side effects — Each save writes a LoyaltyRuleVersion; audit per change (LOY-25).

Used by BO-72

POST /admin/loyalty/rules/{ruleId}/status

admin.loyalty.rules.setStatus · Permission loyalty.administer · Apps BO · Release V2 · Requirements LOY-08 · LOY-23

Purpose. { "status": "ACTIVE", "version": 3 }.

Response 200 OK — the rule.

Errors — 403 PERMISSION_DENIED, 409 VERSION_CONFLICT, 422 LOYALTY_RULE_INVALID, 422 PROGRAMME_REVIEW_REQUIRED.

Rules & side effects — PROGRAMME_REVIEW_REQUIRED blocks the switches of D-60 and D-61 until the settings loyalty.cashback.reviewCleared and loyalty.prizes.reviewCleared are set.

Used by BO-72

GET /admin/loyalty/rules/{ruleId}/versions

admin.loyalty.rules.versions · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-25

Purpose. Who changed what, when, and the change scope.

Response 200 OK — Page<LoyaltyRuleVersion>.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND.

Used by BO-75

POST /admin/loyalty/simulate

admin.loyalty.simulate · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-08 · LOY-11 · LOY-26

Purpose. { "resellerId": "…", "lines": [{ "variantId": "…", "qty": 10 }], "at": "2027-05-14T10:00:00Z" }.

Response 200 OK — base points per line, each step, total, cashback, applied rule versions.

Errors — 403 PERMISSION_DENIED, 400 VALIDATION_FAILED.

Rules & side effects — Writes nothing.

Used by BO-72

GET · POST /admin/loyalty/recalculations[/{recalculationId}]

admin.loyalty.recalculations · Permission loyalty.validate · Apps BO · Release V2 · Requirements LOY-25 · Idempotency-Key required

Purpose. POST with { "ruleVersionId": "…", "from": "2027-01-01", "to": "2027-03-31", "mode": "PREVIEW" }, then { "mode": "RUN", "recalculationId": "…" } on a previewed recalculation.

Response 202 Accepted — LoyaltyRecalculation with status; GET gives the impact.

Errors — 403 PERMISSION_DENIED, 409 RECALCULATION_RUNNING, 409 RECALCULATION_NOT_PREVIEWED.

Rules & side effects — Runs in the cron queue; appends RECALCULATION entries; never edits history (BR-104).

Used by BO-75

POST /admin/loyalty/accounts/{resellerId}/level

admin.loyalty.setLevel · Permission loyalty.update · Apps BO · Release V2 · Requirements LOY-23 · Idempotency-Key required

Purpose. Manual level change of BR-105. Request — { "levelId": "…", "reason": "Client stratégique" }. Response 201 Created — the new level and changeId.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND, 422 REASON_REQUIRED.

Rules & side effects — Writes a LoyaltyLevelChange of type MANUAL with its author and reason, and an audit entry.

GET · POST · PATCH · DELETE /admin/loyalty/levels[/{levelId}]

admin.loyalty.levels.crud · Permission loyalty.* · Apps BO · Release V2 · Requirements LOY-03 · LOY-20 · LOY-23

Purpose. LoyaltyLevelDefinition { id, code, name, rank, minAmount, minOrders, pointsBonusBp, benefits, retention, active, version }.

Response 200 OK or 201 Created — the level.

Errors — 403 PERMISSION_DENIED, 400 VALIDATION_FAILED (thresholds not ascending), 409 LEVEL_IN_USE, 409 VERSION_CONFLICT.

Rules & side effects — Standard cannot be deleted or disabled; a level with resellers needs a target level.

Used by BO-73

GET · POST · PATCH · DELETE /admin/loyalty/campaigns[/{campaignId}]

admin.loyalty.campaigns.crud · Permission loyalty.* · Apps BO · Release V2 · Requirements LOY-09 · LOY-10 · LOY-11 · LOY-13

Purpose. LoyaltyCampaign { id, kind, name, startsAt, endsAt, recurrence, scope, levelIds, multiplierBp, bonusPoints, stacking, priority, maxBeneficiaries, status, version }.

Response 200 OK or 201 Created — the campaign.

Errors — 403 PERMISSION_DENIED, 400 VALIDATION_FAILED, 409 VERSION_CONFLICT.

Used by BO-74

GET /admin/loyalty/campaigns/{campaignId}/beneficiaries

admin.loyalty.campaigns.beneficiaries · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-13

Purpose. The places of a first-N campaign in order: rank, reseller, order, date, and releasedAt for a place given back. Response 200 OK — offset page.

Used by BO-74

POST /admin/loyalty/campaigns/{campaignId}/status

admin.loyalty.campaigns.setStatus · Permission loyalty.administer · Apps BO · Release V2 · Requirements LOY-10

Purpose. { "status": "PAUSED", "version": 2 }.

Response 200 OK — the campaign.

Errors — 403 PERMISSION_DENIED, 409 VERSION_CONFLICT.

Used by BO-74

GET · POST · PATCH · DELETE /admin/loyalty/missions[/{missionId}]

admin.loyalty.missions.crud · Permission loyalty.* · Apps BO · Release V2 · Requirements LOY-06

Purpose. Mission { id, name, description, cadence, condition, params, reward, repeatable, audience, startsAt, endsAt, status, version }.

Response 200 OK or 201 Created — the mission.

Errors — 403 PERMISSION_DENIED, 400 VALIDATION_FAILED, 409 VERSION_CONFLICT.

Used by BO-76

GET · POST · PATCH · DELETE /admin/loyalty/challenges[/{challengeId}]

admin.loyalty.challenges.crud · Permission loyalty.* · Apps BO · Release V2 · Requirements LOY-07

Purpose. Challenge { id, name, criterion, weights, topN, prizes[], startsAt, endsAt, status, version }; GET by id includes the results.

Response 200 OK or 201 Created — the challenge.

Errors — 403 PERMISSION_DENIED, 400 VALIDATION_FAILED, 409 VERSION_CONFLICT.

Used by BO-77

POST /admin/loyalty/challenges/{challengeId}/publish

admin.loyalty.challenges.publish · Permission loyalty.validate · Apps BO · Release V2 · Requirements LOY-07 · Idempotency-Key required

Purpose. { "excluded": [{ "resellerId": "…", "reason": "…" }] }.

Response 200 OK — the published results.

Errors — 403 PERMISSION_DENIED, 409 CHALLENGE_NOT_CLOSED.

Rules & side effects — Prizes are awarded once; emits leaderboard.published.

Used by BO-77

GET · POST · PATCH · DELETE /admin/loyalty/badges[/{badgeId}]

admin.loyalty.badges.crud · Permission loyalty.* · Apps BO · Release V2 · Requirements LOY-17

Purpose. Badge { id, name, image, condition, validity, validityDays, displayed, benefit, active, version }.

Response 200 OK or 201 Created — the badge.

Errors — 403 PERMISSION_DENIED, 400 VALIDATION_FAILED, 409 VERSION_CONFLICT.

Used by BO-78

GET /admin/loyalty/referrals

admin.loyalty.referrals.list · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-15

Purpose. Query: status, flagged, page, pageSize.

Response 200 OK — Page<ReferralRow>.

Errors — 403 PERMISSION_DENIED.

Used by BO-79

POST /admin/loyalty/referrals/{referralId}/decision

admin.loyalty.referrals.decide · Permission loyalty.validate · Apps BO · Release V2 · Requirements LOY-15 · Idempotency-Key required

Purpose. { "decision": "REFUSED", "reason": "…" }.

Response 200 OK — the referral.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND, 409 REFERRAL_ALREADY_DECIDED, 422 REASON_REQUIRED.

Used by BO-79

GET · POST · PATCH · DELETE /admin/loyalty/prize-tables[/{tableId}]

admin.loyalty.prizeTables.crud · Permission loyalty.* · Apps BO · Release V2 · Requirements LOY-18 · LOY-19

Purpose. PrizeTable { id, kind, name, condition, maxPerReseller, validityDays, budget, entries[{ type, value, oddsBp, stock }], status, version }; GET by id includes the results.

Response 200 OK or 201 Created — the table.

Errors — 403 PERMISSION_DENIED, 400 VALIDATION_FAILED, 409 VERSION_CONFLICT, 422 PRIZE_ODDS_INVALID, 422 PROGRAMME_REVIEW_REQUIRED.

Used by BO-80

POST /admin/loyalty/prize-entitlements/{entitlementId}/fulfil

admin.loyalty.prizeTables.fulfil · Permission loyalty.update · Apps BO · Release V2 · Requirements LOY-18, LOY-19 · Idempotency-Key required

Purpose. Records that a physical prize won at the chest or wheel was handed over (fulfilledAt). Response 200 OK.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND.

GET /admin/loyalty/reviews

admin.loyalty.reviews.list · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-12

Purpose. Query: status, page, pageSize.

Response 200 OK — Page<ReviewRow>.

Errors — 403 PERMISSION_DENIED.

Used by BO-81

POST /admin/loyalty/reviews/{reviewId}/decision

admin.loyalty.reviews.decide · Permission loyalty.validate · Apps BO · Release V2 · Requirements LOY-12 · Idempotency-Key required

Purpose. { "decision": "ACCEPTED" } or { "decision": "REJECTED", "reason": "…" }.

Response 200 OK — the review.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND, 409 REVIEW_ALREADY_DECIDED.

Rules & side effects — Acceptance pays the REVIEW_BONUS once.

Used by BO-81

GET /admin/loyalty/occasions

admin.loyalty.occasions.list · Permission loyalty.view · Apps BO · Release V2 · Requirements LOY-16

Purpose. Query: status, type, page, pageSize.

Response 200 OK — Page<OccasionDateRow>.

Errors — 403 PERMISSION_DENIED.

Used by BO-81

POST /admin/loyalty/occasions/{occasionId}/decision

admin.loyalty.occasions.verify · Permission loyalty.validate · Apps BO · Release V2 · Requirements LOY-16 · Idempotency-Key required

Purpose. { "status": "VERIFIED" } or { "status": "REJECTED", "reason": "…" }.

Response 200 OK — the date.

Errors — 403 PERMISSION_DENIED, 404 NOT_FOUND.

Rules & side effects — Audited.

Used by BO-81

DES-02 additions (back-office redesign)

Additive fields and operations read by the redesigned promotion screens (BO-49 to BO-51):

  • Promotion — statusReason (why it was paused or ended early, « En pause : … ») and stats.revenueHt (net HT of the order lines priced with it).
  • admin.promotions.setStatus — to: "ENDED" (« Terminer maintenant ») from SCHEDULED, ACTIVE or PAUSED: endsAt moves to now (a never-started promotion keeps a one-second window); carts recalculate, submitted orders keep their discount. Optional reason (3–300) is kept with PAUSED and ENDED and cleared by the other moves; it is in the audit diff.
  • Banner — clicks and lastClickedAt, counted by banners.click.

GET /admin/promotions/{promotionId}/history

admin.promotions.history · Permission promotions.view · Apps BO · Release V1 · Requirements PRM-01

Purpose. The « Historique » card: creation, edits and status changes, read from the audit log, newest first (50). DES-02.

Response 200 OK — { items: [{ id, at, action, summary, actor, from?, to?, reason? }] }.

POST /admin/promotions/overlaps

admin.promotions.overlaps · Permission promotions.view · Apps BO · Release V1 · Requirements PRM-01

Purpose. The overlap notices of the detail and the editor: draft, scheduled, active and paused promotions whose scope shares a variant with scope and whose dates cross [startsAt, endsAt). Writes nothing. DES-02.

Request { promotionId?, startsAt, endsAt, scope } (promotionId is left out of the answer). Response 200 OK — { items: [{ id, name, type, status, stackable, startsAt, endsAt }] }. Errors 400 VALIDATION_FAILED (endsAt before startsAt).

On this page

SchemasPromotionBannerPromotionsGET /admin/promotionsGET /admin/promotions/{promotionId}POST /admin/promotionsPATCH /admin/promotions/{promotionId}DELETE /admin/promotions/{promotionId}POST /admin/promotions/{promotionId}/statusPOST /admin/promotions/previewBannersGET /admin/bannersGET /admin/banners/{bannerId}POST /admin/bannersPATCH /admin/banners/{bannerId}DELETE /admin/banners/{bannerId}PUT /admin/banners/orderPacks (V2)GET /admin/packsGET /admin/packs/{packId}POST /admin/packsPATCH /admin/packs/{packId}DELETE /admin/packs/{packId}Loyalty (V2)GET /admin/loyalty/settingsPUT /admin/loyalty/settingsPOST /admin/loyalty/accounts/{resellerId}/adjustmentsGET /admin/rewardsGET /admin/rewards/{rewardId}POST /admin/rewardsPATCH /admin/rewards/{rewardId}DELETE /admin/rewards/{rewardId}GET /admin/redemptionsPOST /admin/redemptions/{redemptionId}/fulfilPOST /admin/redemptions/{redemptionId}/cancelFull programme (change request 04)GET /admin/loyalty/dashboardGET /admin/loyalty/accountsGET /admin/loyalty/accounts/{resellerId}GET /admin/loyalty/accounts/{resellerId}/historyPOST /admin/loyalty/accounts/{resellerId}/cashback-adjustmentsPOST /admin/loyalty/accounts/{resellerId}/qualified-purchase-adjustmentsGET · POST · PATCH · DELETE /admin/loyalty/rules[/{ruleId}]POST /admin/loyalty/rules/{ruleId}/statusGET /admin/loyalty/rules/{ruleId}/versionsPOST /admin/loyalty/simulateGET · POST /admin/loyalty/recalculations[/{recalculationId}]POST /admin/loyalty/accounts/{resellerId}/levelGET · POST · PATCH · DELETE /admin/loyalty/levels[/{levelId}]GET · POST · PATCH · DELETE /admin/loyalty/campaigns[/{campaignId}]GET /admin/loyalty/campaigns/{campaignId}/beneficiariesPOST /admin/loyalty/campaigns/{campaignId}/statusGET · POST · PATCH · DELETE /admin/loyalty/missions[/{missionId}]GET · POST · PATCH · DELETE /admin/loyalty/challenges[/{challengeId}]POST /admin/loyalty/challenges/{challengeId}/publishGET · POST · PATCH · DELETE /admin/loyalty/badges[/{badgeId}]GET /admin/loyalty/referralsPOST /admin/loyalty/referrals/{referralId}/decisionGET · POST · PATCH · DELETE /admin/loyalty/prize-tables[/{tableId}]POST /admin/loyalty/prize-entitlements/{entitlementId}/fulfilGET /admin/loyalty/reviewsPOST /admin/loyalty/reviews/{reviewId}/decisionGET /admin/loyalty/occasionsPOST /admin/loyalty/occasions/{occasionId}/decisionDES-02 additions (back-office redesign)GET /admin/promotions/{promotionId}/historyPOST /admin/promotions/overlaps