Sponsor Code System Domain

A comprehensive guide to the sponsor/coverage system that enables NGO, government, insurance, and employer healthcare coverage.

The Big Picture

Healthcare in developing countries often involves multiple payers beyond the patient themselves. NGOs provide free or subsidized care, governments run public health programs, employers offer health plans, and insurance companies provide coverage. The Sponsor Code System provides a unified way to handle all these payment sources.

At its core, the system is simple: someone gives the patient a code, the clinic applies the code, and the sponsor covers part or all of the bill.

Core Concepts

Sponsor

A Sponsor is any entity that pays for patient care. This could be:

Type	Examples
NGO	Red Cross, MSF, local charities
Government	Ministry of Health, public health programs
Insurance	Private insurance companies
Employer	Corporate health plans, union coverage

Each sponsor has contact information, contract details, and can have multiple codes with different coverage rules.

Sponsor Code

A Sponsor Code is what patients present to receive coverage. Each code has:

Discount Rules - How much is covered (percentage, fixed amount, or full coverage)
Usage Limits - Maximum number of times the code can be used
Balance Limits - Maximum total amount the sponsor will cover
Validity Period - When the code is active
Patient Assignment - Optionally assigned to a specific patient

Sponsor Service Rates (Fee Schedule)

NGOs and sponsors often negotiate fixed rates per service. For example:

Service	Clinic Price	NGO Rate
Consultation	15,000 MMK	10,000 MMK
Lab - Malaria	8,000 MMK	8,000 MMK
X-Ray	25,000 MMK	20,000 MMK

When a service rate exists, the sponsor pays exactly that amount regardless of the clinic's standard price.

Sponsor Claims

Every time a sponsor code is applied, a claim is created. Claims track:

How much was billed
How much the sponsor covered
How much the patient paid
Status for reconciliation (recorded → submitted → approved → paid)

Discount Types

Type	How It Works	Example
Percentage	Sponsor pays X% of the bill	80% → Sponsor pays 8,000 of 10,000
Fixed Amount	Sponsor pays exactly X amount	5,000 off → Sponsor pays 5,000 of 10,000
Full Coverage	Sponsor pays 100%	Patient pays nothing

When a service rate exists for the specific service, that takes priority over the code's general discount.

Workflow

1. Setup (Administrator)

Clinic Admin creates:
    ↓
1. Sponsor (e.g., "Red Cross Myanmar")
    ↓
2. Sponsor Codes (e.g., "RC-2024-001" with 100% coverage, 10 uses)
    ↓
3. Service Rates (optional - fixed prices per service)

2. At Point of Care

Patient presents code "RC-2024-001"
    ↓
Front desk enters code in system
    ↓
System validates:
    ├── Code exists? ✓
    ├── Status active? ✓
    ├── Not expired? ✓
    ├── Usage limit not exceeded? ✓
    └── (If assigned) Correct patient? ✓
    ↓
Proceed with visit, coverage noted

3. Billing

Finalize encounter → Generate invoice
    ↓
Apply sponsor code to invoice
    ↓
System calculates:
    ├── Check for service rates (fixed amounts)
    ├── Otherwise apply code's discount
    ├── Respect balance limits
    └── Create claim record
    ↓
Invoice shows breakdown:
    ├── Total: 50,000 MMK
    ├── Sponsor Covers: 40,000 MMK
    └── Patient Pays: 10,000 MMK

4. Reconciliation

Monthly/weekly:
    ↓
Admin reviews claims for sponsor
    ↓
Submit claims to sponsor (mark as "submitted")
    ↓
Sponsor approves and pays
    ↓
Mark claims as "paid"

Coverage Calculation

def calculate_coverage(bill_amount, sponsor_code, service_code=None):
    # 1. Check for fee schedule rate first
    if service_code and sponsor_has_rate(service_code):
        sponsor_rate = get_rate(service_code)
        sponsor_covers = min(sponsor_rate, bill_amount)
        patient_pays = bill_amount - sponsor_covers
        return (sponsor_covers, patient_pays)
    
    # 2. Apply code's general discount
    if code.discount_type == "full_coverage":
        return (bill_amount, 0)
    
    elif code.discount_type == "percentage":
        discount = bill_amount * (code.discount_value / 100)
        return (discount, bill_amount - discount)
    
    elif code.discount_type == "fixed_amount":
        discount = min(code.discount_value, bill_amount)
        return (discount, bill_amount - discount)

Database Schema

Column	Type	Description
id	VARCHAR (PK)	Sponsor ID (spo prefix)
organization_id	VARCHAR (FK)	Clinic/organization
name	VARCHAR	Sponsor name
sponsor_type	ENUM	ngo, government, insurance, employer
contact_name	VARCHAR	Contact person
contact_phone	VARCHAR	Phone
contact_email	VARCHAR	Email
is_active	BOOLEAN	Active status

sponsor_codes

Column	Type	Description
id	VARCHAR (PK)	Code ID (spc prefix)
sponsor_id	VARCHAR (FK)	Parent sponsor
code	VARCHAR	The code patients present
discount_type	ENUM	percentage, fixed_amount, full_coverage
discount_value	DECIMAL	Discount amount/percentage
usage_limit	INTEGER	Max uses (null = unlimited)
times_used	INTEGER	Current usage count
balance_limit	DECIMAL	Max amount (null = unlimited)
balance_used	DECIMAL	Amount already claimed
valid_until	DATE	Expiry date
patient_id	VARCHAR (FK)	If assigned to specific patient
status	ENUM	active, exhausted, expired, revoked

sponsor_service_rates

Column	Type	Description
id	VARCHAR (PK)	Rate ID (ssr prefix)
sponsor_id	VARCHAR (FK)	Parent sponsor
service_code	VARCHAR	Service identifier
service_name	VARCHAR	Service display name
sponsor_rate	DECIMAL	Fixed amount sponsor pays

sponsor_claims

Column	Type	Description
id	VARCHAR (PK)	Claim ID (scl prefix)
sponsor_code_id	VARCHAR (FK)	Code used
patient_id	VARCHAR (FK)	Patient
invoice_id	VARCHAR (FK)	Related invoice
original_amount	DECIMAL	Bill before discount
sponsor_covers	DECIMAL	Amount sponsor pays
patient_pays	DECIMAL	Amount patient pays
status	ENUM	recorded, submitted, approved, paid, rejected

API Endpoints

Sponsor Management

POST   /api/sponsors              # Create sponsor
GET    /api/sponsors              # List sponsors
GET    /api/sponsors/{id}         # Get sponsor
PATCH  /api/sponsors/{id}         # Update sponsor
GET    /api/sponsors/{id}/summary # Get sponsor stats

Sponsor Codes

POST   /api/sponsors/codes               # Create code
GET    /api/sponsors/codes               # List codes
GET    /api/sponsors/codes/{id}          # Get code by ID
GET    /api/sponsors/codes/lookup/{code} # Lookup by code string
PATCH  /api/sponsors/codes/{id}          # Update code

Code Validation & Application

POST   /api/sponsors/codes/validate  # Check if code is valid
POST   /api/sponsors/codes/apply     # Apply code to invoice

Service Rates

POST   /api/sponsors/{id}/rates      # Add service rate
GET    /api/sponsors/{id}/rates      # List rates for sponsor
PATCH  /api/sponsors/rates/{id}      # Update rate
DELETE /api/sponsors/rates/{id}      # Remove rate

Claims

GET    /api/sponsors/claims                  # List claims
PATCH  /api/sponsors/claims/{id}/status      # Update claim status

Permissions

Permission	Description	Roles
`sponsor.manage`	Create/edit sponsors, codes, rates	SUPERUSER, ADMIN, MANAGER
`sponsor.code.apply`	Validate and apply codes at billing	SUPERUSER, ADMIN, MANAGER, DOCTOR, NURSE, RECEPTIONIST
`sponsor.claims.view`	View and manage claim records	SUPERUSER, ADMIN, MANAGER, DOCTOR

Integration with Billing

The sponsor system integrates with the existing billing module:

Invoice - Can reference a sponsor code and track sponsor discount
Payment - Patient portion is collected as a normal payment
Transaction Ledger - Records both sponsor coverage and patient payment

Example Scenarios

Scenario 1: NGO Full Coverage

Red Cross creates code "RC-FREE-001" with full coverage, 50 uses
Patient presents code at clinic
Clinic validates code → Valid, 45 uses remaining
Visit completed, invoice generated: 25,000 MMK
Code applied: Sponsor covers 25,000, Patient pays 0
Claim recorded for Red Cross reconciliation

Scenario 2: Insurance with 80% Coverage

Insurance company creates code "INS-GOLD-999" with 80% coverage
Patient has bill of 100,000 MMK
Code applied: Sponsor covers 80,000, Patient pays 20,000
Patient pays their 20,000 copay
Clinic submits claim to insurance for 80,000

Scenario 3: NGO with Fee Schedule

MSF negotiates rates: Consultation = 10,000, Lab = 5,000
Patient uses MSF code, gets consultation (clinic price 15,000) + lab (8,000)
Coverage calculation:
- Consultation: MSF pays 10,000 (rate), patient pays 5,000
- Lab: MSF pays 5,000 (rate), patient pays 3,000
- Total: MSF pays 15,000, Patient pays 8,000

Key Takeaways

Simple but Extensible - Three discount types cover most use cases, with fee schedules for complex negotiations
Usage Tracking - Every code application is logged with full amounts for reconciliation
Multi-Payer Ready - Supports NGO, government, insurance, and employer payers under one system
Billing Integration - Works seamlessly with existing invoice and payment workflows
Permission-Based - Different roles have appropriate access to manage vs. apply codes

Document created: December 2025

Product User Guide

Guides