Skip to main content
Version: 3.1

Invoice

An invoice is the bill Care produces for a patient: it gathers the charges raised on an account into a single, numbered statement of what is owed. It is the moment billing becomes official — the point where running charges are frozen into a document the patient or payer can be asked to settle.

What it represents​

In Care's FHIR-aligned model, an invoice maps to the Invoice resource. It pulls together three things: the charge items being billed (each a service, medication, or product the patient received), the money they add up to (net and gross totals, built from base amounts, surcharges, discounts, and taxes), and the account it settles. The patient is inherited from that account, never set by hand.

The key distinction is that an invoice is not a payment. It states what is owed; the act of paying it down — and any credit notes against it — lives in payment reconciliation. One account can produce several invoices over time as new charges accumulate, and the invoice's detail view reports what has been paid against each so you can always see the remaining balance.

Lifecycle​

An invoice moves through a small set of statuses, and a crucial thing happens partway through. While an invoice is still a draft it shows the live charges — edit a charge item and the invoice follows. The instant it is issued, Care takes a frozen snapshot of those line items and computes the totals once. From then on the invoice shows that snapshot, not the live charges. This is deliberate: a bill the patient was handed must not silently change if someone later edits an underlying charge.

draft → issued → balanced
  └────────────→ cancelled / entered_in_error
  • draft — being assembled; charges and totals are still live and editable
  • issued — finalised and presented to the patient or payer; line items and totals are now snapshotted
  • balanced — fully settled, with payments matching what was owed
  • cancelled — voided after issue; no longer collectible
  • entered_in_error — recorded by mistake and retracted

Care allows only one path through the ordinary statuses: draft to issued (once the invoice holds at least one charge item), then issued to balanced. Any other change is refused, such as jumping straight from draft to balanced or reopening a balanced invoice. cancelled and entered_in_error are the two terminal void states, reached only through a dedicated cancel action rather than an ordinary status change, since cancelling also returns the linked charge items to billable and adjusts the account.

Refunds​

A normal invoice has positive totals. When goods are returned or a charge is reversed, Care creates a separate refund invoice with negative totals. These are flagged as refunds, and Care refuses to save a negative-total invoice that is not marked as one — a guardrail that keeps refunds from being mistaken for ordinary bills.

Locking​

Care can lock an invoice at any status. A lock does not change the status of the invoice. A lock freezes the invoice and hides its money. While an invoice is locked, Care reports the net total and the gross total as zero to every user who reads the invoice. The invoice list shows a Locked badge in place of the amount.

Only a user with the can_manage_locked_invoice permission can open a locked invoice. Care refuses the request from every other user. The same permission is necessary to lock an invoice and to unlock it. Care also keeps a lock history, and records the user and the time for each lock and each unlock.

How it connects​

An invoice sits at the meeting point of several billing primitives:

  • Account — every invoice settles exactly one account, and takes its patient from there.
  • Charge items — the line items. A charge item is each individual billable thing; the invoice is the envelope that totals them up.
  • Charge item definitions — the priced catalogue entries charge items are built from, used when Care generates a refund invoice automatically.
  • Payment reconciliation — the payments and credit notes recorded against the invoice once it is issued.

Permissions​

Access to invoices is governed by facility-scoped permissions:

PermissionDescriptionSystem Roles
can_write_invoiceCreate and update invoices, including attaching or removing charge items and issuing or balancing them. Also gates a cancel action inside the free-cancel period.Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist
can_read_invoiceList and retrieve invoices, their line items, totals, and reconciliation history.Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist
can_destroy_invoiceCancel an invoice after the free-cancel period ends. The free-cancel period is a deployment setting, and its default value is zero minutes, so a cancel action needs this permission in a default deployment.Facility Admin, Admin
can_manage_locked_invoiceLock an invoice, unlock an invoice, and read a locked invoice. Care refuses a read of a locked invoice for every other user.Facility Admin, Admin

Roles are granted through a user's facility and organization memberships, and permissions cascade down the organization tree, so access at a parent organization carries to the facilities beneath it.