Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:09:55Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:39, 6 July 2026
Line 76:		Line 76:

	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.		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.

			{{Navbox billing}}

	{{Related}}		{{Related}}
			Wiki: ohcnwiki.tellmey.fyi

Admin: OHC identity seed

2026-07-04T22:43:03Z

OHC identity seed

New page

{{Doc header
|type=concept
|domain=billing
|title=Invoice
|order=4
|introduced=3.0
|concept=Concepts/Patient
|reference=References/Payment Reconciliation
}}

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 [[References/Payment Reconciliation|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.

== How it connects ==

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

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

== Lifecycle ==

An invoice moves through a small set of statuses, and a crucial thing happens partway through. While an invoice is still a <code>draft</code> 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.

<syntaxhighlight lang="text">draft → issued → balanced
└────────────→ cancelled / entered_in_error</syntaxhighlight>
* '''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

<code>cancelled</code> and <code>entered_in_error</code> are the two terminal void states. Drive these transitions through the billing workflow rather than editing records directly, since each one also adjusts the linked charge items and 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 ==

An issued invoice can be '''locked''' to freeze it against any further edits — useful once a bill has been formally closed out or handed to an external system. Locking is a privileged action, separate from everyday read and write access.

== Permissions ==

Access to invoices is governed by facility-scoped permissions:

{| class="wikitable"
|-
! Permission
! Description
! System Roles
|-
| <code>can_write_invoice</code>
| Create and update invoices, including attaching or removing charge items and issuing or balancing them. Also gates cancelling an invoice within the free-cancel window.
| Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist
|-
| <code>can_read_invoice</code>
| List and retrieve invoices, their line items, totals, and reconciliation history.
| Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist
|-
| <code>can_destroy_invoice</code>
| Cancel an invoice after the free-cancel window has elapsed.
| Facility Admin, Admin
|-
| <code>can_manage_locked_invoice</code>
| Lock and unlock invoices, and retrieve a locked invoice.
| 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.

{{Related}}

Concepts/Invoice - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed