JikoXpress Pro — Payment, Subscription & Business Model Architecture
| Property | Value |
|---|---|
| Version | 1.0 |
| Status | Draft |
| Created | April 2026 |
| Purpose | Development Guide — Payment, Subscription & Delivery Model |
Executive Summary
JikoXpress Pro operates a three-engine business model designed specifically for the East African food market. Unlike generic SaaS platforms, JikoXpress earns from three distinct but complementary revenue streams — each designed to align platform success with kitchen success.
Part 1: The Three-Engine Business Model
1.1 Overview
ENGINE 1 — Platform Subscription
Kitchen pays monthly to use JikoXpress management tools
POS, KDS, menu, staff, devices, reports — the full platform
ENGINE 2 — Marketplace Commission
JikoXpress brings external customers to the kitchen
Platform earns a cut on those orders only
ENGINE 3 — Delivery Revenue Share
Customer pays delivery fee
JikoXpress shares majority with Dasher, keeps margin
1.2 Revenue Stream Breakdown
| Stream | Who Pays | When | Amount | Applies To |
|---|---|---|---|---|
| Subscription | Kitchen | Monthly | Plan-based | All kitchens |
| Marketplace Commission | Kitchen (deducted) | Per order | 10% of food value | App & WhatsApp orders only |
| Delivery Margin | Customer (via delivery fee) | Per delivery | 30% of delivery fee | All Dasher deliveries |
1.3 What Each Order Type Earns JikoXpress
| Channel | Fulfillment | Subscription ✓ | Commission | Delivery Margin |
|---|---|---|---|---|
| POS | Dine-in | ✅ | ❌ | ❌ |
| POS | Pickup | ✅ | ❌ | ❌ |
| POS | Delivery (Dasher) | ✅ | ❌ | ✅ |
| Kiosk | Dine-in / Pickup | ✅ | ❌ | ❌ |
| Table QR | Dine-in | ✅ | ❌ | ❌ |
| App | Pickup | ✅ | ✅ | ❌ |
| App | Delivery (Dasher) | ✅ | ✅ | ✅ |
| Pickup | ✅ | ✅ | ❌ | |
| Delivery (Dasher) | ✅ | ✅ | ✅ |
App + Dasher Delivery = all three engines firing simultaneously. Highest value order type.
1.4 The Core Principle
Subscription is the stability engine — predictable, recurring. Commission is the growth engine — scales with kitchen volume. Delivery is the experience engine — owns the customer journey end-to-end.
STARTER is free forever — not charity. It is a customer acquisition tool. STARTER kitchens still generate commission revenue on app orders and processing margin on every M-Pesa transaction. Every kitchen on STARTER that takes 50 app orders/month earns JikoXpress real money without paying a subscription.
Part 2: Subscription Plans
2.1 Plan Tiers
STARTER — Free Forever
Price: TZS 0 / month
Billing: None
Trial: Not applicable — free forever
Target: Home chefs, street vendors, side hustle cooks
Included:
Limits:
GROWING — Mid Tier
Price: TZS X/month (monthly) or TZS X/week (weekly)
Billing: Monthly or Weekly — kitchen chooses
Trial: Covered by 3-day PROFESSIONAL trial on signup
Target: Small restaurants, busy food stalls, cafes, food trucks
Included (everything in STARTER plus):
Limits:
- 1,000 orders/month
- 3 staff accounts
- 1 location
Weekly billing option exists because a food stall thinking "TZS 50,000/month" hesitates. "TZS 12,500/week" maps to how small East African businesses think about cash flow.
PROFESSIONAL — Full Feature
Price: TZS XX/month or TZS XX/year (annual = 2 months free)
Billing: Monthly or Annual — kitchen chooses
Trial: Covered by 3-day trial on signup
Target: Full-service restaurants, fast food, bars, hotel restaurants
Included (everything in GROWING plus):
- Kitchen stations
- KDS (Kitchen Display System)
- Drive-through support
- Tabs (pay-later for dine-in)
- Table management
- Up to 15 staff accounts
- Roles & permissions + discount limits
- Advanced reports + customer insights
- Priority support
Limits:
- Unlimited orders
- 15 staff accounts
- 1 location
Annual billing for PROFESSIONAL is a strong retention tool. Once they've paid a year upfront, churn almost disappears.
ENTERPRISE — Custom
Price: Custom (negotiated offline)
Billing: Annual or manual — admin-activated
Trial: No trial — demo + custom onboarding instead
Target: Restaurant chains, franchises, hotel groups, cloud kitchens
Included (everything in PROFESSIONAL plus):
- Multi-location support
- Central menu management
- Consolidated cross-location reports
- API access for integrations
- Inventory management
- White-label option
- Dedicated support + SLA guarantees
- Custom integrations
Limits: Unlimited everything
2.2 Billing Cycle Options by Plan
| Plan | Weekly | Monthly | Annual |
|---|---|---|---|
| STARTER | ❌ | ❌ | ❌ |
| GROWING | ✅ | ✅ | ❌ |
| PROFESSIONAL | ❌ | ✅ | ✅ |
| ENTERPRISE | ❌ | ❌ | Custom |
Part 3: The 3-Day Trial System
3.1 How It Works
Every new kitchen gets one automatic 3-day trial on PROFESSIONAL — not GROWING.
Why PROFESSIONAL specifically? Show them the ceiling. KDS, stations, tabs, drive-through. If they trial GROWING, they never see the most powerful features and undervalue the platform. Show them the best, then they decide where to settle.
Kitchen registers
↓
System offers: "Try PROFESSIONAL free for 3 days — no payment needed"
↓
├── Accept → status: TRIALING, plan: PROFESSIONAL, trialEndsAt: now + 3 days
│ No payment info required
│
└── Skip → lands directly on STARTER
3.2 Trial Expiry Flow
Trial day 3 ends
↓
├── Kitchen entered payment method → auto-converts to PROFESSIONAL ACTIVE
│ First charge hits immediately
│ New billing cycle starts
│
└── No payment method → drops silently to STARTER
Notification: "Your trial ended. Upgrade anytime to get back."
No disruption — kitchen still operational on STARTER
3.3 Trial Rules
- One trial per account ever — automatic, system-enforced
- Admin can manually grant re-trial — for re-engagement, churned kitchens, sales tool
- No trial for ENTERPRISE — they get a demo + custom onboarding instead
- Trial is always PROFESSIONAL — never GROWING, never ENTERPRISE
3.4 The Re-Trial (Admin Tool)
Admin dashboard → Kitchen profile → [Grant Re-Trial]
↓
Admin selects duration (3, 7, or 14 days)
↓
Kitchen gets push notification: "Good news! You've been given X days on PROFESSIONAL"
↓
Same flow as original trial — expires or converts
This is a powerful churn recovery and sales tool. Use it for:
- Kitchens that churned due to payment failure (not dissatisfaction)
- Enterprise prospects evaluating the platform
- Re-engaging inactive STARTER kitchens
Part 4: Subscription Lifecycle — All Scenarios
4.1 New Kitchen — Full Flow
SIGNUP
↓
3-day PROFESSIONAL trial offered
↓
[Accept trial] → TRIALING
↓
Day 3: trial expires
↓
[Has payment method] → ACTIVE on chosen paid plan
[No payment method] → STARTER (free forever)
↓
Monthly auto-renewal cycle begins
4.2 Upgrade Flow
From STARTER → GROWING or PROFESSIONAL:
Kitchen hits a limit OR tries a locked feature
↓
In-context upgrade prompt appears (not redirect to settings)
Shown right where they hit the wall
↓
"You've reached 20 menu items. Upgrade to GROWING for unlimited."
[Upgrade Now]
↓
Kitchen selects billing cycle (weekly/monthly for GROWING, monthly/annual for PRO)
↓
Pays via M-Pesa / card
↓
Plan activates IMMEDIATELY
↓
Feature they were trying to use → now available
System continues where they left off — no restart
In-context upgrade triggers:
| Trigger | Message |
|---|---|
| 21st menu item | "You've reached 20 items. Upgrade to GROWING for unlimited." |
| 80 orders (STARTER) | "20 orders left this month. Upgrade to avoid interruption." |
| Enable POS | "POS is available on GROWING and above." |
| Enable KDS | "KDS is available on PROFESSIONAL and above." |
| Enable tabs | "Tabs are available on PROFESSIONAL and above." |
| Add 4th staff | "You've reached your staff limit. Upgrade to add more." |
From GROWING → PROFESSIONAL: Same flow. Charge full PROFESSIONAL price. New billing cycle starts on upgrade date. No proration in v1 — simpler, cleaner.
4.3 Downgrade Flow
Kitchen requests downgrade (e.g. PROFESSIONAL → GROWING)
↓
System shows what they will LOSE on the downgrade date:
"On [date] you will lose access to:
- Kitchen Stations
- KDS displays
- Tabs (pay later)
- Drive-through
- Staff accounts above 3"
↓
Save flow — system offers:
"Stay on PROFESSIONAL for 1 more month at 50% off?"
[Accept offer] [Proceed with downgrade]
↓
[Accept] → offer applied, subscription continues at 50%
[Proceed] → downgrade SCHEDULED for end of current billing period
↓
Until that date: still on PROFESSIONAL, full access
↓
On renewal date: switches to GROWING, charged GROWING price
What happens to data above the new plan's limits?
Data is NEVER deleted. It is soft-locked:
| Resource | On Downgrade to GROWING | On Re-upgrade |
|---|---|---|
| Kitchen stations | Archived (not deleted) | Restored instantly |
| KDS config | Archived | Restored instantly |
| Staff above 3 | Suspended (can't login) | Reactivated |
| Tabs history | Read-only | Fully accessible |
4.4 Cancellation Flow
Kitchen requests cancellation
↓
System shows impact:
"Your subscription ends on [date].
After that you'll move to STARTER (free forever).
Your data is safe — menus, orders, history all preserved."
↓
Save flow:
"Stay for 1 more month at 50% off?"
[Accept] [Cancel anyway]
↓
[Cancel anyway] → cancellation SCHEDULED for end of current period
↓
Access continues until period ends — no immediate disruption
↓
On expiry: status → CANCELLED, plan falls to STARTER
Kitchen still operational — just on free tier
Cancellation ≠ lockout. They keep STARTER forever.
4.5 Payment Failure & Dunning Flow
Renewal date arrives
↓
Auto-charge attempt → FAILS
↓
status: PAST_DUE
↓
Day 0: Push notification + WhatsApp:
"Your payment didn't go through. Tap to retry."
Silent retry attempt
Day 1: Silent retry
Day 3: Push + WhatsApp (stronger):
"⚠️ Your subscription payment failed again.
Update your payment method to keep full access."
Silent retry attempt
Day 5: Silent retry
Day 7: Push + WhatsApp (urgent):
"⚠️ Final notice — access suspending tomorrow.
Tap to update payment and stay active."
↓
Day 8: status: SUSPENDED
Kitchen enters LIMITED MODE
↓
During suspension (7 days):
- Can log in ✅
- Can view menu, history, reports ✅
- CANNOT accept new orders ❌
- CANNOT process payments ❌
- Banner shown everywhere: "Renew to resume taking orders"
- Push + WhatsApp every 2 days
↓
Day 15: status: CANCELLED
Plan falls to STARTER
Full STARTER access restored
Paid features soft-locked (data preserved)
Limited mode during suspension is critical. A fully locked-out owner panics and churns permanently. A visible-but-restricted owner is motivated to pay and comes back.
4.6 Re-subscription After Cancellation / Failure
Kitchen wants to re-subscribe
↓
Selects plan + billing cycle
↓
Pays
↓
ACTIVE immediately
↓
All archived data restored:
- Stations restored
- KDS config restored
- Staff reactivated
- Old menu items restored (including any over-limit ones)
↓
"Welcome back! Everything is right where you left it." 🎉
Part 5: Limit Enforcement & Data Preservation
5.1 The Core Principle
JikoXpress never deletes kitchen data due to plan changes. Ever.
Data is soft-locked. Access is restricted. But everything is preserved and restores instantly on upgrade.
5.2 What Happens When Kitchen Drops to STARTER
Kitchen has 200 items → drops to STARTER
↓
System auto-selects 20 most recently active items
Selection priority:
1. Items with orders in last 30 days (sorted by order count)
2. Fill remaining with most recently created items
3. Never auto-select items owner already marked unavailable
↓
Those 20 → status: ACTIVE (kitchen immediately live — no downtime)
Remaining 180 → status: OVER_LIMIT_INACTIVE (preserved, not orderable)
↓
Owner notified:
"You're on STARTER. We've kept your 20 most active items live.
Swap them anytime from your menu settings."
↓
Owner can swap at any time:
Deactivate 1 active → activate 1 locked
Always exactly 20 active. Kitchen always live.
Kitchen never goes offline due to a plan change.
5.3 Menu Item Status Model
ACTIVE → visible, orderable, counts toward limit
UNAVAILABLE → owner manually turned off (out of stock)
OVER_LIMIT_INACTIVE → exists but locked due to plan limit
ARCHIVED → owner soft-deleted
OVER_LIMIT_INACTIVE is distinct from UNAVAILABLE — different reason, different resolution path. One is owner choice, the other resolves automatically on upgrade.
5.4 Limit Enforcement Across All Resources
| Resource | STARTER | On Drop — System Action | Kitchen Impact |
|---|---|---|---|
| Menu items | 20 | Auto-pick 20 most active, rest OVER_LIMIT_INACTIVE | None — stays live with 20 |
| Staff accounts | 1 | Extra staff suspended (can't login) | Owner still operational |
| Orders/month | 100 | Counter resets monthly, past orders preserved | Future orders blocked at 100 |
| Table QR | 1 table | Extra QR codes deactivated, first one stays | 1 table still works |
| Locations | 1 | Extra locations suspended, not deleted | Primary location works |
5.5 Usage-Based Upgrade Prompts
STARTER → GROWING triggers:
- Orders this month > 80 (approaching 100 limit)
- Menu items > 15 (approaching 20 limit)
- Customer tried to pay by card (not available on STARTER)
- Multiple staff login attempts
GROWING → PROFESSIONAL triggers:
- Orders this month > 800 (approaching 1,000 limit)
- Staff maxed at 3
- Kitchen searched for: tabs, stations, KDS, drive-through
- Average prep time > 15 minutes
PROFESSIONAL → ENTERPRISE triggers:
- Kitchen asked about second location
- Searched for: multi-location, franchise, API
- Monthly orders consistently > 5,000
Part 6: Feature Access Control
6.1 Three-Layer Access Model
Every feature check in the system goes through three layers:
Layer 1 — Subscription Status
ACTIVE or TRIALING → proceed to Layer 2
PAST_DUE → proceed (grace, still accessible)
SUSPENDED → BLOCK (show renew prompt)
CANCELLED → STARTER features only
Layer 2 — Plan Features
Feature in this plan? → proceed to Layer 3
Feature not in plan? → BLOCK (show upgrade prompt)
Layer 3 — Usage Limits
Usage under limit? → ALLOW
Usage at limit? → BLOCK (show upgrade prompt)
All three layers checked by one service. Business logic never knows which layer blocked — it just gets true or false.
// Single call anywhere in codebase
entitlementService.hasAccess(kitchenId, Feature.KDS_DISPLAY);
entitlementService.canPerform(kitchenId, Action.CREATE_ORDER);
limitService.canAddMenuItem(kitchenId);
6.2 Feature → Plan Mapping
CORE (STARTER — always on):
basic_menu, order_management, mobile_notifications,
basic_payments, operating_hours, order_history_30d,
table_qr_single, mobile_app_channel
CHANNELS (GROWING+):
pos_access, kiosk_channel, table_qr_unlimited,
whatsapp_bot, receipt_printer, kitchen_printer
PAYMENTS (GROWING+):
card_payments, cash_handling, kitchen_wallet
KITCHEN OPS (PROFESSIONAL+):
stations, kds_display, expeditor_mode, drive_through, tabs,
table_management, staff_roles_permissions
INSIGHTS (PROFESSIONAL+):
advanced_reports, customer_insights, order_history_full
SCALE (ENTERPRISE):
multi_location, central_menu, consolidated_reports,
api_access, white_label, inventory_management
Part 7: Transaction Split Architecture
7.1 The Two Flags That Drive Every Split
boolean chargeCommission =
order.channel == APP || order.channel == WHATSAPP;
boolean chargeDeliveryMargin =
order.fulfillmentType == DELIVERY &&
order.deliveryProvider == JIKOXPRESS_DASHERS;
These two flags determine exactly how money is split on every order. No hardcoding per kitchen. Universal.
7.2 Split Scenarios
Scenario 1 — POS Dine-in (subscription only, no per-order split)
Food value: TZS 15,000
Kitchen gets: TZS 15,000 (100%)
Platform earns: TZS 0 per order
(earns via monthly subscription separately)
Processing margin: TZS 75 (0.5% on transaction)
Scenario 2 — App Pickup (commission applies)
Food value: TZS 15,000
Commission (10%): TZS 1,500 → REVENUE_MARKETPLACE_COMMISSION
Kitchen gets: TZS 13,500 → kitchen settlement
Processing margin: TZS 75 → REVENUE_PROCESSING_MARGIN
Scenario 3 — App + Dasher Delivery (all splits)
Food value: TZS 15,000
Delivery fee: TZS 2,500 (see delivery fee formula)
Total collected: TZS 17,500
↓
Commission (10%): TZS 1,500 → REVENUE_MARKETPLACE_COMMISSION
Kitchen gets: TZS 13,500 → kitchen settlement
Dasher earning (70%): TZS 1,750 → DasherWalletEntity
Platform delivery (30%): TZS 750 → REVENUE_DELIVERY_MARGIN
Processing margin: TZS 75 → REVENUE_PROCESSING_MARGIN
Platform total earned: TZS 2,325
Kitchen nets: TZS 13,500
Dasher gets: TZS 1,750
7.3 TransactionSplitEntity Records Per Order
Every order that involves money generates split records:
Order #47 — App + Dasher Delivery
SplitRecord 1:
type: KITCHEN_EARNING
amount: TZS 13,500
destination: kitchen_settlement_ledger
SplitRecord 2:
type: PLATFORM_COMMISSION
amount: TZS 1,500
destination: REVENUE_MARKETPLACE_COMMISSION
SplitRecord 3:
type: DASHER_EARNING
amount: TZS 1,750
destination: dasher_wallet
SplitRecord 4:
type: PLATFORM_DELIVERY_MARGIN
amount: TZS 750
destination: REVENUE_DELIVERY_MARGIN
SplitRecord 5:
type: PROCESSING_MARGIN
amount: TZS 75
destination: REVENUE_PROCESSING_MARGIN
Total splits always equal total collected. Double-entry stays balanced.
7.4 Revenue Ledger Accounts
REVENUE_SUBSCRIPTION_FEES ← monthly plan payments
REVENUE_MARKETPLACE_COMMISSION ← 10% on app/WhatsApp orders
REVENUE_DELIVERY_MARGIN ← 30% of delivery fee
REVENUE_PROCESSING_MARGIN ← 0.5% spread on all transactions
LIABILITY_DASHER_WALLETS ← accumulated Dasher earnings (owed to drivers)
LIABILITY_KITCHEN_SETTLEMENTS ← kitchen earnings pending payout
ASSET_DELIVERY_POOL ← delivery fees collected, not yet split
Part 8: Delivery System & Fee Model
8.1 JikoXpress Dashers — Internal Fleet
JikoXpress owns the delivery operation. No third-party providers in v1.
Why own the fleet:
- Control the full customer experience end-to-end
- Own the delivery margin (not shared with Bolt/Uber)
- Dasher quality directly reflects on JikoXpress brand
- Build competitive advantage — "Dashers are faster and cheaper"
8.2 Delivery Fee Formula
The customer delivery fee is calculated from the Dasher cost outward, not arbitrarily:
Dasher earning = baseFee + (pricePerKm × distanceKm)
Delivery fee = Dasher earning × (1 + platformMarginRate)
Final fee = round to nearest TZS 100
Config values (adjustable by admin):
baseFee: TZS 1,000
pricePerKm: TZS 150
platformMarginRate: 0.30 (30%)
roundingUnit: 100
Examples:
1km: Dasher TZS 1,150 → Fee TZS 1,495 → Customer pays TZS 1,500
3km: Dasher TZS 1,450 → Fee TZS 1,885 → Customer pays TZS 1,900
5km: Dasher TZS 1,750 → Fee TZS 2,275 → Customer pays TZS 2,300
8km: Dasher TZS 2,200 → Fee TZS 2,860 → Customer pays TZS 2,900
8.3 Delivery Fee Split
Customer pays delivery fee
↓
Dasher share: 70% of fee (always)
Platform share: 30% of fee
Minimum Dasher: TZS 1,000 (floor — protects very short trips)
8.4 Dasher Payout
Dasher completes delivery
↓
Earning added to DasherWalletEntity instantly
↓
Dasher sees real-time balance in app
↓
Daily or on-demand withdrawal to:
M-Pesa / Tigo Pesa / Airtel Money
Part 9: Dasher App Psychology & UX Flow
9.1 The Three Questions Every Driver Asks
When an order pops, every Dasher makes a split-second decision based on exactly three things:
1. How much will I earn?
2. How far do I have to go?
3. Is it worth my time?
Every screen must answer these three questions instantly. Nothing else matters at the moment of decision.
9.2 Screen 1 — Order Notification (The Pop-up)
┌─────────────────────────────────────────┐
│ 🛵 NEW DELIVERY │
│ │
│ TZS 1,750 │ ← earnings FIRST, biggest font
│ your earning │
│ │
│ ├── 📍 0.8km to kitchen │ ← distance to pickup
│ └── 🏠 2.3km to customer │ ← distance to drop-off
│ │
│ Est. 18 mins total │ ← time commitment
│ │
│ ████████████░░░ 12s │ ← countdown timer
│ │
│ [ACCEPT ORDER] │
└─────────────────────────────────────────┘
Design decisions:
- Earnings shown first, largest — this is what drives acceptance
- No restaurant name — prevents bias (driver shouldn't reject based on kitchen)
- No customer name — privacy
- 12-second timer — sweet spot (5s = panic, 30s = overthinking)
- Single button — no friction on accept
Timer expiry behavior:
No response in 12s → auto-decline for this Dasher
→ Order sent to next nearest available Dasher
→ No penalty for first miss
→ 3 consecutive misses → system marks Dasher as "away" automatically
9.3 Screen 2 — After Accept (Full Details Unlock)
┌─────────────────────────────────────────┐
│ ✅ Order Accepted! │
│ │
│ PICK UP │
│ Mama Lishe Downtown │
│ Msimbazi Street, Dar │
│ 📍 0.8km from you │
│ [NAVIGATE] │
│ │
│ ───────────────────────────────────── │
│ ORDER SUMMARY │
│ 1× Ugali + Samaki │
│ 1× Pilau │
│ ───────────────────────────────────── │
│ │
│ DROP OFF │
│ Mlimani City Area, Near Gate 2 │
│ 📍 2.3km from kitchen │
│ [NAVIGATE] │
│ │
│ Your earning: TZS 1,750 │
│ │
│ [ARRIVED AT KITCHEN] │
└─────────────────────────────────────────┘
9.4 Screen 3 — At Kitchen (Pickup Verification)
┌─────────────────────────────────────────┐
│ 📦 PICK UP │
│ │
│ Show this to kitchen staff: │
│ │
│ ┌─────────────────────────────────┐ │
│ │ │ │
│ │ ORDER #47 │ │
│ │ Dasher: John M. │ │
│ │ │ │
│ │ ████████████████ │ │
│ │ (QR code) │ │
│ └─────────────────────────────────┘ │
│ │
│ Kitchen scans → confirms → you proceed │
│ │
│ [FOOD PICKED UP] │
└─────────────────────────────────────────┘
QR verification prevents wrong Dasher picking up wrong order. Kitchen scans, confirms, Dasher proceeds.
9.5 Screen 4 — En Route to Customer
┌─────────────────────────────────────────┐
│ 🏍️ EN ROUTE │
│ │
│ Delivering to: │
│ Mlimani City Area, Near Gate 2 │
│ │
│ Customer note: │
│ "Call when you arrive, gate is locked" │
│ │
│ 📞 Call Customer │
│ │
│ [NAVIGATE] │
│ │
│ [ARRIVED AT CUSTOMER] │
└─────────────────────────────────────────┘
9.6 Screen 5 — Delivery Complete (The Reward Screen)
┌─────────────────────────────────────────┐
│ 🎉 Delivery Complete! │
│ │
│ TZS 1,750 added to your wallet │
│ │
│ Today's earnings: TZS 8,750 │
│ Deliveries today: 5 │
│ │
│ ───────────────────────────────────── │
│ │
│ Keep it up! 3 more deliveries │
│ to hit your daily bonus 🔥 │
│ │
│ [GO ONLINE] │
└─────────────────────────────────────────┘
The daily bonus progress is deliberate gamification — keeps Dashers online longer and drives supply during peak hours.
9.7 Daily Bonus Structure (Dasher Retention)
8 deliveries/day → TZS 2,000 bonus
12 deliveries/day → TZS 5,000 bonus
15 deliveries/day → TZS 8,000 bonus + "Top Dasher" badge
Dashers chase the bonus. You get supply when you need it most.
Part 10: Dasher Delivery Status Flow
ORDER PLACED
↓
FINDING_DASHER → System dispatches to nearest available Dasher
↓
DASHER_ASSIGNED → Dasher accepted, heading to kitchen
↓
DASHER_AT_KITCHEN → Dasher arrived, awaiting pickup verification
↓
PICKED_UP → QR scanned, food confirmed, en route to customer
↓
IN_TRANSIT → Real-time location tracking active
↓
DASHER_AT_CUSTOMER → Arrived at drop-off location
↓
DELIVERED → Order complete, Dasher earning posted to wallet
Failure states:
NO_DASHER_AVAILABLE → Alert admin, manual assign or fallback
DASHER_CANCELLED → Re-dispatch to next available Dasher
DELIVERY_FAILED → Escalate, refund flow triggered
Part 11: Offer System
11.1 Offer Types
Offers can be applied to subscriptions or per-order:
| Type | How It Works | Example |
|---|---|---|
| PERCENT_DISCOUNT | % off subscription price | 30% off for 3 months |
| FIXED_DISCOUNT | Fixed amount off | TZS 10,000 off first month |
| FREE_MONTHS | N months free | 2 months free on annual plan |
| TRIAL_EXTENSION | Extend trial duration | +7 days on trial |
| SAVE_OFFER | Shown on cancel/downgrade | Stay 1 month at 50% off |
11.2 Save Flow Offer (Churn Prevention)
Kitchen requests cancel or downgrade
↓
System shows save offer:
"Stay on PROFESSIONAL for 1 month at 50% off?"
[Accept] [Proceed anyway]
↓
[Accept] → offer applied, billed at 50% next cycle, full price after
[Proceed] → scheduled for end of cycle
11.3 Offer Rules
- Offers have budget limits (max total discount)
- Offers have expiry dates
- Offers have usage limits (per kitchen, global)
- One active offer per subscription at a time
- Offers track how many billing cycles they've been applied
- When cycles run out, full price resumes automatically
Part 12: Entity Overview
12.1 Subscription Package
subscription/
├── entity/
│ ├── SubscriptionPlanEntity ← plan catalog (STARTER, GROWING, PRO, ENTERPRISE)
│ ├── PlanFeatureEntity ← plan → feature mapping
│ ├── PlanLimitEntity ← plan → limit mapping
│ ├── PlanPricingEntity ← plan → price per billing cycle
│ ├── SubscriptionEntity ← per-kitchen live subscription
│ ├── SubscriptionUsageEntity ← current period usage tracking
│ ├── SubscriptionPaymentEntity ← each billing event
│ ├── SubscriptionTrialEntity ← trial record (one per account)
│ └── SubscriptionScheduledChangeEntity ← pending downgrade/cancel
│
├── enums/
│ ├── SubscriptionStatus ← TRIALING, ACTIVE, PAST_DUE, SUSPENDED, CANCELLED
│ ├── BillingCycle ← WEEKLY, MONTHLY, ANNUAL, CUSTOM
│ └── PlanTier ← STARTER, GROWING, PROFESSIONAL, ENTERPRISE
│
└── service/
├── EntitlementService ← the access gate (most critical)
├── LimitService ← usage limit enforcement
├── SubscriptionService ← lifecycle management
└── SubscriptionBillingService ← renewals, dunning, trial expiry
12.2 Dasher Package
dasher_service/
├── driver/ ← profiles, onboarding, status, ratings
├── dispatch/ ← order assignment, routing, fallback
├── tracking/ ← real-time location, ETA
├── earnings/ ← DasherWalletEntity, per-trip records
└── payout/ ← settlement to M-Pesa / Tigo / Airtel
12.3 Financial Package (delivery additions)
wallet/
├── CustomerWalletEntity
├── KitchenWalletEntity
└── DasherWalletEntity ← Dasher accumulated earnings
ledger/
├── LedgerAccountEntity (includes delivery-specific accounts)
└── JournalEntryEntity
Part 13: The Business Model in One View
┌─────────────────────────────────────────────────────────────────┐
│ JIKOXPRESS EARNS FROM │
├─────────────────────────────────────────────────────────────────┤
│ │
│ EVERY KITCHEN (subscription) │
│ └── Monthly fee for using the management platform │
│ STARTER: TZS 0 | GROWING: TZS X | PRO: TZS XX │
│ │
│ EVERY APP / WHATSAPP ORDER (commission) │
│ └── 10% of food value on orders JikoXpress generated │
│ Kitchen's own customers (POS/Kiosk) = zero commission │
│ │
│ EVERY DASHER DELIVERY (delivery margin) │
│ └── 30% of delivery fee on all Dasher deliveries │
│ Dasher gets 70% — "we share with you, not take from you" │
│ │
│ EVERY TRANSACTION (processing margin) │
│ └── ~0.5% spread on all M-Pesa / card transactions │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ STARTER kitchen, 50 app orders/month, avg TZS 10,000: │
│ Commission: 50 × 10,000 × 10% = TZS 50,000/month │
│ Subscription: TZS 0 │
│ Platform earns TZS 50,000 from a "free" kitchen │
│ │
│ PROFESSIONAL kitchen, 500 app orders + 100 Dasher deliveries: │
│ Subscription: TZS 150,000 │
│ Commission: 500 × 10,000 × 10% = TZS 500,000 │
│ Delivery: 100 × 2,000 × 30% = TZS 60,000 │
│ Platform earns TZS 710,000/month from one kitchen │
│ │
└─────────────────────────────────────────────────────────────────┘
Appendix A: Subscription Status Reference
| Status | Kitchen Can Login | Can Take Orders | Paid Features | Action Required |
|---|---|---|---|---|
| TRIALING | ✅ | ✅ | ✅ (PROFESSIONAL) | None — enjoy trial |
| ACTIVE | ✅ | ✅ | ✅ (per plan) | None |
| PAST_DUE | ✅ | ✅ | ✅ (grace) | Update payment |
| SUSPENDED | ✅ | ❌ | ❌ | Pay to resume |
| CANCELLED | ✅ | ✅ (STARTER) | ❌ (STARTER only) | Re-subscribe |
Appendix B: Dunning Timeline Reference
| Day | Event | Kitchen Status | Action |
|---|---|---|---|
| 0 | Payment fails | PAST_DUE | Push + WhatsApp + retry |
| 1 | Retry | PAST_DUE | Silent retry |
| 3 | Still failing | PAST_DUE | Push + WhatsApp + retry |
| 5 | Retry | PAST_DUE | Silent retry |
| 7 | Final warning | PAST_DUE | Push + WhatsApp + retry |
| 8 | All retries exhausted | SUSPENDED | Limited mode |
| 15 | Grace period over | CANCELLED | Falls to STARTER |
Appendix C: Decision Log
| Decision | Choice | Rationale |
|---|---|---|
| STARTER pricing | Free forever | Acquisition tool — earns via commission anyway |
| Trial plan | PROFESSIONAL (not GROWING) | Show the ceiling — max value drives conversion |
| Trial duration | 3 days | Short enough to create urgency, long enough to experience value |
| Trial recurrence | Once automatic + admin re-grant | Prevents abuse, keeps re-engagement tool |
| Upgrade timing | Immediate | Kitchen gets value now, better experience |
| Downgrade timing | End of cycle | Fair, reduces panic cancellations |
| Failed payment lockout | Soft lock (limited mode) | Hard lockout causes permanent churn |
| Data on downgrade | Soft-lock, never delete | Re-upgrade restores everything — retention lever |
| Auto-select on limit drop | 20 most recently active | Kitchen stays live immediately, no downtime |
| Commission scope | App + WhatsApp only | Fair — charge for demand we generated |
| Delivery model | Internal Dashers only (v1) | Own the margin, own the experience |
| Delivery fee basis | Dasher cost + 30% margin | Fee always covers Dasher, platform never loses |
| Dasher share | 70% of delivery fee | Fair split, drives Dasher supply |
| Dasher notification | Earnings first, 12s timer | Psychology — answer the 3 questions instantly |
| Dunning channel | Push + WhatsApp (not email) | East Africa mobile-first — WhatsApp beats email |
| Service fee on pickup/dine-in | No | Price sensitivity — avoid customer leakage to WhatsApp direct |
| Delivery fee from customer | Yes | Universal expectation, accepted without friction |
End of Document JikoXpress Pro — Payment, Subscription & Business Model Architecture v1.0
No comments to display
No comments to display