Billing and charge capture — user guide
This guide explains how treatment costs reach a patient's account, who controls what is billable, and how the same machinery serves both hospital pharmacy dispensing and over-the-counter sales.
Who this is for: finance administrators who maintain prices, billing clerks who review and issue invoices, and pharmacists (hospital or retail) who dispense.
The governing rule: billing never gets in the way of care. Clinical staff never see a price check during a form submission or a workflow stage — charges are captured quietly in the background, and money conversations happen at the billing desk, not the bedside.
1. The charge master: your facility's price list
Managed under Billing → Charge items (API: /api/v1/billing/charge-items; screen: FE-127).
A charge item says what one billable thing costs at your facility — prices are always facility business, never platform-wide. Each entry prices either:
- a specific orderable (e.g. "Full blood count" — the exact concept clinicians order), or
- a whole order type as a fallback (e.g. a flat price for any LAB order that has no specific price of its own),
and can be linked to your facility's service catalogue entry so the invoice line carries your service code.
Maintaining the charge master needs its own permission (billing.charge.*), separate from
invoice-writing on purpose: pricing the price list is a finance-administration act, and the clerk
who records payments should not silently be able to change what things cost.
Billable, covered, and unpriced — three different facts
- Billable (the default): completing a matching order adds a charge to the patient's draft invoice automatically.
- Covered (billable switched off): the item is priced but deliberately free — typically paid by a programme. It is matched and then skipped, and the skip is recorded in the system logs.
- Unpriced: nobody has created a charge item for it. Nothing is charged, and that is also visible in the logs.
The distinction matters for revenue review: covered is a decision your facility made; unpriced is a gap someone should look at. The system keeps them distinguishable instead of letting both look like "free".
Who the bill names, and who it is addressed to
An invoice records two different facts, and confusing them loses money trails:
- The patient is who received the service. Every charge that comes from care carries this, and the system refuses to attach such a charge to an invoice that names no patient — otherwise the payment could never be tied back to the episode that earned it.
- The billed-to person is who should pay, when that is somebody other than the patient: a parent, a guarantor, an employer's contact. Setting it does not remove the patient; it adds the payer beside them.
Both may be empty only for a counter sale — an over-the-counter purchase by someone the facility holds no record of. That is the one case with no patient to lose.
Which currency prices are in
Every charge item stores its own ISO currency code (NGN, GHS, USD…), and new items default to
your facility's operating currency. Set that once under Administration → Properties as the
setting billing.default_currency (see the platform settings guide) —
your facility's value overrides any tenant or platform default.
You never configure a currency symbol. The ₦ or $ you see is derived from the code, so a price can never display a symbol that disagrees with the currency it is actually recorded in.
2. When do charges reach the patient's account?
The moment care completes — not when someone remembers to type an invoice. When an order
(lab, imaging, medication, procedure…) is marked completed, the system looks up its price in
the charge master and adds a draft invoice line to the patient's open draft invoice, creating
that invoice if none exists (you will recognise these by their generated CHG- invoice numbers).
Each captured line records exactly which completed order produced it, and the same order can never
be charged twice — even if statuses are corrected back and forth.
Nothing is ever issued automatically. The draft accumulates during the visit and waits for a person.
3. Review and issue: the billing desk's moment
The natural review point is checkout: if your facility uses workflow checkout routing, ending a visit places the patient on your billing queue, and the clerk who receives them finds the draft invoice already populated with everything that completed during the visit. The clerk then:
- reviews the captured lines (each shows what it was and where it came from),
- adjusts, removes, or adds manual lines (bed days, consumables, anything not yet order-driven),
- issues the invoice — from that point it proceeds to payment like any hand-written invoice.
Clinicians decide what care happens; the charge master decides what it costs; the clerk decides what the patient is actually asked to pay. No step steals another's decision.
Today's scope: charges fire automatically on completed orders. Encounter-based fees (e.g. a flat consultation fee per completed encounter) are planned on the same mechanism; until then they are the clerk's manual lines at review.
4. Pharmacy: one design for the ward and the shop counter
The medication tables were built so that hospital dispensing and retail (over-the-counter) pharmacy share one backbone instead of growing two parallel systems:
- In-hospital dispensing starts from a prescription: the clinician's medication order is the instruction, and each dispense is the pharmacy's separately-recorded action against it — including substitutions (stated on the dispense, never rewriting the prescriber's order) and partial dispensing (several handovers against one order). When the medication order completes, its charge is captured onto the patient's draft invoice exactly as in §2.
- Over-the-counter sales have no doctor's order. The retail pharmacy module sells from its own catalogue and stock, and posts its charges into the same billing pipeline with the same once-and-only-once guarantee — so a till receipt and a ward charge are equally auditable, and a patient who is both an outpatient and a shop customer still has one coherent financial record.
- In both settings, drugs are dictionary concepts (RxNorm-mapped), so what was prescribed, what was dispensed, and what was charged all speak the same vocabulary — and the dispenser is always attributable: the signed-in pharmacist by default, or the named dispenser when another system records the handover.
The retail pharmacy product (inventory, batches/expiry, procurement, controlled-drug registers)
is its own module. In-hospital fills still complete the medication order so M13-007 capture
fires. OTC / walk-in till sales post ChargeSourceType.SALE lines through
BillingCommandClient into this same invoice pipeline — identified onto the patient's draft,
anonymous onto a SALE- counter invoice that names no patient.