# 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) | ✅ | ✅ | ✅ |
| WhatsApp | Pickup | ✅ | ✅ | ❌ |
| WhatsApp | 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:**
- Basic menu (up to 20 items)
- Order management (receive, accept, prepare, complete)
- Mobile app only
- Mobile money payments (USSD)
- Table QR (1 table)
- Operating hours scheduling
- Order history (30 days)
- Basic push notifications

**Limits:**
- 20 menu items
- 100 orders/month
- 1 staff account (owner only)
- 1 location

---

#### 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):**
- Unlimited menu items
- POS access (desktop/tablet)
- Kiosk channel
- Table QR (unlimited)
- WhatsApp bot ordering
- Receipt & kitchen printer support
- Card payments + cash handling
- Basic sales reports
- Order history (1 year)

**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

**Menu Items (limit: 20)**

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

```java
// 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

```java
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)
```

**Framing:** "We share 70% of every delivery fee with you" — not "we take 30% commission."

### 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*