JikoXpress Pro — Offer Engine Architecture

Version 3.0 | May 2026 | QBIT SPARK CO LIMITED
Full offer engine design — psychology, architecture, user journeys, UI flows, and competitive positioning.
Updated: Three discount layers defined. Menu discount as Layer 1. Offer governance and loss prevention added. Implementation prerequisites defined — offer engine builds only after core order flow is stable.
No code. No schema. Pure design thinking. 
 
 
 Table of Contents 
 
 Why Offers Win or Kill a Platform 
 The Psychology Behind Offers 
 The Three Offer Worlds 
 The Three Discount Layers — The Full Picture 
 Phase Strategy — What We Build Now vs Later 
 The Coupon Engine — Phase 1 Architecture 
 Offer Types — Deep Dive 
 The Rule Engine 
 Coupon Scope — What a Coupon Can Target 
 Delivery Configuration vs Offers 
 Offer Governance & Loss Prevention 
 Referral System — Built on Coupon Engine 
 B2B — Kitchen Subscription Offers 
 Notification & Preference System 
 User Journeys — All Levels 
 UI Ideas & Flow Concepts 
 Where JikoXpress Wins 
 Financial Impact of Offers 
 Entity Overview 
 Implementation Prerequisites 
 Decision Log 
 
 
 1. Why Offers Win or Kill a Platform 
 Jumia failed in food not because of bad tech — they failed because customers had no reason to stay loyal. An offer engine done wrong either burns money with zero return, or is so stingy users ignore it entirely. JikoXpress needs to get this exactly right. 
 The three ways platforms lose with offers: 
 TOO GENEROUS → burns budget, users only order when there's a deal, unsustainable
TOO STINGY → users don't feel valued, go to competitor
TOO COMPLEX → users don't understand the deal, ignore it entirely
 
 The winning formula: 
 RIGHT OFFER → RIGHT PERSON → RIGHT TIME → IRRESISTIBLE
 
 This document designs exactly that — starting with the simplest, most powerful tool: the coupon code. 
 
 2. The Psychology Behind Offers 
 Understanding why humans respond to offers is the foundation of the entire engine. Every offer type maps to a specific psychological trigger. 
 2.1 Loss Aversion — The Most Powerful Trigger 
 
 Humans feel the pain of losing TZS 2,000 more than the pleasure of gaining TZS 2,000. 
 
 How JikoXpress uses it: 
 
 "Your coupon expires tonight" → time pressure creates urgency 
 "You have TZS 1,500 in your wallet — don't let it go to waste" → loss framing 
 Showing crossed-out delivery fee → TZS 1,500 → FREE 
 
 2.2 Reciprocity — I Got Something, Now I Owe You 
 
 When someone gives us something, we feel compelled to give back. 
 
 How JikoXpress uses it: 
 
 Referral coupon gives new user free delivery → they feel obligated to complete the order 
 Kitchen gives free item coupon → customer feels loyalty to that kitchen 
 First order deal → customer feels obligated to return 
 
 2.3 Social Proof — Others Are Doing It 
 
 Humans look at what others do to decide what to do. 
 
 How JikoXpress uses it: 
 
 "127 people used this coupon today" on the offer card 
 Referral system shows friend already uses the platform 
 
 2.4 Scarcity — Limited Makes It Valuable 
 
 We want what is running out. 
 
 How JikoXpress uses it: 
 
 "Only 14 redemptions left for this coupon" 
 "This kitchen's lunch special ends at 2pm" 
 Coupon with totalUseLimit shows remaining count 
 
 2.5 Identity & Reward — I Earned This 
 
 We value things more when we feel we worked for them or were specially chosen. 
 
 How JikoXpress uses it: 
 
 Birthday coupon — platform "remembered" you, feels personal 
 Referral reward — you helped a friend, you get rewarded 
 Kitchen coupon on flyer — feels exclusive, like insider access 
 
 2.6 Anchoring — The Original Price Matters 
 
 Humans judge value based on the first number they see. 
 
 How JikoXpress uses it: 
 
 Always show original price crossed out → TZS 8,000 → TZS 6,000 
 Show "You saved TZS 2,000" at order confirmation 
 Delivery fee shown then zeroed → feels better than just "Free delivery" 
 
 
 3. The Four Offer Worlds 
 JikoXpress operates four completely separate offer worlds. Each has different actors, different funding, different purpose, and different implementation timing. Understanding these worlds is the foundation of the entire offer system. 
 ┌─────────────────────────────────────────────────────────────────┐
│ WORLD 1: MENU ITEM OFFER │
│ │
│ Actor → Kitchen Owner (menu management) │
│ Funded by → Kitchen (absorbed in their margin) │
│ Purpose → Permanent or semi-permanent price reduction │
│ on a specific menu item │
│ Trigger → None — always active while item is active │
│ Code → No code needed │
│ Channels → ALL channels, always, no restriction │
│ Phase 1 → ✅ BUILD NOW (part of menu management) │
│ Examples → Pilau TZS ~~8,000~~ → TZS 7,500 │
│ Juice TZS ~~3,000~~ → TZS 2,500 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ WORLD 2: KITCHEN COUPON │
│ │
│ Actor → Kitchen Owner (offer dashboard) │
│ Funded by → Kitchen (deducted from their settlement) │
│ Purpose → Time-limited promotions to attract customers, │
│ boost slow hours, push specific items │
│ Trigger → Customer enters code at checkout │
│ Code → Yes — e.g. MAMA20, FRIDAY10, OPENDAY │
│ Channels → All channels (configurable per coupon) │
│ Phase 1 → ✅ BUILD NOW (after core order flow stable) │
│ Examples → 15% off this weekend, free delivery Friday, │
│ TZS 1,000 off orders above TZS 8,000 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ WORLD 3: PLATFORM COUPON │
│ │
│ Actor → JikoXpress Admin │
│ Funded by → Platform (marketing cost, EXPENSE_OFFER_SUBSIDY) │
│ Purpose → Customer acquisition, retention, market growth │
│ Trigger → Customer enters code at checkout │
│ Code → Yes — e.g. JIKO20, WELCOME50, FREESHIP │
│ Also: system-generated referral codes (REF-*) │
│ Channels → All channels (configurable per coupon) │
│ Phase 1 → ✅ BUILD NOW (after core order flow stable) │
│ Examples → 20% off first order, free delivery new users, │
│ referral reward coupons │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ WORLD 4: AUTO / MANUAL PLATFORM OFFERS │
│ │
│ Actor → JikoXpress Admin (defines rules) │
│ System (fires automatically based on triggers) │
│ Funded by → Platform │
│ Purpose → Targeted offers fired by system events or │
│ scheduled by admin — no code needed by customer │
│ Trigger → System event (birthday, first session, schedule) │
│ OR admin manually pushes to eligible users │
│ Code → No — applies transparently at checkout │
│ Channels → All channels │
│ Phase 1 → ⏳ NOT YET — Phase 2 only │
│ Examples → Free delivery this whole week (manual, admin │
│ sets it and it runs for all orders) │
│ Birthday offer — 30% off on user's birthday │
│ Welcome offer — free delivery first order ever │
│ Happy hour — 15% off between 3pm–5pm daily │
│ B2B trial — PROFESSIONAL plan free 30 days │
└─────────────────────────────────────────────────────────────────┘
 
 Critical rule: These four worlds never mix financially. Each has its own cost center, its own accounting entry, its own audit trail. A kitchen coupon cost never touches the platform marketing budget. A platform coupon never reduces what a kitchen earns. 
 How the Four Worlds Relate to the Three Discount Layers 
 Layer 1 (menu discount) ←→ World 1 (menu item offer)
Layer 2 (coupon code) ←→ World 2 + World 3 (kitchen + platform coupons)
Layer 3 (auto-offer) ←→ World 4 (auto / manual platform offers)
 
 Same concept, two views. The layers describe the checkout calculation sequence. The worlds describe who owns and funds each type of offer. 
 
 4. The Three Discount Layers — The Full Picture 
 This is the most important framing in the entire document. JikoXpress has three completely separate discount layers . They are independent, they serve different purposes, and they must never be confused with each other — not in design, not in code, not in financial accounting. 
 ┌─────────────────────────────────────────────────────────────────────────┐
│ LAYER 1 — MENU ITEM DISCOUNT │
│ │
│ What it is: A price reduction set directly on a menu item │
│ Who sets it: Kitchen owner (in menu management) │
│ How: Fixed amount off OR percent off the base price │
│ Trigger: None — always active while item is active │
│ Channels: ALL channels (App, WhatsApp, Counter, Kiosk) │
│ Lifespan: No expiry — kitchen edits manually to change │
│ Budget: None — kitchen accepts the reduced earnings │
│ Code needed: No │
│ Financial: Changes the item's selling price │
│ Baked into the order subtotal before anything else │
│ │
│ Example: │
│ Pilau base price: TZS 8,000 │
│ Menu discount: TZS 500 (fixed) │
│ Selling price: TZS 7,500 ← this is now THE price │
│ Shown as: TZS ~~8,000~~ → TZS 7,500 on all channels │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│ LAYER 2 — COUPON CODE │
│ │
│ What it is: A promotional code applied at checkout │
│ Who sets it: Admin (platform coupon) or Kitchen owner (kitchen coupon)│
│ How: Customer enters a code at checkout │
│ Trigger: Customer action — manual code entry │
│ Channels: All channels (can be restricted per coupon config) │
│ Lifespan: Defined startDate → endDate, auto-expires │
│ Budget: Hard cap — auto-deactivates when exhausted │
│ Code needed: Yes — e.g. JIKO20, MAMA15, REF-GRACE7X │
│ Financial: Applied on top of already-discounted subtotal (Layer 1) │
│ Platform coupon → platform absorbs cost │
│ Kitchen coupon → deducted from kitchen settlement │
│ │
│ Example: │
│ Order subtotal (after menu discounts): TZS 15,000 │
│ Coupon JIKO20 (20% off): - TZS 3,000 │
│ Customer pays: TZS 12,000 │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│ LAYER 3 — PLATFORM AUTO-OFFER (Phase 2 only) │
│ │
│ What it is: An offer applied automatically by the system │
│ Who sets it: Admin defines rules, system fires automatically │
│ How: System checks eligibility on every checkout │
│ Trigger: System — based on user profile, order history, date │
│ Channels: All or specific channels │
│ Lifespan: Defined, auto-expires │
│ Budget: Hard cap │
│ Code needed: No — transparent to customer, just applies │
│ Financial: Applied after Layer 1 and Layer 2 │
│ Platform always absorbs cost │
│ │
│ Examples: │
│ Birthday offer — 30% off on user's birthday, auto-applied │
│ Welcome offer — free delivery on first order, auto-applied │
│ ⚠ NOT BUILT IN PHASE 1 │
└─────────────────────────────────────────────────────────────────────────┘
 
 
 4.1 How the Three Layers Interact at Checkout 
 The layers are resolved in strict order. Each layer is independent — a change in one does not affect the others. 
 CHECKOUT CALCULATION SEQUENCE
══════════════════════════════════════════════════════

Step 1 — LAYER 1: Apply menu item discounts
 For each item in cart:
 selling price = base price - menu discount (if any)
 Order subtotal = sum of all selling prices

 ···············································
 Result: discounted subtotal
 e.g. TZS 15,000 (already reflects item discounts)
 ···············································

Step 2 — Calculate delivery fee
 From kitchen distance tiers or flat fee
 e.g. TZS 1,500

Step 3 — Kitchen delivery subsidy active?
 YES → delivery fee = 0, kitchen billed at settlement
 NO → delivery fee stays

Step 4 — LAYER 2: Customer entered a coupon?
 YES → validate coupon → apply on discounted subtotal
 NO → skip
 ···············································
 Result: coupon discount deducted
 e.g. JIKO20 20% off TZS 15,000 = - TZS 3,000
 New total: TZS 12,000
 ···············································

Step 5 — LAYER 3: Platform auto-offer eligible? (Phase 2)
 YES → apply platform offer
 NO → skip

Step 6 — Final total shown to customer
 Subtotal (after layer 1): TZS 15,000
 Coupon JIKO20 (layer 2): - TZS 3,000
 Delivery: TZS 1,500
 ─────────────────────────────────────────
 You pay: TZS 13,500
 Savings shown: TZS 3,500 (item discounts + coupon)
 
 
 4.2 The Clean Separation Rule 
 Layer 1 (menu discount)
 → Is a PRICE. Not a promotion. Not tracked as offer usage.
 → No budget. No rules. No code. No audit trail as offer.
 → Kitchen absorbs it silently in their margin.

Layer 2 (coupon)
 → Is a PROMOTION. Tracked. Has budget. Has rules. Has audit trail.
 → Goes through the full coupon engine.
 → Creates CouponRedemptionEntity, updates budgetUsed, perUserCount.

Layer 3 (auto-offer, phase 2)
 → Is a PLATFORM PROMOTION. System-triggered.
 → Full audit trail. Platform absorbs cost.
 → Only applies if no coupon was entered (coupon wins).
 
 
 4.3 Channel Behaviour Per Layer 
 App WhatsApp Counter Kiosk
 ─── ──────── ─────── ─────
Layer 1 (menu) ✅ ✅ ✅ ✅ always, no config
Layer 2 (coupon) ✅ ✅ ✅ ✅ configurable per coupon
Layer 3 (auto) ✅ ✅ ✅ ✅ phase 2
 
 Menu discounts are never channel-restricted. A price is a price everywhere.
Coupons can optionally be restricted — but default is all channels. 
 
 5. Phase Strategy — What We Build Now vs Later 
 This is the most important section for implementation planning. 
 Why Coupons First is the Right Decision 
 Auto-applied offers require: Coupons require:
 → User profiling → User enters a code
 → Order history queries at checkout → System validates
 → Real-time eligibility on every session → Done
 → Complex targeting logic
 → Easy to get wrong silently
 
 Coupons give you 80% of the value at 20% of the complexity. More importantly — coupons give you market feedback before you build more. You learn which offer types actually drive orders in Tanzania before over-engineering. 
 Phase 1 — Build Now 
 ✅ Coupon engine
 Admin creates platform coupons
 Kitchen owner creates kitchen coupons
 Full rule engine behind every coupon
 Full scope targeting (whole kitchen, menu item, delivery)
 All channels (App, WhatsApp, Counter, Kiosk)

✅ Referral system
 Built on top of coupon engine
 System generates unique referral coupon per user
 Referrer reward via wallet credit after referee completes first order

✅ B2B subscription offers
 Manual — admin grants trial or discount via subscription admin panel
 No separate offer engine needed
 Subscription system handles it directly
 
 Phase 2 — After Real User Data 
 ⏳ Auto-applied offers
 Birthday offers (daily scheduled job)
 Welcome offer for new users (auto-apply on first checkout)
 New user window offers

⏳ Automated B2B offer engine
 System detects kitchen growth signals
 Auto-triggers trial offer
 Tracks acceptance and conversion

⏳ Advanced offer types
 Flash sales with countdown
 Happy hour triggers
 Community offers
 
 The Key Mindset 
 Phase 1 coupon engine is NOT a simplified version.
It IS the full engine — rules, scope, budget, limits, all of it.
The only thing missing is the auto-apply trigger.
When Phase 2 comes → you add AUTO_APPLIED redemption type
and write the trigger logic. The engine itself doesn't change.
 
 
 5. The Coupon Engine — Phase 1 Architecture 
 5.1 The Full Flow 
 COUPON CREATED (Admin or Kitchen Owner)
 Code set (e.g. JIKO20)
 Offer type set (FREE_DELIVERY, PERCENT_DISCOUNT, etc.)
 Scope set (whole kitchen, menu item, delivery only)
 Rules attached (first order, min amount, time window, etc.)
 Budget + limits set
 Lifespan set (startDate → endDate)
 │
 ▼
COUPON ACTIVE
 Discoverable in kitchen deal badges (if kitchen coupon)
 Shareable by admin via WhatsApp / SMS / social
 Printable by kitchen on physical flyers
 │
 ▼
CUSTOMER ENTERS CODE AT CHECKOUT
 │
 ▼
VALIDATION LAYER (atomic — no side effects yet)
 ├── Does this code exist?
 ├── Is the coupon ACTIVE?
 ├── Is the channel eligible?
 ├── Does the order scope match? (right kitchen? right item?)
 ├── Does customer pass ALL rules?
 ├── Is totalBudget remaining?
 ├── Has user hit perUserLimit?
 ├── Is dailyUseLimit still available?
 │
 ├── ANY FAIL → clear error shown, no money moved
 │
 └── ALL PASS →
 │
 ▼
 SLOT LOCKED (prevents race condition on last redemption)
 │
 ▼
 DISCOUNT COMPUTED + SHOWN TO CUSTOMER
 │
 ▼
 PAYMENT PROCESSED
 │
 ├── PAYMENT SUCCESS →
 │ CouponRedemptionEntity created
 │ CouponUsageEntity updated (perUser count)
 │ budgetUsed updated
 │ totalUsed updated
 │ Auto-deactivate check (budget or limit exhausted?)
 │
 └── PAYMENT FAILED →
 Slot released
 Coupon still available
 Customer can retry
 
 5.2 Validation is Atomic 
 Validation happens before payment. If validation fails, nothing has happened — no money, no records, no side effects. This is non-negotiable. 
 5.3 One Coupon Per Order — Phase 1 
 One coupon code per order. No stacking. Ever. Phase 1. 
 This is a deliberate decision, not a limitation. Here is the full reasoning: 
 Financial clarity:
 One coupon → discount calculation is clean and predictable
 Two coupons → edge cases multiply:
 Do they stack on original price or already-discounted price?
 What if one is platform-funded and one is kitchen-funded?
 What if FREE_DELIVERY + PERCENT_DISCOUNT both apply?
 → Financial math becomes ambiguous fast

Abuse prevention:
 User finds two 20% off coupons → stacks them → 40% off
 Platform or kitchen bleeds money on one order
 One coupon → cost is controlled and predictable

Market learning:
 You don't yet know which coupon types resonate in Tanzania
 Run one coupon per order → collect data → understand behavior
 Then decide if stacking makes sense and for which combinations
 
 The rule at checkout: 
 Customer enters first code → validated and applied, shown in summary
Customer enters second code → first code is REPLACED by second
 customer sees new discount
 only the last entered code applies at payment
Customer removes code → order returns to full price
 
 Last code entered wins. Customer can change their mind freely — but only one applies when they place the order. 
 Phase 2 — Controlled Stacking (when data justifies it): 
 One platform coupon + one kitchen coupon → potentially allowed (different funders)
Two platform coupons → never allowed
Two kitchen coupons → never allowed
FREE_DELIVERY + PERCENT_DISCOUNT → potentially allowed (different targets)
Two PERCENT_DISCOUNT coupons → never allowed
 
 This is future thinking only. Build it when kitchens are running coupons constantly and users are actively requesting it. 
 5.4 Validation Response — Always Specific 
 ✅ VALID → show discount amount, "JIKO20 applied ✓"
❌ NOT_FOUND → "This code doesn't exist"
❌ EXPIRED → "This offer has ended"
❌ NOT_YET_ACTIVE → "This offer starts on [date]"
❌ ALREADY_USED → "You've already used this code"
❌ LIMIT_REACHED → "This offer is fully redeemed"
❌ BUDGET_EXHAUSTED→ "This offer is no longer available"
❌ WRONG_KITCHEN → "This code is only valid at [Kitchen Name]"
❌ WRONG_ITEM → "This code only applies to [Item Name]"
❌ MIN_NOT_MET → "Minimum order TZS [X] required"
❌ WRONG_DAY → "This offer is only valid on [days]"
❌ WRONG_TIME → "This offer is only valid between [time] – [time]"
❌ NOT_FIRST_ORDER → "This offer is for first-time orders only"
❌ NOT_NEW_USER → "This offer is for new users only"
❌ WRONG_CHANNEL → "This code is not valid on this channel"
 
 Never a vague "invalid code." Always tell the user exactly why. This is UX that builds trust. 
 
 6. Offer Types — Deep Dive 
 6.1 FREE_DELIVERY 
 Customer pays zero delivery fee. The delivery cost is absorbed by whoever owns the coupon. 
 Platform coupon → platform pays rider from treasury (EXPENSE_OFFER_SUBSIDY)
Kitchen coupon → deducted from kitchen earnings at settlement
 
 This is different from: 
 
 Kitchen self-delivery setting → kitchen uses own riders, JikoXpress not involved (not a coupon) 
 Kitchen delivery subsidy setting → standing "cover all delivery this week" config (not a coupon) 
 
 FREE_DELIVERY coupon is promotional — has rules, budget, lifespan, code. Always goes through the coupon engine. 
 Psychology: #1 checkout abandonment reason is delivery fee. Removing it with a code converts hesitant users instantly. 
 
 6.2 PERCENT_DISCOUNT 
 X% off the order subtotal. Optional maximum cap. 
 Example: 20% off, max TZS 5,000
Order TZS 12,000 → discount TZS 2,400 (20%) → customer pays TZS 9,600
Order TZS 30,000 → discount capped at TZS 5,000 → customer pays TZS 25,000
 
 Almost always paired with MIN_ORDER_AMOUNT rule to protect margin. 
 Psychology: Anchoring. Customer calculates savings themselves, feels smart. 
 
 6.3 FIXED_DISCOUNT 
 Flat TZS amount off. Simpler to market than percent. 
 Example: TZS 2,000 off orders above TZS 8,000
"TZS 2,000 OFF" on a banner → more readable than "20% off up to TZS 5,000"
 
 Psychology: Simplicity. Customer knows exactly what they save before doing math. 
 
 6.4 FREE_ITEM 
 A specific menu item is free on this order. 
 Coupon: FREEJUICE
Offer: Get one Mango Juice free with any main course
Scope: SPECIFIC_MENU_ITEM (menuItemId = juice item)
Rule: MIN_ORDER_AMOUNT = 8,000 (must order a main course worth this)
 
 Kitchen use case — push a new menu item by making it free for first 100 orders. Sampling strategy that works in physical markets too (print flyers, drive digital orders). 
 Psychology: Reciprocity. Free gift creates obligation to order again. 
 
 7. The Rule Engine 
 Every coupon can have multiple eligibility rules. All rules must pass (AND logic) for the coupon to apply. Rules are stored as separate records linked to the coupon — new rule types can be added in future without changing the coupon structure. 
 7.1 Phase 1 Rules 
 ┌──────────────────────────────┬──────────────────────────────────────────────┐
│ Rule Type │ What It Checks │
├──────────────────────────────┼──────────────────────────────────────────────┤
│ FIRST_ORDER │ User has zero completed orders ever │
│ FIRST_ORDER_AT_KITCHEN │ User has zero completed orders at this │
│ │ specific kitchen │
│ MIN_ORDER_AMOUNT │ Order subtotal >= configured amount (TZS) │
│ NEW_USER_DAYS │ User registered within last N days │
│ VALID_TIME_WINDOW │ Current time is between start and end time │
│ VALID_DAYS_OF_WEEK │ Today is one of the configured days │
│ MAX_USES_PER_USER │ User redemption count < configured limit │
│ ELIGIBLE_CHANNEL │ Order channel is in the allowed list │
└──────────────────────────────┴──────────────────────────────────────────────┘
 
 7.2 How Rules Compose — Real Examples 
 "Welcome coupon — new user, first order ever"
 FIRST_ORDER
 NEW_USER_DAYS = 7

"Lunch special — weekdays only, 12pm–2pm, above TZS 10,000"
 VALID_DAYS_OF_WEEK = [MON, TUE, WED, THU, FRI]
 VALID_TIME_WINDOW = 12:00 – 14:00
 MIN_ORDER_AMOUNT = 10,000

"New customer promo — first time at this kitchen, above TZS 8,000, weekend"
 FIRST_ORDER_AT_KITCHEN
 MIN_ORDER_AMOUNT = 8,000
 VALID_DAYS_OF_WEEK = [FRI, SAT]

"Simple discount — no restrictions, anyone, any time"
 (no rules attached — just budget and lifespan limits)
 
 7.3 Future Rule Types — Phase 2 
 MIN_ORDERS_COMPLETED → "Must have ordered at least 5 times total"
REFERRED_USER → "Must have come via a referral link"
BIRTHDAY_MONTH → "User's birthday is this month"
SPECIFIC_PAYMENT_METHOD → "Must pay via mobile money"
REPEAT_CUSTOMER → "Has ordered from this kitchen before"
 
 Adding a new rule = new enum value + new validation handler. Zero schema changes. 
 
 8. Coupon Scope — What a Coupon Can Target 
 Every coupon has a scope that defines which orders and items it applies to. 
 ┌─────────────────────┬───────────────────────────────────────────────────┐
│ Scope │ Meaning │
├─────────────────────┼───────────────────────────────────────────────────┤
│ ALL_KITCHENS │ Platform coupon — works at any kitchen │
│ SPECIFIC_KITCHEN │ Only at one named kitchen │
│ WHOLE_KITCHEN │ Any item from this kitchen qualifies │
│ SPECIFIC_MENU_ITEM │ Only this specific item gets the discount │
│ DELIVERY_ONLY │ Only the delivery fee is affected │
│ │ Food price unchanged │
└─────────────────────┴───────────────────────────────────────────────────┘
 
 Scope + Offer Type Combinations 
 DELIVERY_ONLY + FREE_DELIVERY → classic free shipping coupon
SPECIFIC_MENU_ITEM + FREE_ITEM → free specific item
WHOLE_KITCHEN + PERCENT_DISCOUNT → % off everything at this kitchen
ALL_KITCHENS + FIXED_DISCOUNT → TZS X off any order anywhere
SPECIFIC_KITCHEN + FREE_DELIVERY → partnership deal with one kitchen
 
 
 10. Delivery Configuration vs Offers 
 This is the most important separation in the delivery + offer system. Three things look similar on the surface but are fundamentally different systems. 
 ┌───────────────────────────┬─────────────────────────────────────────────┐
│ Concept │ What It Is │
├───────────────────────────┼─────────────────────────────────────────────┤
│ Kitchen Self-Delivery │ Kitchen uses own riders. │
│ (KitchenDeliveryConfig) │ JikoXpress NOT involved at all. │
│ │ NOT a coupon. NOT financial. │
│ │ Just a capability flag. │
├───────────────────────────┼─────────────────────────────────────────────┤
│ Kitchen Delivery Subsidy │ "I cover all delivery fees this week." │
│ (KitchenDeliverySubsidy) │ JikoXpress still dispatches riders. │
│ │ NOT a coupon. Standing config with │
│ │ lifespan. No code. No rules. │
├───────────────────────────┼─────────────────────────────────────────────┤
│ FREE_DELIVERY Coupon │ Promotional. Has code, rules, budget, │
│ (CouponEntity) │ lifespan. Platform or kitchen funded. │
│ │ Goes through full coupon engine. │
└───────────────────────────┴─────────────────────────────────────────────┘
 
 Distance-Based Delivery Pricing 
 Kitchen can configure delivery fee by distance — this is kitchen config, not a coupon: 
 Kitchen X delivery tiers:
 0 – 2 km → Free delivery
 2 – 5 km → TZS 1,000
 5 – 10 km → TZS 2,500
 Above 10km → Not deliverable
 
 Priority Chain at Delivery Checkout 
 When a customer places a delivery order, system resolves in this exact order: 
 Step 1: Does kitchen handle own delivery?
 YES → customer uses kitchen's own system, JikoXpress out entirely
 NO → continue

Step 2: Is customer within kitchen's max delivery radius?
 NO → reject (cannot deliver to this location)
 YES → continue

Step 3: Calculate base delivery fee from distance tiers (or flat fee)

Step 4: Is there an active Kitchen Delivery Subsidy for this order?
 YES → fee = 0, kitchen billed at settlement
 NO → continue

Step 5: Did customer enter a FREE_DELIVERY coupon that passed validation?
 YES → fee = 0, coupon owner (platform or kitchen) absorbs cost
 NO → continue

Step 6: Customer pays the calculated delivery fee
 
 
 
 11. Offer Governance & Loss Prevention 
 This section exists because offers, done without controls, will bleed money silently. Every control here is deliberate — designed to prevent the three failure modes: overspending, abuse, and accidental duplication. 
 11.1 Who Can Trigger What — Strict Lane Separation 
 ┌─────────────────────┬──────────────────────────────────────────────────┐
│ Actor │ What They Can Create / Trigger │
├─────────────────────┼──────────────────────────────────────────────────┤
│ JikoXpress Admin │ Platform coupons (any type, any kitchen scope) │
│ │ Platform free delivery offers │
│ │ Referral reward configuration │
│ │ B2B subscription trials (manual) │
├─────────────────────┼──────────────────────────────────────────────────┤
│ Kitchen Owner │ Kitchen coupons (their kitchen only) │
│ │ Menu item discounts (their items only) │
│ │ Kitchen delivery subsidy (their orders only) │
├─────────────────────┼──────────────────────────────────────────────────┤
│ System (automated) │ Referral coupon generation (on user request) │
│ │ Auto-deactivation when budget/limit exhausted │
│ │ Auto-expiry at endDate │
│ │ Phase 2 only: auto-offer triggering │
└─────────────────────┴──────────────────────────────────────────────────┘
 
 Nobody crosses their lane. Admin cannot touch kitchen pricing. Kitchen cannot touch platform offers. System only does what it is explicitly programmed to do. 
 
 11.2 The Six Hard Controls 
 These controls are non-negotiable. Every coupon must have all applicable controls set before it can go active. 
 Control 1 — Hard Budget Cap 
 Every coupon must have a totalBudget set.
When budgetUsed reaches totalBudget → coupon auto-deactivates immediately.
No human intervention needed. No override possible.
No open-ended "unlimited budget" coupons allowed in the system.

Platform coupon budget = marketing cost line (admin accountable)
Kitchen coupon budget = kitchen's own money (they feel the pain directly)
 
 Control 2 — Hard Time Boundary 
 Every coupon must have startDate and endDate.
System auto-expires at endDate — midnight, no exceptions.
No open-ended coupons. No "runs until we decide to stop it."
Admin must set an end date before publishing.
 
 Control 3 — Per-User Limit 
 perUserLimit prevents one person from emptying the budget alone.
Default: 1 use per user unless explicitly set higher.
System checks CouponUsageEntity before every redemption.
 
 Control 4 — Daily Redemption Limit 
 dailyUseLimit = max redemptions across all users per day.
Even if budget remains, daily cap protects against day-1 rush abuse.
Spreads the cost over the full lifespan rather than burning in hours.
 
 Control 5 — Total Redemption Limit 
 totalUseLimit = max redemptions ever, regardless of budget.
Useful for "first 100 customers only" style campaigns.
Whichever hits first (budget or redemption limit) auto-deactivates.
 
 Control 6 — Duplicate Offer Warning 
 When admin creates a new coupon, system checks:
 Is there already an ACTIVE coupon of the same type
 covering the same scope?

 Example: FREE_DELIVERY coupon already active for ALL_KITCHENS?
 → System warns: "A free delivery coupon (FREESHIP) is already running.
 Creating another will double your committed delivery budget.
 Deactivate FREESHIP first, or confirm you want both active."

Admin must explicitly confirm before publishing the duplicate.
This prevents accidental budget doubling — the most common admin mistake.
 
 
 11.3 The Real-Time Governance Dashboard (Admin) 
 Admin sees a live view of all active offer costs: 
 ┌──────────────────────────────────────────────────────────┐
│ Active Offers — Live Overview │
│ │
│ Total active coupons: 4 │
│ Total budget committed: TZS 1,200,000 │
│ Total burned today: TZS 187,000 │
│ Projected burn by end dates: TZS 820,000 │
│ │
│ ⚠ At risk (>80% budget used): │
│ JIKO20 — 84% used — TZS 32,000 remaining │
│ │
│ COUPON TYPE USED BUDGET STATUS │
│ JIKO20 20% off 168× 84% used ACTIVE ● │
│ FREESHIP Free delivery 43× 43% used ACTIVE ● │
│ REF-* Referral 89× 62% used ACTIVE ● │
│ MAMA15 Kitchen 15% 31× 78% used ACTIVE ● │
└──────────────────────────────────────────────────────────┘
 
 You see the bleeding before it kills you. 
 
 11.4 How Conflict Is Actually Prevented 
 The real-world conflict scenarios and how each is handled: 
 SCENARIO 1: Two free delivery coupons active simultaneously
 FREESHIP (platform) active
 Admin creates FREERIDE (platform) — same scope
 → Duplicate warning fires before publishing
 → Admin must confirm or deactivate FREESHIP first
 → Even if both go active, one coupon per order rule means
 customer only uses one — no double cost per order
 → But total budget is double what was intended — warning saves this

SCENARIO 2: Platform coupon + kitchen coupon same order
 JIKO20 (platform 20% off) — customer enters this
 MAMA15 (kitchen 15% off) — customer tries to add this
 → Second code replaces first (our one-coupon rule)
 → Customer chooses which one to use
 → No stacking, no conflict, no double cost

SCENARIO 3: Menu discount + coupon
 Item has TZS 500 menu discount already (Layer 1)
 Customer applies JIKO20 coupon (Layer 2)
 → Coupon applies to the already-discounted subtotal
 → Both discounts apply — by design, no conflict
 → Menu discount absorbed by kitchen margin
 → Coupon cost absorbed by platform or kitchen (whoever owns it)
 → Separate cost centers, no confusion

SCENARIO 4: Budget exhausted mid-day
 FREESHIP budget TZS 200,000
 Order 87 pushes budgetUsed to TZS 200,000
 → Auto-deactivates immediately
 → Order 88 tries FREESHIP → "This offer is no longer available"
 → No over-spending. Ever.
 
 
 11.5 Kitchen-Level Protection 
 Kitchen owners also need protection from their own offers: 
 Kitchen creates MAMA15 — 15% off, no budget cap set
→ System REQUIRES a budget before publishing
 "Set a maximum budget to protect your earnings"

Kitchen's dashboard shows real-time:
 MAMA15 used 31× · TZS 28,500 subsidized · Budget: 71% remaining
 Estimated end: Sunday (at current rate)

At 90% budget → kitchen gets a warning notification:
 "Your MAMA15 coupon budget is almost used up.
 Add more budget or let it auto-stop when exhausted."
 
 
 12. Referral System — Built on Coupon Engine 
 The referral system is not a separate engine. It sits on top of the coupon engine. A referral is a system-generated coupon with special attributes. 
 10.1 How It Works 
 Customer A (Grace) wants to refer a friend
Grace goes to "Refer a Friend" section
System generates a unique referral coupon: REF-GRACE7X
 │
 ▼
Grace shares code/link with Zawadi via WhatsApp, SMS, or any channel
 │
 ▼
Zawadi registers on JikoXpress
Zawadi places her first order
Zawadi enters REF-GRACE7X at checkout
 │
 ▼
Coupon engine validates:
 ✓ Code exists and is a referral code (REF- prefix)
 ✓ Zawadi is a new user (NEW_USER_DAYS rule)
 ✓ This is Zawadi's first order (FIRST_ORDER rule)
 ✓ Code not yet used (perUserLimit = 1, totalUseLimit = 1)
 ✓ Grace cannot refer herself (device/phone check)
 │
 ▼
Offer applied: FREE_DELIVERY on Zawadi's first order
 │
 ▼
Order completes
 │
 ├── Zawadi already got free delivery (applied at checkout)
 │
 └── ReferralRewardEntity created for Grace
 Status: PENDING → UNLOCKED
 TZS 2,000 wallet credit → Grace's wallet
 Push notification: "Zawadi placed her first order! TZS 2,000 added to your wallet 💰"
 
 10.2 Referral Coupon Properties 
 Code format → REF-[shortcode] (e.g. REF-GRACE7X)
Generated by → system (not human-readable marketing code)
Offer type → FREE_DELIVERY (referee gets free delivery on first order)
Rules attached → FIRST_ORDER + NEW_USER_DAYS
perUserLimit → 1 (referee can only use one referral code)
totalUseLimit → 1 (each referral code is single-use)
Funded by → Platform (marketing cost)
linkedReferrer → Grace's userId (for reward tracking)
 
 10.3 Referral Entities 
 ReferralEntity
 referrerId → Grace
 refereeId → Zawadi (set when Zawadi registers with the link)
 couponCode → REF-GRACE7X
 status → PENDING | COMPLETED | REWARDED | VOIDED

ReferralRewardEntity
 referralId → links to ReferralEntity
 beneficiary → REFERRER (Grace) or REFEREE (Zawadi)
 rewardType → WALLET_CREDIT | OFFER_APPLIED
 amount → TZS 2,000 (Grace) / TZS 1,500 delivery value (Zawadi)
 status → PENDING | UNLOCKED | PAID | EXPIRED
 
 10.4 Anti-Abuse Rules 
 Self-referral check → Grace cannot use her own code
Device fingerprint → same device cannot be both referrer and referee
Phone number check → same number cannot register twice
Reward only on complete → Zawadi must complete order (not just register)
 
 10.5 Financial Impact 
 Cost per referral:
 Zawadi's free delivery subsidy: TZS 1,500 → EXPENSE_OFFER_SUBSIDY
 Grace's wallet credit: TZS 2,000 → EXPENSE_REFERRAL_REWARD
 Total platform cost: TZS 3,500

vs. acquiring a new user via digital ads in Tanzania:
 Estimated CAC via ads: TZS 15,000 – 25,000+

Referral CAC: TZS 3,500 with two happy, engaged users.
 
 
 13. B2B — Kitchen Subscription Offers 
 Why B2B Is Not in the Coupon Engine (Phase 1) 
 Coupon engine target → customers (end users placing food orders)
B2B target → kitchen owners (business operators)
B2B currency → subscription months, plan access
B2B logic → lives in the subscription system
 
 Building a separate B2B coupon engine in phase 1 is overengineering. The subscription system already has everything needed. 
 Phase 1 — Manual Admin Actions 
 Admin handles B2B directly from the subscription admin panel: 
 FREE TRIAL
 Admin selects kitchen → "Grant free trial"
 Selects plan (PROFESSIONAL) and duration (30 days)
 SubscriptionEntity updated:
 plan = PROFESSIONAL
 trialEndDate = today + 30 days
 isTrial = true
 Kitchen owner notified via WhatsApp
 Day 28 → system reminder to kitchen owner
 Day 30 → auto-revert to previous plan if not upgraded

DISCOUNTED UPGRADE
 Admin selects kitchen → "Apply discount"
 Sets discount percent and duration (N billing cycles)
 Subscription billing uses discounted rate for those cycles
 Normal rate resumes after

LOYALTY REWARD
 Admin manually adjusts kitchen's subscription rate
 "You've been with us 12 months — 20% off forever"
 Admin note recorded for audit trail
 
 Phase 2 — Automated B2B Engine 
 When you have enough kitchens that manual management doesn't scale: 
 System detects growth signals (order volume threshold)
Auto-triggers trial offer to qualifying kitchens
Tracks acceptance, trial usage, conversion rate
Full B2B offer engine with targeting rules
 
 
 14. Notification & Preference System 
 12.1 User Notification Preferences 
 Every customer controls their offer notification preferences: 
 Master toggle: Notify me for offers [ON / OFF]

If ON — what types do you want?
 ☑ Free delivery deals
 ☑ Discounts & coupons
 ☑ New kitchen promotions
 ☑ Birthday offers
 ☐ Flash sales
 ☑ Referral rewards
 
 One UserOfferPreferenceEntity per user. System only notifies users who opted in to the relevant category. 
 12.2 Notification Triggers 
 TRIGGER ACTION
─────────────────────────────── ──────────────────────────────────────────────
New platform coupon published → notify all eligible opted-in users
New kitchen coupon published → notify users who ordered from this kitchen
 and opted in
Referral reward unlocked → notify referrer "TZS 2,000 added to wallet"
Coupon about to expire → 24hr warning if user viewed but didn't redeem
B2B trial offer granted → WhatsApp to kitchen owner
B2B trial ending soon → reminder 2 days before trial ends
 
 12.3 Notification Channels 
 Push notification → app users
WhatsApp message → WhatsApp channel users (highest open rate in Tanzania)
SMS → fallback for users without WhatsApp or app
In-app banner → shown next time user opens app
 
 
 15. User Journeys — All Levels 
 13.1 New Customer — Platform Coupon (Admin Drops Code on WhatsApp) 
 [JikoXpress admin posts in a WhatsApp group]:
"New on JikoXpress? Use code JIKO20 — 20% off your first order! 🎉"

Maria sees the message, downloads the app, registers
 │
 ▼
Maria browses kitchens, adds items (TZS 10,000 food)
 │
 ▼
Checkout → Maria types: JIKO20
 │
 ▼
System validates:
 ✓ Code exists
 ✓ Coupon is ACTIVE
 ✓ Channel: App (eligible)
 ✓ FIRST_ORDER rule → Maria has 0 completed orders ✓
 ✓ NEW_USER_DAYS = 7 → Maria registered today ✓
 ✓ Budget remaining
 ✓ perUserLimit not hit
 │
 ▼
Checkout updates:
 Food total: TZS 10,000
 20% discount: - TZS 2,000
 You pay: TZS 8,000
 "JIKO20 applied — You saved TZS 2,000 ✓"
 │
 ▼
Maria pays TZS 8,000. Order placed. Order arrives.
 │
 ▼
Order confirmation: "You saved TZS 2,000 today 🎉
 Share JikoXpress with a friend — you BOTH get a reward. [Share]"
 │
 ▼
Maria immediately shares her referral code.
New user acquired. Referral loop started.
 
 
 13.2 Regular Customer — Kitchen Coupon from Physical Flyer 
 [Juma walks past a flyer in Mbeya town]
Flyer: "Order from Mama Lishe online — use MAMA15 for 15% off this weekend 🍽"
 │
 ▼
Juma opens JikoXpress (app or WhatsApp), finds Mama Lishe, adds items (TZS 12,000)
 │
 ▼
Checkout → types: MAMA15
 │
 ▼
System validates:
 ✓ Code exists
 ✓ Coupon is ACTIVE, scope = SPECIFIC_KITCHEN (Mama Lishe) ✓
 ✓ VALID_DAYS_OF_WEEK = [FRI, SAT] → today is Saturday ✓
 ✓ MIN_ORDER_AMOUNT = 8,000 → order is TZS 12,000 ✓
 ✓ perUserLimit = 2 → Juma has used 0 times ✓
 │
 ▼
Checkout updates:
 Food: TZS 12,000
 15% discount: - TZS 1,800
 You pay: TZS 10,200
 "MAMA15 applied — You saved TZS 1,800 ✓"
 │
 ▼
Order placed.
Kitchen Mama Lishe receives:
 Gross: TZS 12,000 (full food amount)
 Less offer subsidy:- TZS 1,800 (kitchen funded this)
 Net settlement: TZS 10,200
Platform earns service fee on original TZS 12,000.
 
 Physical flyer → digital order. Tanzania market unlocked. 
 
 13.3 New User — Referral Coupon 
 [Grace is a happy JikoXpress user]
Grace goes to "Refer a Friend" → gets code REF-GRACE7X
Grace sends it to her sister Zawadi via WhatsApp
 │
 ▼
Zawadi registers on JikoXpress
Zawadi browses, adds items (TZS 9,000 food, delivery TZS 1,500)
 │
 ▼
Checkout → Zawadi enters: REF-GRACE7X
 │
 ▼
System validates:
 ✓ Referral code exists and is valid
 ✓ Zawadi is a new user ✓
 ✓ This is Zawadi's first order ✓
 ✓ Code not yet used ✓
 ✓ Grace ≠ Zawadi (self-referral check passed) ✓
 │
 ▼
Offer: FREE_DELIVERY applied
 Food: TZS 9,000
 Delivery: ~~TZS 1,500~~ → FREE ✓
 You pay: TZS 9,000
 "Welcome gift — Free delivery on your first order 🎁"
 │
 ▼
Zawadi pays TZS 9,000. Order completes.
 │
 ▼
System creates ReferralRewardEntity for Grace
Status: PENDING → UNLOCKED
TZS 2,000 credited to Grace's wallet
 │
 ▼
Grace gets push notification:
"Your sister Zawadi placed her first order! TZS 2,000 added to your wallet 💰"
 │
 ▼
Grace uses wallet credit on her next order.
Two users engaged. Total platform cost: TZS 3,500.
 
 
 13.4 Kitchen Owner — Creating a Weekend Promo Coupon 
 [Mama Lishe logs into kitchen dashboard — Thursday afternoon]
Goes to Offers → clicks [+ New Coupon]
 │
 ▼
Form:
 Coupon code: MAMA15 (she types this — her brand, memorable)
 Offer type: PERCENT_DISCOUNT
 Discount: 15%
 Applies to: Whole kitchen
 Rules:
 Min order: TZS 8,000
 Valid days: Friday, Saturday
 Time window: All day (no time restriction)
 Budget: TZS 40,000 (won't spend more than this)
 Per user limit: 2 uses
 Runs: This Friday → Sunday night
 │
 ▼
Coupon goes ACTIVE
Deal badge appears on Mama Lishe's kitchen card in the app
 │
 ▼
Kitchen dashboard shows real-time:
 "MAMA15 — Used 18× today · TZS 28,500 subsidized · Budget: 29% remaining"
 │
 ▼
Sunday midnight → coupon auto-expires
Kitchen sees performance report:
 Total orders from coupon: 31
 Total subsidy paid: TZS 40,000 (budget fully used, auto-deactivated)
 New customers acquired: 14 first-time orders at this kitchen
 
 Kitchen owner has full control, zero surprises. 
 
 13.5 Kitchen Owner — Receiving B2B Trial Offer (Manual Phase 1) 
 [Kitchen Bora Bora — 4 months on STARTER, growing fast]
Admin notices 3x order volume growth in last 60 days
Admin goes to subscription admin panel
Selects Bora Bora → [Grant Free Trial]
 Plan: PROFESSIONAL
 Duration: 30 days
 Note: "Growth milestone reward"
 │
 ▼
Admin sends WhatsApp to Bora Bora owner:
"Habari! Your kitchen is growing fast 🚀
 We're giving you FREE access to PROFESSIONAL plan for 30 days.
 Enjoy: unlimited menu items, advanced analytics, priority support.
 No action needed — it's already active. Try it!"
 │
 ▼
Day 28 → system auto-sends reminder to kitchen:
"Your free PROFESSIONAL trial ends in 2 days.
 Upgrade to keep your features — TZS 45,000/month.
 Reply to talk to our team."
 │
 ▼
Kitchen has grown accustomed to PROFESSIONAL features → upgrades.
 
 
 16. UI Ideas & Flow Concepts 
 14.1 Home Screen — Coupon Discovery 
 ┌─────────────────────────────────────────────┐
│ JikoXpress 🔔 👤 │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 🎉 Use code JIKO20 — 20% off │ │
│ │ your order today! │ │
│ │ [Copy Code] │ │
│ └─────────────────────────────────────┘ │
│ │
│ 🔥 Kitchens With Deals │
│ ┌────────────┐ ┌────────────┐ │
│ │ [Photo] │ │ [Photo] │ │
│ │ Mama Lishe │ │ Bora Bora │ │
│ │ 🏷 MAMA15 │ │ 🚚 Free │ │
│ │ 15% OFF │ │ delivery │ │
│ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────┘
 
 Deal badges are visible before clicking into a kitchen. Value is shown upfront. 
 14.2 Checkout — Coupon Entry & Applied State 
 ┌──────────────────────────────────────┐
│ Order Summary │
│ │
│ Ugali na Nyama TZS 7,000 │
│ Pilau TZS 5,000 │
│ ─────────────────────────────────── │
│ Subtotal TZS 12,000 │
│ Delivery TZS 1,500 │
│ │
│ ┌──────────────────────────────┐ │
│ │ 🏷 Enter coupon code │ │
│ │ [MAMA15 ] [APPLY] │ │
│ └──────────────────────────────┘ │
│ │
│ ✅ MAMA15 applied! │
│ Discount: - TZS 1,800 │
│ ─────────────────────────────────── │
│ Total TZS 10,200 │
│ │
│ 💚 You saved TZS 1,800 today! │
│ │
│ [Place Order — TZS 10,200] │
└──────────────────────────────────────┘
 
 Savings celebrated before payment. Positive reinforcement at the most important moment. 
 14.3 Order Confirmation — Savings + Referral CTA 
 ┌──────────────────────────────────────┐
│ ✅ Order Confirmed! │
│ │
│ Estimated delivery: 30 minutes │
│ │
│ ┌──────────────────────────────┐ │
│ │ 💰 You saved TZS 1,800 │ │
│ │ with code MAMA15 │ │
│ └──────────────────────────────┘ │
│ │
│ 🎁 Know someone who'd love this? │
│ Share your referral code and │
│ you BOTH get a reward. │
│ Your code: REF-MARIA3K │
│ [Share Now] │
└──────────────────────────────────────┘
 
 Every confirmation is a referral opportunity. Strike when satisfaction is highest. 
 14.4 Coupon Validation — Error State 
 ┌──────────────────────────────────────┐
│ [MAMA15 ] [APPLY] │
│ │
│ ❌ This offer is only valid on │
│ Fridays and Saturdays. │
│ Come back this weekend! │
└──────────────────────────────────────┘
 
 Specific error. Not just "invalid." And crucially — "come back this weekend" keeps the user engaged for a future order. 
 14.5 Kitchen Dashboard — Coupon Management 
 ┌──────────────────────────────────────┐
│ My Coupons [+ New] │
│ │
│ ● MAMA15 — Weekend Special ACTIVE │
│ 15% off · Fri–Sat │
│ Used 18× · Budget: 29% left │
│ Expires Sunday │
│ [Pause] [Edit] [Stats] │
│ │
│ ○ OPENDAY — Grand Opening EXPIRED │
│ 20% off · 3 days │
│ Used 87× · Budget fully used │
│ New customers: 41 │
│ [Duplicate as new] │
└──────────────────────────────────────┘
 
 Performance visible at a glance. Kitchen owners see ROI clearly. 
 14.6 Offer Notification Preferences 
 ┌──────────────────────────────────────┐
│ ← Offer Notifications │
│ │
│ Get notified about deals │
│ ●────────────────── ON │
│ │
│ What interests you? │
│ │
│ 🚚 Free Delivery deals ☑ │
│ 🏷 Discounts & coupons ☑ │
│ 🆕 New kitchen promos ☑ │
│ 🎂 Birthday offers ☑ │
│ 🎁 Referral rewards ☑ │
│ ⚡ Flash sales ☐ │
│ │
│ [Save] │
└──────────────────────────────────────┘
 
 User in control. Builds trust. Reduces unsubscribes. 
 
 17. Where JikoXpress Wins 
 15.1 The Tanzania-Specific Advantages 
 Physical coupon → digital order bridge 
Kitchen prints MAMA15 on a flyer, sticks it at a bus station, a market stall, a university notice board. Customer orders on WhatsApp or app using that code. No other food platform in Tanzania does this cleanly. This is the entire informal economy brought into the digital platform. 
 WhatsApp as a first-class coupon channel 
Admin drops JIKO20 in a WhatsApp group. Kitchen shares MAMA15 in their neighborhood group. These codes work on WhatsApp ordering directly. The channel Tanzanians already use becomes a marketing and ordering channel simultaneously. 
 Kitchen empowerment 
Kitchens are not passive suppliers. They create their own coupons, set their own rules, control their own budget. They become invested in JikoXpress success because JikoXpress invests in their success. 
 Referral at TZS 3,500 CAC 
Acquiring users via digital ads in Tanzania costs TZS 15,000–25,000+. A referral costs TZS 3,500 and gives you two engaged users. This is how JikoXpress grows without burning investor money. 
 15.2 What Jumia Got Wrong — What JikoXpress Fixes 
 Jumia's mistake JikoXpress answer
──────────────────────────────────── ──────────────────────────────────────────
App-only offers → Coupons work on App + WhatsApp + Counter
No physical coupon bridge → Kitchen prints codes on flyers
Generic "save money" messaging → Specific errors, specific savings shown
No kitchen marketing tools → Kitchen dashboard with full coupon control
No referral program → Structured referral built on coupon engine
Burned budget on wrong users → Rule engine filters eligible users precisely
 
 15.3 The Retention Loop 
 Customer discovers JikoXpress via referral code or admin coupon
 │
 ▼
First order → coupon gives value → positive experience
 │
 ▼
Refers a friend → wallet credit → uses wallet → orders again
 │
 ▼
Favorite kitchen runs a weekend promo → orders again
 │
 ▼
Habit formed → orders without needing a coupon
 │
 ▼
Becomes organic referrer
 
 The coupon engine's real job is not discounts. Its job is to convert a first-time user into a habitual customer before they even notice it happened. 
 
 18. Financial Impact of Offers 
 16.1 Platform Coupon — Financial Flow 
 Platform coupon applied (e.g. JIKO20 — 20% off):

Customer pays: TZS 8,000 (discounted)
Platform absorbs: TZS 2,000 (the discount)
Kitchen receives: TZS 10,000 (full original amount — always)

Journal:
 DEBIT EXPENSE_OFFER_SUBSIDY 2,000
 CREDIT ASSET_PSP_SELCOM 2,000

Platform service fee earned on original TZS 10,000 — not discounted amount.
Platform marketing cost = TZS 2,000.
 
 16.2 Kitchen Coupon — Financial Flow 
 Kitchen coupon applied (e.g. MAMA15 — 15% off TZS 12,000 order):

Customer pays: TZS 10,200 (discounted)
Kitchen absorbs: TZS 1,800 (they chose to discount)
Kitchen receives: TZS 10,200 net (after subsidy deduction at settlement)

Settlement:
 Kitchen gross: TZS 12,000
 Less: coupon subsidy: - TZS 1,800
 Kitchen net: TZS 10,200

Platform service fee earned on original TZS 12,000.
Platform earns same regardless of kitchen's promotional decisions.
 
 16.3 FREE_DELIVERY Coupon — Financial Flow 
 FREE_DELIVERY coupon applied:

Customer pays: food total only (e.g. TZS 9,000)
Platform absorbs: delivery fee (e.g. TZS 1,500) if platform coupon
Kitchen absorbs: delivery fee if kitchen coupon (deducted at settlement)
Rider receives: full delivery fee as normal

Platform coupon journal:
 DEBIT EXPENSE_OFFER_SUBSIDY 1,500
 CREDIT ASSET_PSP_SELCOM 1,500
 
 16.4 Budget Controls — Automatic 
 Every coupon with a budget has automatic controls:

budgetUsed reaches 80% of budgetTotal → admin / kitchen notification
budgetUsed reaches 100% → coupon auto-deactivates immediately
totalUsed reaches totalUseLimit → coupon auto-deactivates immediately

No manual intervention needed.
No over-spending possible.
 
 16.5 Referral Financial Impact 
 Per referral:
 Referee free delivery: TZS 1,500 → EXPENSE_OFFER_SUBSIDY
 Referrer wallet credit: TZS 2,000 → EXPENSE_REFERRAL_REWARD
 Total platform cost: TZS 3,500

Industry digital ad CAC: TZS 15,000 – 25,000+
Referral CAC: TZS 3,500 with two engaged users
 
 
 19. Entity Overview 
 No code. No schema. Just entities and their relationships. 
 CouponEntity
 → defines the coupon (code, type, owner, scope, discount config, budget, dates)
 → offerOwner: PLATFORM | KITCHEN
 → has many CouponRuleEntity
 → has many CouponUsageEntity (per user tracking)
 → has many CouponRedemptionEntity (per order)

CouponRuleEntity
 → one rule per record (ruleType + ruleValue)
 → many rules per coupon, ALL must pass (AND logic)

CouponUsageEntity
 → one record per user per coupon
 → tracks how many times this user used this coupon
 → prevents per-user limit violations

CouponRedemptionEntity
 → one record per order that used a coupon
 → stores exact discount applied, amount subsidized
 → funded by: PLATFORM or KITCHEN
 → linked to both coupon and order

KitchenDeliveryConfig
 → deliveryHandledBy: JIKOXPRESS | KITCHEN_SELF
 → deliveryPricingModel: FLAT_FEE | DISTANCE_BASED | FREE_ALWAYS
 → maxDeliveryRadiusKm
 → has many KitchenDeliveryTierEntity

KitchenDeliveryTierEntity
 → fromKm, toKm, fee, isDeliverable
 → child of KitchenDeliveryConfig

KitchenDeliverySubsidyEntity
 → standing delivery cost coverage (not a coupon)
 → coverageType: ALL_ORDERS | SPECIFIC_ORDERS
 → startDate, endDate, status: ACTIVE | EXPIRED | CANCELLED

UserOfferPreferenceEntity
 → one per user
 → notificationsEnabled (master toggle)
 → preferredTypes: list of OfferNotificationType

ReferralEntity
 → referrerId, refereeId
 → couponCode (the REF- code generated)
 → status: PENDING | COMPLETED | REWARDED | VOIDED

ReferralRewardEntity
 → referralId (links to ReferralEntity)
 → beneficiary: REFERRER | REFEREE
 → rewardType: WALLET_CREDIT | OFFER_APPLIED
 → amount, status: PENDING | UNLOCKED | PAID | EXPIRED
 
 
 
 20. Implementation Prerequisites 
 The offer engine is designed. It is complete. Do not build it yet. 
 This is not because the design is incomplete — it is because offers touch every financial layer of the platform. Building offers while those layers are still moving creates financial bugs that are hard to trace and expensive to fix. 
 The offer engine implementation begins only when all of the following are green: 
 PREREQUISITE WHY IT MATTERS FOR OFFERS
──────────────────────────────────────── ─────────────────────────────────────────────
✅ Order lifecycle complete Offer redemption is tied to order status.
 (checkout → confirmed → delivered) Can't track "order completed" for FIRST_ORDER
 rule or referral reward unlock without this.

✅ Payment splitting working Platform coupons debit EXPENSE_OFFER_SUBSIDY.
 (kitchen vs platform vs rider) Kitchen coupons deduct from settlement.
 If splitting is wrong, offer accounting is wrong.

✅ Kitchen settlement working Kitchen coupon subsidy is deducted at settlement.
 (earnings, deductions, payouts) Can't deduct what hasn't been calculated.

✅ Journal entries flowing correctly Every offer redemption creates journal entries.
 If double-entry bookkeeping isn't stable,
 offer entries will pollute the ledger.

✅ User order history queryable FIRST_ORDER rule queries: "has this user ever
 completed an order?"
 FIRST_ORDER_AT_KITCHEN queries per kitchen.
 Needs reliable order history.

✅ Wallet system working Referral rewards credit the referrer's wallet.
 Wallet must exist and be transactionally safe
 before referral rewards are issued.

✅ Menu item management stable Layer 1 (menu discount) is set on menu items.
 Menu item CRUD must be stable before adding
 discount fields to it.
 
 When all seven are confirmed stable and tested in a real environment — open this document and begin entity design and implementation. 
 The design will not change significantly. The thinking is done. Build the foundation first. 
 
 21. Decision Log 
 
 
 
 Decision 
 Choice 
 Reason 
 
 
 
 
 Three discount layers 
 Layer 1 (menu), Layer 2 (coupon), Layer 3 (auto-offer phase 2) 
 Each serves a different purpose, different actor, different financial impact. Must never be confused. 
 
 
 Menu discount channels 
 All channels, always 
 A price is a price. Not a promotion. Channel restriction makes no sense for item pricing. 
 
 
 Menu discount lifespan 
 None in phase 1 — kitchen edits manually 
 Adding lifespan blurs the line between menu pricing and the coupon engine. Keep layers clean. 
 
 
 Menu discount financial 
 Absorbed in kitchen margin, not tracked as offer 
 It is a price reduction, not a promotional cost. No CouponRedemptionEntity created. 
 
 
 Phase 1 redemption 
 Coupon codes only 
 80% of value, 20% complexity. Market feedback before building auto-apply. 
 
 
 Auto-applied offers 
 Phase 2 
 Requires user profiling and eligibility checks on every checkout. Build when you have data. 
 
 
 Rule engine 
 Separate CouponRuleEntity table 
 Future-proof. New rule types added as enum values without schema changes. 
 
 
 Referral implementation 
 System-generated coupon on top of coupon engine 
 Reuses validation engine. Not a separate system. Clean separation of concerns. 
 
 
 B2B phase 1 
 Manual via subscription admin panel 
 Not enough kitchens to justify automation. Admin handles manually. 
 
 
 Coupon codes on all channels 
 Yes, default 
 Physical flyer → WhatsApp/app/counter bridge is a real Tanzania market advantage. 
 
 
 Coupon stacking 
 One coupon per order, phase 1 
 Financial math stays clean. Prevents abuse. Last code entered replaces previous. Phase 2 may allow controlled stacking when market data justifies it. 
 
 
 Kitchen always gets full amount 
 Yes (platform coupons) 
 Platform subsidy is platform's marketing cost. Kitchen is not penalized. 
 
 
 Platform earns on original price 
 Yes (kitchen coupons too) 
 Kitchen's promotional decision does not affect platform service fee. 
 
 
 Delivery config separation 
 Three distinct systems 
 Self-delivery config, subsidy standing instruction, and FREE_DELIVERY coupon are fundamentally different. Must never mix. 
 
 
 Distance-based delivery 
 Kitchen config tiers 
 Pricing decision by kitchen, resolved at checkout before coupons are checked. 
 
 
 Validation specificity 
 Always specific error message 
 "Come back this weekend" keeps user engaged. Vague errors kill conversion. 
 
 
 Budget auto-deactivation 
 Yes, at 100% usage 
 No over-spending possible. No manual intervention needed. 
 
 
 Budget required 
 Mandatory before publishing any coupon 
 No open-ended coupons. Every coupon has a financial ceiling. 
 
 
 Duplicate offer warning 
 Yes — system warns before admin publishes duplicate type/scope 
 Most common admin mistake. Prevents accidental budget doubling. 
 
 
 Referral CAC 
 TZS 3,500 target 
 TZS 1,500 (referee delivery) + TZS 2,000 (referrer wallet). Far below digital ad CAC. 
 
 
 Offer engine implementation timing 
 Only after 7 core prerequisites are stable 
 Offers touch every financial layer. Building on unstable foundation creates untraceable financial bugs. 
 
 
 
 
 QBIT SPARK CO LIMITED | JikoXpress Pro | May 2026 
 Internal offer engine architecture — confidential