Skip to content

Campaign Management & Inventory Module

Overview

The Campaign Management module enables marketing campaigns, promotional offers, vouchers, referral programs, and loyalty points. The Inventory module tracks physical and digital inventory with stock management and movement tracking.

API Prefixes: /api/v1/campaign and /api/v1/inventory

Route Verification Status

  • Source Routers: app/api/v1/endpoints/campaign.py, app/api/v1/endpoints/inventory.py
  • Live Route Count: 41 (campaign: 28, inventory: 13)
  • Verification State: Verified (2026-06-28)
  • Canonical Tracking: docs/API_ROUTE_DOCUMENTATION_TODO.md
  • Verification Method: Route decorators extracted from source routers above.

Key Features

Campaign Management

1. Campaign Types

  • Marketing Campaigns: Promotional offers and discounts
  • Referral Campaigns: Customer referral programs with incentives
  • Fee Waiver Campaigns: Temporary fee removal campaigns
  • Promotional Vouchers: Discount codes and coupons
  • Loyalty Programs: Points-based rewards system

2. Campaign Lifecycle

  • Create and configure campaigns
  • Campaign scheduling (start/end dates)
  • Target audience segmentation
  • Campaign pause and resume
  • Campaign performance tracking
  • Campaign expiration management

3. Voucher Management

  • Generate promotional codes
  • Track voucher redemption
  • Validity period management
  • Single vs. batch code generation
  • Voucher classification and categorization

4. Referral Programs

  • Customer referral tracking
  • Referral incentive distribution
  • Referral link generation
  • Bulk referral invitations
  • Referral code management

5. Loyalty Points System

  • Earn points on transactions
  • Configurable earning rates
  • Points redemption for rewards
  • Points expiry management
  • Points balance tracking

Inventory Management

1. Inventory Tracking

  • Physical and digital inventory
  • Stock level management
  • Stock location tracking
  • Real-time inventory updates
  • Inventory reconciliation

2. Inventory Movement

  • Track inventory movements (in/out)
  • Link to transactions (auto-deduct on sale)
  • Inventory transfers between locations
  • Adjustment records
  • Movement history

3. Stock Location Management

  • Define storage locations
  • Location capacity tracking
  • Multi-location inventory
  • Location-based stock allocation

4. Inventory Types

  • Product inventory
  • Device/Terminal inventory
  • Consumable supplies
  • Digital goods inventory

API Endpoints (Verified Against Live Router)

For complete endpoint inventories (method, effective path, source line), use: - docs/API_ROUTE_LIVE_REFERENCE.md -> section campaign.py (28 routes) - docs/API_ROUTE_LIVE_REFERENCE.md -> section inventory.py (13 routes)

Permission Dependency Notes (Verified)

Confirmed explicit permission checks in campaign.py include: - Campaign lifecycle: add_campaign, edit_campaign, pause_campaign, resume_campaign, get_campaign, fetch_campaign. - Rewards and vouchers: fetch_redeemed, fetch_reward, fetch_pointstransaction, fetch_voucher, upload_voucher, summary_points, redeem_points, activity_points, rates_points, fetch_redemption. - Referral operations: get_referral_stats, fetch_referral, share_referral, view_referral_fraud, view_referral_stats, flag_suspicious_referral.

Operational note: - Some campaign endpoints currently include empty placeholders (permission_required("")) and should be made explicit.

Confirmed explicit permission checks in inventory.py include: - Inventory lifecycle and lookup: add_inventory, get_inventory, edit_inventory, fetch_inventory. - Stock locations and assignment: get_stocklocation, add_stocklocation, edit_stocklocation, assign_inventory, fetch_stocklocation, fetch_assignment, get_assignment. - Catalog/movement: fetch_inventorykind, fetch_movement.

Standard Error Response Matrix

{
  "status_code": 400,
  "error_code": "CAMPAIGN_INVENTORY_ERROR",
  "message": "Human-readable summary",
  "details": {}
}

Common mappings: - 400 invalid campaign/inventory rule or state transition. - 401 unauthenticated request. - 403 permission denied. - 404 campaign/voucher/referral/inventory resource not found. - 409 conflicting campaign lifecycle or stock assignment state. - 422 schema validation failure. - 429 throttled request. - 500 internal campaign/inventory processing error.

Database Models

Campaign Models

  • Campaign: Campaign record with dates, target, rules
  • CampaignRun: Campaign execution instance
  • CampaignSegment: Target audience specification
  • Voucher: Promotional code/voucher
  • VoucherRedemption: Redemption tracking

Referral Models

  • ReferralProgram: Program configuration
  • ReferralInvitation: Referral invites sent
  • ReferralRegistration: Referred customer signup
  • ReferralReward: Reward tracking

Loyalty Models

  • LoyaltyProgram: Loyalty program configuration
  • LoyaltyPoints: Points balance tracking
  • PointsTransaction: Points earn/redeem history
  • PointsRedemption: Redemption records

Inventory Models

  • Inventory: Inventory item record
  • InventoryLocation: Storage location
  • InventoryAssignment: Item assignment to location
  • InventoryMovement: Inventory movement tracking
  • InventoryTransaction: Link to transaction (auto-deduct)

Campaign Types & Configuration

Marketing Campaign

{
  "name": "Summer Promotion",
  "type": "marketing",
  "description": "20% off all transfers",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "target_segment": "active_customers",
  "offer": {
    "type": "discount_percentage",
    "value": 20,
    "max_discount": 500
  },
  "budget_cap": 100000,
  "status": "active"
}

Referral Campaign

{
  "name": "Friend Referral Bonus",
  "type": "referral",
  "description": "Earn 500 ZMW for each friend signup",
  "referrer_reward": 500,
  "referee_reward": 200,
  "max_referrals": 10,
  "expiry_days": 90,
  "status": "active"
}

Voucher Configuration

{
  "code": "SUMMER20",
  "campaign_id": "campaign_123",
  "discount_percent": 20,
  "discount_amount": null,
  "max_uses": 1000,
  "uses": 450,
  "valid_from": "2024-06-01",
  "valid_until": "2024-08-31",
  "min_transaction": 1000,
  "status": "active"
}

Loyalty Points System

Points Earning Rules

Transaction Type          Points Per Unit
P2P Transfer             1 point per 100 ZMW
Merchant Payment         2 points per 100 ZMW
Bill Payment             1.5 points per 100 ZMW
Loan Repayment           3 points per 100 ZMW
Card Purchase            2 points per 100 ZMW
Referral Reward          500 points per referral

Points Redemption Options

Redemption Option        Points Required
Cash Back                100 points = 100 ZMW
Transaction Fee Waiver   50 points = next transfer free
Bill Payment Discount    75 points = 25% off bill
Airtime Top-up           50 points = 500 ZMW airtime

Campaign Workflows

Creating & Running a Campaign

1. Create Campaign
   ├─ Define campaign name and type
   ├─ Set target audience (segment)
   ├─ Configure offer (discount, incentive)
   ├─ Set date range
   └─ Set budget cap

2. Pre-Launch Testing
   ├─ Test with sample customers
   ├─ Verify offer application
   ├─ Check budget tracking
   └─ Validate communications

3. Launch Campaign
   ├─ Activate campaign
   ├─ Send notifications
   ├─ Start tracking metrics
   └─ Monitor performance

4. Active Management
   ├─ Track redemptions
   ├─ Monitor budget spend
   ├─ Pause if needed
   ├─ Adjust targeting if needed
   └─ Send reminder notifications

5. Campaign Closure
   ├─ Set end date
   ├─ Final metrics calculation
   ├─ Process final rewards
   ├─ Archive campaign data
   └─ Generate final report

Referral Program Flow

1. Referrer Initiates
   ├─ Request referral code/link
   ├─ System generates unique code
   ├─ Send code to referrer
   └─ Referrer shares with friends

2. Referee Signs Up
   ├─ Use referrer's code during registration
   ├─ Complete KYC verification
   ├─ First transaction completed
   └─ Referral validated

3. Reward Distribution
   ├─ Referrer gets reward (e.g., 500 ZMW)
   ├─ Referee gets welcome bonus (e.g., 200 ZMW)
   ├─ Rewards added to wallets
   └─ Confirmation sent to both

4. Tracking
   ├─ Track successful referrals
   ├─ Enforce max referral limit
   ├─ Track referral revenue share
   └─ Generate referral reports

Controllers & Business Logic

Campaign Controllers

  • controller/campaign.py: Campaign management
  • create_campaign(): Create new campaign
  • apply_campaign_offer(): Apply discount/reward
  • track_campaign_metrics(): Calculate KPIs

  • distribute_rewards(): Process rewards

  • controller/voucher.py: Voucher management

  • generate_voucher_code(): Create codes
  • validate_voucher(): Verify voucher

  • redeem_voucher(): Apply and track redemption

  • controller/referral.py: Referral programs

  • create_referral(): Initiate referral
  • validate_referee(): Verify new customer

  • distribute_referral_rewards(): Payout rewards

  • controller/loyalty.py: Loyalty points

  • earn_points(): Add points on transaction
  • redeem_points(): Process redemption
  • track_point_balance(): Maintain balance

Inventory Controllers

  • controller/inventory.py: Inventory operations
  • create_inventory(): Create inventory item
  • update_stock(): Update quantity
  • track_movement(): Log inventory movement

  • auto_deduct_on_transaction(): Deduct on sale

  • controller/inventory_location.py: Location management

  • add_location(): Create storage location
  • assign_inventory(): Assign to location
  • transfer_inventory(): Move between locations

Common Use Cases

1. Running a Promotional Campaign

Admin creates "50% off transfers" campaign
→ Set target: New customers
→ Set validity: 2 weeks
→ Set budget: 50,000 ZMW
→ Launch campaign
→ Customers see offer in app
→ Discounts applied automatically
→ Track budget spend in real-time
→ Campaign ends, metrics generated

2. Voucher Promotion

Generate 1000 voucher codes "SAVE50"
→ Each code = 50 ZMW discount
→ Valid for next 30 days
→ Share via SMS/Email/Social
→ Customer enters code in app
→ Discount applied to next transaction
→ Track redemption rate

3. Referral Bonus

Customer gets referral code
→ Shares with friend
→ Friend signs up with code
→ Friend completes KYC
→ Friend makes first transaction
→ Referrer gets 500 ZMW bonus
→ Friend gets 200 ZMW welcome bonus
→ Both rewards added to wallets

4. Inventory Tracking

Buy 100 mobile terminals
→ Create inventory record
→ Assign to central warehouse location
→ Assign 30 to Lusaka store
→ Movement tracked in system
→ Agent requests 5 devices
→ Assign 5 to agent
→ Auto-deduct from inventory
→ Low stock alert when <10 remain

Error Handling

Campaign Errors

  • CAMPAIGN_NOT_FOUND: Campaign doesn't exist
  • CAMPAIGN_INACTIVE: Campaign is paused or expired
  • BUDGET_EXCEEDED: Campaign budget cap reached
  • INVALID_VOUCHER: Voucher code invalid or expired
  • VOUCHER_ALREADY_USED: Single-use voucher already redeemed
  • REFERRAL_LIMIT_EXCEEDED: Max referrals reached
  • INSUFFICIENT_POINTS: Not enough points to redeem

Inventory Errors

  • INSUFFICIENT_STOCK: Not enough inventory available
  • LOCATION_NOT_FOUND: Stock location doesn't exist
  • INVALID_QUANTITY: Negative or invalid quantity
  • MOVEMENT_FAILED: Inventory movement failed

Testing

Campaign Tests

  • Campaign creation and scheduling
  • Offer application and discount calculation
  • Budget tracking and enforcement
  • Voucher generation and redemption
  • Referral reward distribution
  • Points earning and redemption

Inventory Tests

  • Inventory creation and updates
  • Stock location management
  • Inventory movement tracking
  • Auto-deduction on transactions
  • Low stock alerts

Performance Considerations

  1. Campaign Caching: Cache active campaigns
  2. Batch Processing: Process bulk referrals/vouchers
  3. Metrics Aggregation: Pre-calculate campaign metrics
  4. Inventory Indexing: Index on location and item type
  5. Voucher Lookup: Cache valid voucher codes

Integration Points

Campaign Integrations

  • Transaction System: Apply discounts automatically
  • Wallet System: Add/deduct points and bonuses
  • Notification System: Campaign communications
  • Customer Management: Segment targeting
  • Reporting: Campaign analytics

Inventory Integrations

  • Transaction System: Auto-deduct on sale
  • Agent Management: Device provisioning
  • Warehouse Management: Stock transfer requests
  • Reporting: Inventory analytics