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

2026-07-06T04:12:01Z

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

← Older revision		Revision as of 09:42, 6 July 2026
Line 243:		Line 243:
	* The list view (<code>InvoiceReadSpec</code>) returns a minimal <code>account</code>; the detail view (<code>InvoiceRetrieveSpec</code>) returns the full account plus charge items, aggregated price components, payments, credit notes, and lock history.		* The list view (<code>InvoiceReadSpec</code>) returns a minimal <code>account</code>; the detail view (<code>InvoiceRetrieveSpec</code>) returns the full account plus charge items, aggregated price components, payments, credit notes, and lock history.
	* When <code>locked</code> is <code>True</code>, the read specs serialize <code>total_net</code> and <code>total_gross</code> as <code>0</code>.		* When <code>locked</code> is <code>True</code>, the read specs serialize <code>total_net</code> and <code>total_gross</code> as <code>0</code>.

			{{Navbox billing}}

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

Admin: OHC identity seed

2026-07-04T22:44:11Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=billing
|title=Invoice
|order=4
|introduced=3.0
|model=Invoice
|reference=References/Base models & conventions
}}

An <code>Invoice</code> groups [[References/Charge Item|charge items]] raised against a single [[References/Account|account]] into one billable document, with snapshotted line items, totals, and a lifecycle <code>status</code>. You touch it whenever you bill a patient, issue a refund, or reconcile payments.

The data splits across two layers. The Django model is storage: columns plus several opaque <code>JSONField</code>s (<code>charge_items_copy</code>, <code>total_price_components</code>, <code>lock_history</code>) whose real structure lives in the Pydantic resource specs. The specs define the API request/response schemas, the <code>InvoiceStatusOptions</code> enum, the shape of those JSON fields, validation, and the server-side totalling and snapshot behaviour.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/invoice.py <code>care/emr/models/invoice.py</code>]
* Resource specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/invoice/spec.py <code>spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/invoice/sync_items.py <code>sync_items.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/invoice/return_items_invoice.py <code>return_items_invoice.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/invoice/default_expression_evaluator.py <code>default_expression_evaluator.py</code>]
* Shared types: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>base.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/monetary_component.py <code>monetary_component.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>Invoice</code>
| A billable grouping of charge items for one account, with snapshotted line items, totals, and status
|}

<code>Invoice</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]] (shared Care EMR base with <code>external_id</code>, audit fields, and soft-delete semantics).

On issue, the server computes net and gross totals and snapshots each charge item, so the invoice stays stable even when its charge items change later. The retrieve view reports [[References/Payment Reconciliation|payment reconciliation]] records — payments and credit notes — against the invoice.

== <code>Invoice</code> fields ==

=== References ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Invoice|section=References|name=facility|type=FK → facility.Facility (PROTECT)|notes=Facility where the invoice is created}}
{{Field|model=Invoice|section=References|name=patient|type=FK → emr.Patient (PROTECT)|notes=Entity that incurred the charges; set server-side from <code>account.patient</code> on write}}
{{Field|model=Invoice|section=References|name=account|type=FK → emr.Account (PROTECT)|notes=Account being balanced by this invoice}}
|}

=== Status & metadata ===

{| class="wikitable"
|-
! Field
! Type
! Spec / values
! Notes
{{Field|model=Invoice|section=Status & metadata|name=status|type=CharField(100)|notes=<code>InvoiceStatusOptions</code> enum — required on write}}
{{Field|model=Invoice|section=Status & metadata|name=title|type=CharField(1024)|notes=<code>str | None</code>, default <code>None</code>}}
{{Field|model=Invoice|section=Status & metadata|name=cancelled_reason|type=TextField|notes=<code>str | None</code>}}
{{Field|model=Invoice|section=Status & metadata|name=payment_terms|type=TextField|notes=<code>str | None</code>}}
{{Field|model=Invoice|section=Status & metadata|name=note|type=TextField|notes=<code>str | None</code>}}
{{Field|model=Invoice|section=Status & metadata|name=number|type=CharField(1000)|notes=<code>str | None</code>, default <code>None</code>}}
{{Field|model=Invoice|section=Status & metadata|name=issue_date|type=DateTimeField|notes=<code>datetime | None</code> (tz-aware), default <code>None</code>}}
{{Field|model=Invoice|section=Status & metadata|name=is_refund|type=BooleanField|notes=<code>bool</code>, default <code>False</code>}}
|}

=== Charge items ===

{| class="wikitable"
|-
! Field
! Type
! Spec shape
! Notes
{{Field|model=Invoice|section=Charge items|name=charge_items|type=ArrayField[int], default []|notes=write: <code>list[UUID4]</code>; storage: list of integer PKs}}
{{Field|model=Invoice|section=Charge items|name=charge_items_copy|type=JSONField, default []|notes=<code>list[dict]</code> — array of serialized <code>ChargeItemReadSpec</code>}}
|}

=== Totals (server-maintained) ===

<code>sync_invoice_items</code> and <code>calculate_charge_items_summary</code> compute these. Never send them from a client.

{| class="wikitable"
|-
! Field
! Type
! Spec shape
! Notes
{{Field|model=Invoice|section=Totals (server-maintained)|name=total_price_components|type=JSONField, default {}|notes=retrieve: <code>list[dict]</code> of <code>MonetaryComponent</code>}}
{{Field|model=Invoice|section=Totals (server-maintained)|name=total_net|type=DecimalField(20, 6), default 0|notes=<code>Decimal(max_digits=20, decimal_places=6)</code>}}
{{Field|model=Invoice|section=Totals (server-maintained)|name=total_gross|type=DecimalField(20, 6), default 0|notes=<code>Decimal(max_digits=20, decimal_places=6)</code>}}
|}

When <code>locked</code> is <code>True</code>, the read specs serialize both <code>total_net</code> and <code>total_gross</code> as <code>0</code>.

=== Locking ===

{| class="wikitable"
|-
! Field
! Type
! Spec shape
! Notes
{{Field|model=Invoice|section=Locking|name=locked|type=BooleanField, default False|notes=<code>bool</code> (read-only on read specs)}}
{{Field|model=Invoice|section=Locking|name=lock_history|type=JSONField, default []|notes=<code>list[dict]</code> — each entry <code>{ user, ... }</code>}}
|}

== Enums ==

=== <code>InvoiceStatusOptions</code> values ===

Defined in <code>care/emr/resources/invoice/spec.py</code>. The API value is <code>entered_in_error</code> (underscore), not the FHIR-style hyphen.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| In progress; retrieve serializes live charge items, not the snapshot
|-
| <code>issued</code>
| Issued to the patient/payer
|-
| <code>balanced</code>
| Fully settled
|-
| <code>cancelled</code>
| Cancelled
|-
| <code>entered_in_error</code>
| Recorded in error
|}

<code>INVOICE_CANCELLED_STATUS = ["cancelled", "entered_in_error"]</code> — the two terminal/void states.

=== <code>MonetaryComponentType</code> values ===

Defined in <code>care/emr/resources/common/monetary_component.py</code>. Each type contributes to net and gross differently during totalling.

{| class="wikitable"
|-
! Value
! Effect on totals
|-
| <code>base</code>
| Added to net (one base component per item; must carry an <code>amount</code>)
|-
| <code>surcharge</code>
| Added to net
|-
| <code>discount</code>
| Subtracted from net
|-
| <code>tax</code>
| Added to gross only (excluded from net)
|-
| <code>informational</code>
| Carried for display; not summed
|}

== Resource specs (API schema) ==

All specs subclass <code>EMRResource</code> (<code>serialize</code> / <code>de_serialize</code>, with <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks). <code>BaseInvoiceSpec.__model__ = Invoice</code> and <code>__exclude__ = ["account", "charge_items"]</code>; the hooks handle those two fields rather than the generic mapper.

{| class="wikitable"
|-
! Spec
! Role
! Fields beyond base
! Server behaviour
|-
| <code>BaseInvoiceSpec</code>
| shared
| <code>id</code>, <code>title</code>, <code>status</code> (required), <code>cancelled_reason</code>, <code>payment_terms</code>, <code>note</code>, <code>issue_date</code>, <code>number</code>
| Base for all specs
|-
| <code>InvoiceWriteSpec</code>
| write · create + update
| <code>account: UUID4</code> (required), <code>charge_items: list[UUID4]</code> (default <code>[]</code>)
| <code>perform_extra_deserialization</code>: resolves <code>account</code> from <code>external_id</code>, sets <code>patient = account.patient</code>, stages <code>charge_items</code> (rewritten in <code>perform_create</code>)
|-
| <code>InvoiceReadSpec</code>
| read · list
| <code>total_net</code>, <code>total_gross</code>, <code>locked</code>, <code>created_date</code>, <code>modified_date</code>, <code>account: dict</code>, <code>is_refund</code>
| <code>perform_extra_serialization</code>: <code>id = external_id</code>; <code>account</code> → <code>AccountMinimalReadSpec</code>; if <code>locked</code>, zero out <code>total_net</code>/<code>total_gross</code>
|-
| <code>InvoiceRetrieveSpec</code>
| read · detail
| (all read fields) + <code>charge_items: list[dict]</code>, <code>total_price_components: list[dict]</code>, <code>created_by</code>, <code>updated_by</code>, <code>payments: list[dict]</code>, <code>total_payments</code>, <code>credit_notes: list[dict]</code>, <code>total_credit_notes</code>, <code>lock_history: list[dict]</code>
| See retrieve serialization below
|}

<code>InvoiceWriteSpec</code> handles both create and update — there's no separate Update spec. <code>InvoiceRetrieveSpec</code> extends <code>InvoiceReadSpec</code>.

=== <code>InvoiceRetrieveSpec.perform_extra_serialization</code> ===

* <code>id = external_id</code>; <code>account</code> serialized via <code>AccountReadSpec</code> (full account on detail).
* <code>charge_items</code>: if <code>status == draft</code>, live <code>ChargeItemReadSpec.serialize(...)</code> over <code>ChargeItem.objects.filter(id__in=charge_items)</code> (<code>select_related</code> <code>paid_invoice</code>, <code>charge_item_definition</code>); otherwise the stored <code>charge_items_copy</code> snapshot.
* <code>created_by</code> / <code>updated_by</code>: hydrated via <code>serialize_audit_users</code>.
* Reconciliations against this invoice with <code>outcome = complete</code> and <code>status = active</code> are split into:
** <code>payments</code> (+ <code>total_payments</code>) where <code>is_credit_note</code> is false,
** <code>credit_notes</code> (+ <code>total_credit_notes</code>) where <code>is_credit_note</code> is true,
** each serialized via <code>PaymentReconciliationRetrieveSpec</code>.
* <code>lock_history</code>: each entry's <code>user</code> id replaced with a cached <code>UserSpec</code>.

=== <code>MonetaryComponent</code> shape ===

Stored inside <code>total_price_components</code> and <code>charge_items_copy</code>. Source: <code>care/emr/resources/common/monetary_component.py</code>.

<syntaxhighlight lang="text">MonetaryComponent {
monetary_component_type: MonetaryComponentType # required (base|surcharge|discount|tax|informational)
code: Coding | None # { system?, version?, code, display? }
factor: Decimal(20,6) | None
amount: Decimal(20,6) | None
tax_included_amount: Decimal(20,6) | None # only valid on base
global_component: bool = False
conditions: list[EvaluatorConditionSpec] = []
}</syntaxhighlight>
Per-component validation: <code>base</code> must carry an <code>amount</code> and no <code>conditions</code>; <code>tax_included_amount</code> is allowed only on <code>base</code>; <code>amount</code> and <code>factor</code> are mutually exclusive; at least one of <code>amount</code>/<code>factor</code> is required, unless the component is a <code>global_component</code> with a <code>code</code>. Collection-level rules (<code>MonetaryComponents</code>) forbid duplicate codes, require exactly one <code>base</code>, and reconcile <code>tax_included_amount</code> against the sum of tax components.

== Related models ==

* [[References/Charge Item|<code>ChargeItem</code>]] — line items grouped by the invoice; snapshotted into <code>charge_items_copy</code> via <code>ChargeItemReadSpec</code>.
* [[References/Account|<code>Account</code>]] — the billing account; resolved on write, rebalanced after return-invoice generation/cancellation.
* [[References/Payment Reconciliation|<code>PaymentReconciliation</code>]] — payments and credit notes reported on the retrieve view (filtered to <code>outcome=complete</code>, <code>status=active</code>).
* [[References/Charge Item Definition|<code>ChargeItemDefinition</code>]] — applied when building return-invoice charge items.

== Methods & save behaviour ==

* '''<code>sync_invoice_items(invoice)</code>''' (<code>sync_items.py</code>) — recomputes <code>total_net</code>, <code>total_gross</code>, <code>total_price_components</code>, and <code>charge_items_copy</code> from the linked charge items, then rounds totals using <code>INVOICE_FINAL_AMOUNT_PRECISION</code> / <code>INVOICE_FINAL_AMOUNT_ROUNDING_METHOD</code>. '''Validation:''' if <code>is_refund</code> is false and either total is negative, raises <code>ValidationError("A Refund Ivoice is required for negative values")</code>.
* '''<code>calculate_charge_items_summary(charge_items)</code>''' — net = Σ base + Σ surcharge − Σ discount; gross = net + Σ tax; components aggregated per <code>type + code</code> (key = <code>system + code</code>, else <code>No-Code</code>).
* '''<code>evaluate_invoice_identifier_default_expression(facility)</code>''' (<code>default_expression_evaluator.py</code>) — generates <code>number</code> from the facility's <code>invoice_number_expression</code> with context <code>{ invoice_count, current_year_yyyy, current_year_yy }</code>; returns <code>""</code> if unset. <code>evaluate_invoice_dummy_expression</code> previews an expression with sample context.
* '''<code>generate_return_invoice(delivery_order)</code>''' (<code>return_items_invoice.py</code>) — creates a <code>draft</code> refund invoice (<code>is_refund=True</code>), reverses each completed <code>SupplyDelivery</code>'s charge item via <code>apply_charge_item_definition(reverse=True)</code>, marks items <code>billed</code>, runs <code>sync_invoice_items</code>, sets status <code>issued</code>, then triggers <code>rebalance_account_task</code>. Raises if any delivery is still <code>in_progress</code>.
* '''<code>cancel_return_invoice(delivery_order)</code>''' — sets the invoice <code>cancelled</code>, marks its charge items <code>entered_in_error</code> (clears <code>paid_invoice</code>/<code>paid_on</code>), voids the supply deliveries, rebalances the account, and resyncs inventory.

== API integration notes ==

* <code>status</code> is the control surface for the billing lifecycle. Drive transitions through the API rather than editing rows directly; the values are <code>draft</code>, <code>issued</code>, <code>balanced</code>, <code>cancelled</code>, <code>entered_in_error</code>.
* On write (<code>InvoiceWriteSpec</code>): send <code>account</code> and <code>charge_items</code> as external UUIDs. The server derives <code>patient</code> from the account, so don't send it. <code>account</code> and <code>charge_items</code> bypass the generic field mapper and are handled in <code>perform_extra_deserialization</code>.
* <code>charge_items_copy</code>, <code>total_price_components</code>, <code>total_net</code>, and <code>total_gross</code> are platform-maintained snapshots derived from the linked charge items — don't set them directly.
* The list view (<code>InvoiceReadSpec</code>) returns a minimal <code>account</code>; the detail view (<code>InvoiceRetrieveSpec</code>) returns the full account plus charge items, aggregated price components, payments, credit notes, and lock history.
* When <code>locked</code> is <code>True</code>, the read specs serialize <code>total_net</code> and <code>total_gross</code> as <code>0</code>.

{{Related}}

References/Invoice - Revision history

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

Admin: OHC identity seed