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.
| Permission | Unlocks on this page |
|---|---|
promotions.view | Promotions, banners, packs (read), preview |
promotions.create · promotions.update · promotions.delete | Create · edit · delete drafts |
promotions.validate | Schedule, activate, pause, archive |
loyalty.view · loyalty.create · loyalty.update · loyalty.delete · loyalty.validate · loyalty.administer | V2 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.
| Method | Path | Operation | Access | Apps | Release |
|---|---|---|---|---|---|
| GET · POST · PATCH · DELETE | /admin/promotions[/{promotionId}] | admin.promotions.crudPromotions (type, value, scope, targeting, schedule, cap, stacking) | promotions.* | BO | V1 |
| POST | /admin/promotions/{promotionId}/status | admin.promotions.setStatusSchedule, activate, pause, end now, archive | promotions.validate | BO | V1 |
| GET | /admin/promotions/{promotionId}/history | admin.promotions.historyCreation, edits and status changes of a promotion | promotions.view | BO | V1 |
| POST | /admin/promotions/overlaps | admin.promotions.overlapsPromotions that cover the same products during the same dates | promotions.view | BO | V1 |
| POST | /admin/promotions/preview | admin.promotions.previewSimulate a promotion on a sample cart and reseller | promotions.view | BO | V1 |
| GET · POST · PATCH · DELETE | /admin/banners[/{bannerId}] | admin.banners.crudBanners and daily offers | promotions.* | BO | V1 |
| PUT | /admin/banners/order | admin.banners.reorderReorder the banners of a placement in one call | promotions.update | BO | V1 |
| GET · POST · PATCH · DELETE | /admin/packs[/{packId}] | admin.packs.crudPacks (V2) | promotions.* | BO | V2 |
| GET · PUT | /admin/loyalty/settings | admin.loyalty.settingsProgramme switches, earning trigger, expiry, regularisation (V2) | loyalty.administer | BO | V2 |
| POST | /admin/loyalty/accounts/{resellerId}/adjustments | admin.loyalty.adjustManual points adjustment with reason (V2) | loyalty.update | BO | V2 |
| POST | /admin/loyalty/accounts/{resellerId}/level | admin.loyalty.setLevelManual level change with reason (V2) | loyalty.update | BO | V2 |
| POST | /admin/loyalty/prize-entitlements/{entitlementId}/fulfil | admin.loyalty.prizeTables.fulfilRecord a physical prize as handed over (V2) | loyalty.update | BO | V2 |
| GET | /admin/loyalty/campaigns/{campaignId}/beneficiaries | admin.loyalty.campaigns.beneficiariesPlaces of a first-N campaign, in order (V2) | loyalty.view | BO | V2 |
| GET · POST · PATCH · DELETE | /admin/rewards[/{rewardId}] | admin.rewards.crudRewards catalogue (V2) | loyalty.* | BO | V2 |
| GET · POST | /admin/redemptions[/{redemptionId}/fulfil] | admin.redemptions.listRedemptions to fulfil (V2) | loyalty.update | BO | V2 |
| POST | /admin/redemptions/{redemptionId}/cancel | admin.redemptions.cancelCancel a pending redemption or an unused voucher (V2) | loyalty.update | BO | V2 |
| GET | /admin/loyalty/dashboard | admin.loyalty.dashboardProgramme dashboard indicators (V2) | loyalty.view | BO | V2 |
| GET | /admin/loyalty/accounts | admin.loyalty.accounts.listSearch loyalty accounts (V2) | loyalty.view | BO | V2 |
| GET | /admin/loyalty/accounts/{resellerId} | admin.loyalty.accounts.getOne reseller's loyalty account (V2) | loyalty.view | BO | V2 |
| GET | /admin/loyalty/accounts/{resellerId}/history | admin.loyalty.accounts.historyCombined history with actors and calculation steps (V2) | loyalty.view | BO | V2 |
| POST | /admin/loyalty/accounts/{resellerId}/cashback-adjustments | admin.loyalty.cashback.adjustManual cashback adjustment with reason (V2) | loyalty.updateIdempotency-Key | BO | V2 |
| POST | /admin/loyalty/accounts/{resellerId}/qualified-purchase-adjustments | admin.loyalty.purchases.adjustManual qualified-purchase adjustment with reason (V2) | loyalty.updateIdempotency-Key | BO | V2 |
| GET · POST · PATCH · DELETE | /admin/loyalty/rules[/{ruleId}] | admin.loyalty.rules.crudEarning, bonus, cashback and birthday rules (V2) | loyalty.* | BO | V2 |
| POST | /admin/loyalty/rules/{ruleId}/status | admin.loyalty.rules.setStatusEnable, schedule, pause or end a rule (V2) | loyalty.administer | BO | V2 |
| GET | /admin/loyalty/rules/{ruleId}/versions | admin.loyalty.rules.versionsVersions of a rule (V2) | loyalty.view | BO | V2 |
| POST | /admin/loyalty/simulate | admin.loyalty.simulateTest the rules on a sample order, no ledger entry (V2) | loyalty.view | BO | V2 |
| GET · POST | /admin/loyalty/recalculations[/{recalculationId}] | admin.loyalty.recalculationsPreview and run a recalculation (V2) | loyalty.validateIdempotency-Key | BO | V2 |
| GET · POST · PATCH · DELETE | /admin/loyalty/levels[/{levelId}] | admin.loyalty.levels.crudConfigured levels (V2) | loyalty.* | BO | V2 |
| GET · POST · PATCH · DELETE | /admin/loyalty/campaigns[/{campaignId}] | admin.loyalty.campaigns.crudOccasions, Happy Days, selected products, new-product campaigns (V2) | loyalty.* | BO | V2 |
| POST | /admin/loyalty/campaigns/{campaignId}/status | admin.loyalty.campaigns.setStatusSchedule, activate, pause or end a campaign (V2) | loyalty.administer | BO | V2 |
| GET · POST · PATCH · DELETE | /admin/loyalty/missions[/{missionId}] | admin.loyalty.missions.crudMissions (V2) | loyalty.* | BO | V2 |
| GET · POST · PATCH · DELETE | /admin/loyalty/challenges[/{challengeId}] | admin.loyalty.challenges.crudMonthly challenges (V2) | loyalty.* | BO | V2 |
| POST | /admin/loyalty/challenges/{challengeId}/publish | admin.loyalty.challenges.publishPublish reviewed results and award prizes (V2) | loyalty.validateIdempotency-Key | BO | V2 |
| GET · POST · PATCH · DELETE | /admin/loyalty/badges[/{badgeId}] | admin.loyalty.badges.crudBadges (V2) | loyalty.* | BO | V2 |
| GET | /admin/loyalty/referrals | admin.loyalty.referrals.listReferrals with fraud flags (V2) | loyalty.view | BO | V2 |
| POST | /admin/loyalty/referrals/{referralId}/decision | admin.loyalty.referrals.decideAccept or refuse a flagged referral (V2) | loyalty.validateIdempotency-Key | BO | V2 |
| GET · POST · PATCH · DELETE | /admin/loyalty/prize-tables[/{tableId}] | admin.loyalty.prizeTables.crudChest and wheel prize tables (V2) | loyalty.* | BO | V2 |
| GET | /admin/loyalty/reviews | admin.loyalty.reviews.listReviews to moderate (V2) | loyalty.view | BO | V2 |
| POST | /admin/loyalty/reviews/{reviewId}/decision | admin.loyalty.reviews.decideAccept or refuse a review (V2) | loyalty.validateIdempotency-Key | BO | V2 |
| GET | /admin/loyalty/occasions | admin.loyalty.occasions.listDeclared dates to verify (V2) | loyalty.view | BO | V2 |
| POST | /admin/loyalty/occasions/{occasionId}/decision | admin.loyalty.occasions.verifyVerify or refuse a declared date (V2) | loyalty.validateIdempotency-Key | BO | V2 |
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
| Query | Type | Values / default | Notes |
|---|---|---|---|
status | PromotionStatus[] | repeatable | |
type | PromotionType[] | repeatable | |
isDailyOffer | boolean | ||
activeOn | string (date) | Running that day | |
brandId / categoryId / productId | Uuid | Scope contains it | |
segmentId / wilayaCode | Uuid / string | Audience contains it | |
q | string | min 2 chars | Name, label |
sort / order / page / pageSize | startsAt (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
| Status | Code | When |
|---|---|---|
| 403 | PERMISSION_DENIED | Caller lacks promotions.view |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | Unknown promotion |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | Value 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 |
| 403 | PERMISSION_DENIED | Caller lacks promotions.create |
| 404 | NOT_FOUND | Unknown id in scope or audience |
Rules & side effects
- A
FIXED_PRICEabove a customer-type price never increases the price (the lower price wins, BR-65). AuditCREATE. - Contract 1.1.0 — a
FIXED_PRICEmay carryfixedPrices: { SUPER_GROS, DEMI_GROS, DETAIL }(all three, each > 0): each customer type gets its own promotional price, andvaluemay then benull. WithoutfixedPrices, the singlevalueapplies to every type, as before. The reseller catalog shows each reseller the price of its own type. - SRV-42 —
name(internal) andlabel(shown to resellers) are stored apart;notifyResellersdefaults tofalse.perResellerCaplimits 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 answers409 CART_CHANGEDwith 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
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | As for creation |
| 403 | PERMISSION_DENIED | Caller lacks promotions.update |
| 404 | NOT_FOUND | Unknown promotion |
| 409 | PROMOTION_NOT_EDITABLE | Field 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 |
| 409 | VERSION_CONFLICT | Stale version |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | Unknown promotion |
| 409 | PROMOTION_NOT_EDITABLE | Not DRAFT — archive it with setStatus |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 403 | PERMISSION_DENIED | Caller lacks promotions.validate |
| 404 | NOT_FOUND | Unknown promotion |
| 409 | PROMOTION_TRANSITION_NOT_ALLOWED | Move not in the table (e.g. ENDED → ACTIVE, resume after endsAt) |
| 422 | VALIDATION_FAILED | Scheduling guards fail (value, dates, empty scope) |
Rules & side effects
SCHEDULED→ACTIVEatstartsAtandACTIVE/PAUSED→ENDEDatendsAtor when the cap is consumed are automatic (jobpromotions.applySchedule, every minute); the engine checks dates itself at every pricing.- Audit
STATUS_CHANGE. - Notifications: at activation with
notifyResellers→promotion.startedto 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.
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
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | Neither or both of promotionId / draft, both resellerId and customerType, empty lines |
| 403 | PERMISSION_DENIED | Caller lacks promotions.view |
| 404 | NOT_FOUND | Unknown promotion, reseller or variant |
| 422 | CUSTOMER_TYPE_REQUIRED | The reseller has no customer type yet |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 403 | PERMISSION_DENIED | Caller lacks promotions.view |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | Unknown banner |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | URL link not https, targetId missing for a typed link, endsAt before startsAt |
| 403 | PERMISSION_DENIED | Caller lacks promotions.create |
| 404 | NOT_FOUND | Unknown link target or promotion |
| 422 | FILE_NOT_READY · FILE_PURPOSE_MISMATCH | Image not uploaded or not BANNER_IMAGE |
Rules & side effects
- A banner linked to a promotion is hidden while the promotion is not
ACTIVE(BR-68). AuditCREATE. - SRV-42 — every field is stored:
imageMobileFileId(BANNER_IMAGE, checked like the image), the fullaudience(loyalty levels excepted, V2),countdown(default: the linked promotion is a daily offer), anddraft: true(statusDRAFT, never served to resellers or guests until aPATCHsetsACTIVEorPAUSED).audience.guestsdefaults totrueonly 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | Unknown banner |
| 409 | PROMOTION_TRANSITION_NOT_ALLOWED · VERSION_CONFLICT | Status move not allowed · stale version |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | Unknown banner |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | ids misses a banner of the placement, names another one, or repeats one (field ids) |
| 403 | PERMISSION_DENIED | Caller lacks promotions.update |
Rules & side effects
sortOrderbecomes 10, 20, 30… in the given order, in one transaction; each moved banner gets an auditUPDATE(sortOrderfrom → to) and a newversion.
Used by BO-51
Packs (V2)
V2
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
| Status | Code | When |
|---|---|---|
| 403 | PERMISSION_DENIED | Caller lacks promotions.view |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | Unknown pack |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | Fewer than 2 items, pack price not below the items' total |
| 403 | PERMISSION_DENIED | Caller lacks promotions.create |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 409 | PROMOTION_NOT_EDITABLE · VERSION_CONFLICT | Locked field · stale version |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 409 | PROMOTION_NOT_EDITABLE | Not DRAFT |
Rules & side effects
- Audit
DELETE.
Used by BO-52
Loyalty (V2)
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
| Status | Code | When |
|---|---|---|
| 403 | PERMISSION_DENIED | Caller lacks loyalty.view |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | Ratio ≤ 0, value out of range |
| 403 | PERMISSION_DENIED | Caller lacks loyalty.administer |
| 409 | VERSION_CONFLICT | Stale version |
Rules & side effects
- Apply to operations from now on; a change to past operations goes through
admin.loyalty.recalculations. AuditUPDATEper 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
| Status | Code | When |
|---|---|---|
| 403 | PERMISSION_DENIED | Caller lacks loyalty.update |
| 404 | NOT_FOUND | Unknown reseller |
| 409 | LOYALTY_DISABLED | Programme disabled |
| 422 | INSUFFICIENT_POINTS · REASON_REQUIRED | Balance would become negative through a manual debit · empty reason |
Rules & side effects
- Appends a
LoyaltyTransactionADJUST; auditUPDATEwith the reason.
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
| Status | Code | When |
|---|---|---|
| 403 | PERMISSION_DENIED | Caller lacks loyalty.view |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | Unknown reward |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | value missing for VOUCHER / DISCOUNT, cost ≤ 0 |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 409 | VERSION_CONFLICT | Stale version |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 409 | RESOURCE_IN_USE | Already redeemed — deactivate it |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 403 | PERMISSION_DENIED | Caller lacks loyalty.view |
Rules & side effects
- 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | Unknown redemption |
| 409 | REDEMPTION_NOT_PENDING | Not PENDING |
Rules & side effects
- 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
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.
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 : … ») andstats.revenueHt(net HT of the order lines priced with it).admin.promotions.setStatus—to: "ENDED"(« Terminer maintenant ») fromSCHEDULED,ACTIVEorPAUSED:endsAtmoves to now (a never-started promotion keeps a one-second window); carts recalculate, submitted orders keep their discount. Optionalreason(3–300) is kept withPAUSEDandENDEDand cleared by the other moves; it is in the auditdiff.Banner—clicksandlastClickedAt, counted bybanners.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).
Finance
Back-office finance operations — invoices and their cancellation, payments recorded or declared and their verification, allocations, credit accounts with exposure and limit history, and the V2 overdue and accounting exports.
Field operations
Back-office field operations — delegates, zones, objectives, tour planning and live follow-up, visits and their unlocking, visit types, checklist templates and the invitation funnel.