Billing Domain - Workflow Narrative

A conversational guide to understanding financial workflows

What is the Billing Domain?

The Billing domain handles the financial side of healthcare - turning clinical services into invoices, recording payments, and tracking patient balances. It's where clinical activity meets revenue management.

Healthcare billing is particularly complex because prices can vary by organization, procedures have different fee schedules, and patients may have outstanding balances across multiple visits.

The Core Entities

Invoices

An invoice is a bill for services rendered. It has a patient, a date, and a list of line items. Each invoice tracks its total amount, amount paid, balance due, and status.

Invoice statuses include:

draft - Still being prepared
pending - Sent to patient, awaiting payment
partial - Some payment received
paid - Fully paid
overdue - Past due date without full payment
cancelled - Voided

Invoice Items

Each line item on an invoice represents a service or product. Items might come from:

Service fees (consultation, procedure charges)
Inventory items (medications, supplies sold)
Custom entries (misc charges)

Each item has a quantity, unit price, discount percentage, and calculated line total.

Payments

Payments record money received. A payment is linked to an invoice and reduces the balance due. Multiple payments can apply to a single invoice (partial payments over time).

Payment methods include cash, card, bank transfer, insurance, and others.

Transaction Ledger

Every financial transaction is recorded in the ledger. This includes invoice creation, payments received, adjustments made, and write-offs. The ledger provides an immutable audit trail of all financial activity.

Creating an Invoice

The Workflow

Invoices are typically created at the end of a clinical encounter. The practitioner has seen the patient, documented the visit, and now the billing process begins.

The BillingService.create_invoice() method accepts invoice data including:

Patient ID
Encounter ID (optional, links to the clinical visit)
Invoice date
Due date
Currency
Any initial notes

Automatic Numbering

Each invoice gets a unique invoice number. The system generates these sequentially within the organization - INV-00001, INV-00002, etc. Custom formats can be configured per organization.

Initial Status

New invoices start in "draft" status. This allows the billing team to review and add items before sending to the patient.

Organization Scoping

Like all data, invoices are scoped to an organization. The organization_id is set from the authenticated user's context.

Adding Invoice Items

From Service Fees

The most common source of invoice items is the service fee schedule. Organizations define their fee schedules with codes, descriptions, and prices.

When adding a service fee to an invoice, add_invoice_item() looks up the fee by code and applies the configured price. The item tracks which service fee it came from.

From Inventory

If the practice sells products (medications, medical supplies), inventory items can be added to invoices. The item tracks the inventory item ID and quantity.

Inventory is decremented when items are invoiced. If insufficient stock exists, the system can warn or block the addition.

Custom Items

Sometimes you need a line item that doesn't fit a predefined service fee. Custom items can be added with freeform descriptions and amounts.

Total Recalculation

Every time an item is added, modified, or removed, the invoice totals are recalculated. The subtotal is the sum of all line items. Discounts reduce the subtotal. Tax might be added based on organization settings. The final total is what the patient owes.

Recording Payments

The Payment Flow

When a patient pays, the create_payment() method records the transaction.

The payment record includes:

Invoice ID (which invoice is being paid)
Amount
Payment method
Payment date
Reference number (check number, transaction ID)
Received by user ID (who processed the payment)

Automatic Balance Update

After recording the payment, the invoice's amount_paid is increased and balance_due is decreased. If balance_due reaches zero, the invoice status changes to "paid".

Partial Payments

If a payment doesn't cover the full balance, the invoice status changes to "partial". Multiple payments can accumulate until the invoice is fully paid.

Overpayment Prevention

The system prevents recording payments that exceed the balance due. If an invoice has a $100 balance, you can't record a $150 payment.

Ledger Entry

Every payment creates a ledger entry. This immutable record shows:

Transaction type: "payment_received"
Amount
Related invoice ID
Related payment ID
Timestamp

The Patient Ledger

Running Balance

Each patient has a financial history. The get_patient_ledger() method returns all transactions for a patient in chronological order. This includes:

Invoice creations (charges)
Payments received
Adjustments
Write-offs

The running balance shows how much the patient owes at any point in time.

Unpaid Invoices

get_unpaid_invoices() filters to show only invoices with outstanding balances. This powers the "patient owes" view that front desk staff check during visits.

Aging

The billing system can categorize unpaid invoices by age:

Current (0-30 days)
30-60 days overdue
60-90 days overdue
90+ days overdue

This aging report helps practices manage their accounts receivable.

Invoice Lifecycle

Draft to Pending

When an invoice is ready to send to the patient, its status changes from "draft" to "pending". This might trigger:

Email notification to the patient
Print job for paper statements
Logging of the sent date

Pending to Partial

When the first payment arrives (but doesn't fully cover the balance), status becomes "partial".

Partial to Paid

Additional payments accumulate. When balance_due reaches zero, status becomes "paid".

Overdue Handling

A background job (cron) checks for invoices past their due date. These are marked "overdue" automatically. This status might trigger:

Late fee addition
Follow-up notifications
Escalation to collections

Cancellation

If an invoice was created in error, it can be cancelled. Cancelled invoices don't show in normal lists and don't count toward patient balances. The ledger still records the cancellation for audit purposes.

Batch Operations

Bulk Item Deletion

Sometimes billing staff need to remove multiple items at once. The delete_invoice_items_batch() method handles this efficiently.

It validates that all items exist and belong to accessible invoices, then deletes them in a single transaction. Affected invoices have their totals recalculated.

Bulk Invoice Updates

For end-of-month processing or bulk status changes, the system supports batch operations. This is more efficient than individual updates when you're processing many records.

Financial Reporting

Invoice Statistics

The billing domain provides aggregated statistics:

Total billed this period
Total collected this period
Outstanding balance across all patients
Payment method breakdown
Average collection time

These statistics power financial dashboards for practice managers.

Encounter-Based Revenue

By linking invoices to encounters, you can analyze revenue by:

Practitioner (who generates the most revenue)
Service type (which services are most profitable)
Time period (monthly/quarterly trends)

Integration with Clinical Domains

From Encounters

The billing domain receives data from encounters. When an encounter is finalized, the services documented become billable. The encounter ID links the clinical record to the financial record.

Diagnoses from the encounter (ICD-10 codes) may be required for insurance billing. These flow from the clinical conditions to the invoice.

From Appointments

Appointment types might have associated fees. A "new patient visit" appointment type might automatically add a specific service fee when invoiced.

To Service Fees

The service fee schedule is a shared reference. Clinical staff select procedure codes; billing staff see the associated prices. Keeping these in sync ensures accurate billing.

Key Takeaways

Invoices are containers - they hold line items for services rendered
Items come from multiple sources - service fees, inventory, custom entries
Payments accumulate - multiple payments can apply to one invoice
Ledger is immutable - every transaction is recorded forever
Status progression - draft → pending → partial → paid
Encounter connection - clinical services become billable items
Running balance - patients have ongoing financial histories

Next: Read about the Practitioner Domain to understand provider management

အသုံးပြုသူ လက်စွဲစာအုပ်

Guides