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

2026-07-06T04:11:26Z

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

← Older revision		Revision as of 09:41, 6 July 2026
Line 343:		Line 343:
	* Create and update enforce that <code>performer_actor</code> (and, when applying definitions, the actor) belongs to the facility's organization.		* Create and update enforce that <code>performer_actor</code> (and, when applying definitions, the actor) belongs to the facility's organization.
	* <code>discount_configuration</code> and <code>tags</code> are structured but deployment-tunable: <code>discount_configuration</code> follows <code>DiscountConfiguration</code>, and tags resolve through the single-facility tag manager.		* <code>discount_configuration</code> and <code>tags</code> are structured but deployment-tunable: <code>discount_configuration</code> follows <code>DiscountConfiguration</code>, and tags resolve through the single-facility tag manager.

			{{Navbox billing}}

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

Admin: OHC identity seed

2026-07-04T22:44:07Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=billing
|title=Charge Item
|order=2
|introduced=3.0
|model=ChargeItem
|reference=References/Base models & conventions
}}

A <code>ChargeItem</code> is a single billable line for a service or product supplied to a patient — what was charged, the quantity, the unit and total price components, and any discounts or override reasons. You create one against a patient (and optionally an encounter); it always settles onto an [[References/Account|<code>Account</code>]].

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/charge_item.py <code>care/emr/models/charge_item.py</code>]
* Resource specs: [<nowiki/>https://github.com/ohcnetwork/care/tree/develop/care/emr/resources/charge_item <code>care/emr/resources/charge_item/</code>] ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/charge_item/spec.py <code>spec.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/charge_item/sync_charge_item_costs.py <code>sync_charge_item_costs.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/charge_item/apply_charge_item_definition.py <code>apply_charge_item_definition.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/charge_item/handle_charge_item_cancel.py <code>handle_charge_item_cancel.py</code>])
* Viewset: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/charge_item.py <code>care/emr/api/viewsets/charge_item.py</code>]

The Django model is only the storage layer. Several fields are opaque <code>JSONField</code>s whose structure lives in the Pydantic resource specs under <code>care/emr/resources/charge_item/</code>, which also define the enums, validation, read/write API schemas, server-side cost calculation, and status side effects. The field tables below tell you what's stored; the spec and behaviour sections tell you what happens on write.

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ChargeItem</code>
| A single billable line item for a service or product rendered to a patient
|}

<code>ChargeItem</code> extends <code>EMRBaseModel</code> (shared Care EMR base with <code>external_id</code>, audit fields — <code>created_by</code>/<code>updated_by</code>/<code>created_date</code>/<code>modified_date</code> — and soft-delete semantics — see [[References/Base models & conventions|Base model]]).

== <code>ChargeItem</code> fields ==

=== Context & relationships ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ChargeItem|section=Context & relationships|name=facility|type=FK → facility.Facility (PROTECT)|notes=Set server-side from the URL; a body value is ignored}}
{{Field|model=ChargeItem|section=Context & relationships|name=patient|type=FK → emr.Patient (CASCADE)|notes=When you supply an <code>encounter</code>, the patient is taken from it rather than the request}}
{{Field|model=ChargeItem|section=Context & relationships|name=encounter|type=FK → emr.Encounter (CASCADE)|notes=Nullable; the encounter the charge relates to}}
{{Field|model=ChargeItem|section=Context & relationships|name=charge_item_definition|type=FK → emr.ChargeItemDefinition (CASCADE)|notes=Nullable; the template the charge was applied from. Not writable via create/update — set only by <code>apply_charge_item_defs</code>}}
{{Field|model=ChargeItem|section=Context & relationships|name=account|type=FK → emr.Account (CASCADE)|notes=The account this charge lands on. Falls back to the patient's default account when omitted}}
|}

=== Description & status ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ChargeItem|section=Description & status|name=title|type=CharField(255)|notes=Required; display title for the charge}}
{{Field|model=ChargeItem|section=Description & status|name=description|type=TextField|notes=Nullable; longer description}}
{{Field|model=ChargeItem|section=Description & status|name=status|type=CharField(255)|notes=Required; lifecycle status, constrained to <code>ChargeItemStatusOptions</code> — see [[#status-values}}
{{Field|model=ChargeItem|section=Description & status|name=code|type=JSONField|notes=Nullable; a <code>Coding</code> that identifies the charge (e.g. a billing code), shape <code>Coding { system?, version?, code, display? }</code> — see [[#coding-shape}}
{{Field|model=ChargeItem|section=Description & status|name=note|type=TextField|notes=Nullable; free-text (markdown) comments}}
|}

=== Pricing ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ChargeItem|section=Pricing|name=quantity|type=DecimalField(20, 6)|notes=Required on write; the quantity serviced. Multiplies the base/per-unit components during cost sync}}
{{Field|model=ChargeItem|section=Pricing|name=unit_price_components|type=JSONField|notes=Required on write; list of <code>MonetaryComponent</code> — see [[#monetarycomponent-shape}}
{{Field|model=ChargeItem|section=Pricing|name=total_price_components|type=JSONField|notes=Nullable; server-computed list of <code>MonetaryComponent</code> (as dicts) — the resolved breakdown after base × quantity, surcharges, discounts, and taxes. Not client-writable}}
{{Field|model=ChargeItem|section=Pricing|name=total_price|type=DecimalField(20, 6)|notes=Nullable; server-computed total. Must be ≥ 0 unless the charge is a reversal}}
{{Field|model=ChargeItem|section=Pricing|name=override_reason|type=JSONField|notes=Nullable; <code>ChargeItemOverrideReason { text: str, code?: Coding }</code> explaining a list-price/factor override. No bound value set}}
{{Field|model=ChargeItem|section=Pricing|name=discount_configuration|type=JSONField|notes=Nullable (default <code>None</code>); <code>DiscountConfiguration { max_applicable: int (≥0), applicability_order: total_asc | total_desc }</code>. Populated from the definition/facility config when applied from a definition}}
|}

=== Service source ===

These fields trace the charge back to the resource that produced it.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ChargeItem|section=Service source|name=service_resource|type=CharField(255)|notes=Nullable (default <code>None</code>); resource type, constrained to <code>ChargeItemResourceOptions</code> — see [[#service-resource-types}}
{{Field|model=ChargeItem|section=Service source|name=service_resource_id|type=CharField(255)|notes=Nullable (default <code>None</code>); external id of the originating resource. Required once <code>service_resource</code> is set}}
{{Field|model=ChargeItem|section=Service source|name=performer_actor|type=FK → users.User (CASCADE)|notes=Nullable (default <code>None</code>); the user who performed the service. Must belong to the facility's organization}}
|}

=== Invoicing & tags ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ChargeItem|section=Invoicing & tags|name=paid_invoice|type=FK → emr.Invoice (CASCADE)|notes=Nullable (default <code>None</code>); denormalized link to the settling invoice. Platform-maintained; cleared on cancel}}
{{Field|model=ChargeItem|section=Invoicing & tags|name=paid_on|type=DateTimeField|notes=Nullable (default <code>None</code>); when the charge was paid. Platform-maintained; cleared on cancel}}
{{Field|model=ChargeItem|section=Invoicing & tags|name=tags|type=ArrayField[int]|notes=Tag IDs, default <code>[]</code>. Managed through the tag mixin (<code>SingleFacilityTagManager</code>), serialized as objects on read}}
|}

== Enums ==

=== Status values ===

<code>status</code> is a plain <code>CharField</code> in storage, but every write passes through <code>ChargeItemStatusOptions</code> (<code>care/emr/resources/charge_item/spec.py</code>):

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>billable</code>
| Ready to be invoiced
|-
| <code>not_billable</code>
| Will not be billed
|-
| <code>aborted</code>
| Charge was cancelled before billing
|-
| <code>billed</code>
| Included on an invoice
|-
| <code>paid</code>
| Settled (links to <code>paid_invoice</code> / <code>paid_on</code>)
|-
| <code>entered_in_error</code>
| Recorded in error
|}

(<code>planned</code> exists in the source as a commented-out option and is '''not''' currently selectable.)

<code>not_billable</code>, <code>aborted</code>, and <code>entered_in_error</code> form the cancelled set (<code>CHARGE_ITEM_CANCELLED_STATUS</code>). Moving into this set on update triggers the cancel side effect (see [[#methods--save-behaviour|Methods & save behaviour]]). <code>billed</code> and <code>paid</code> cannot be set by hand — the viewset rejects manual transitions into them.

=== Service resource types ===

<code>service_resource</code> is constrained by <code>ChargeItemResourceOptions</code>:

{| class="wikitable"
|-
! Value
|-
| <code>service_request</code>
|-
| <code>medication_dispense</code>
|-
| <code>appointment</code>
|-
| <code>bed_association</code>
|}

On create, the viewset validates the referenced resource: <code>service_request</code> must exist (and not be completed) for the patient/encounter, and <code>bed_association</code> must reference a <code>FacilityLocationEncounter</code> on a non-completed encounter in the facility.

=== MonetaryComponentType values ===

Used by every entry in <code>unit_price_components</code> / <code>total_price_components</code> (<code>care/emr/resources/common/monetary_component.py</code>):

{| class="wikitable"
|-
! Value
! Role in cost sync
|-
| <code>base</code>
| Per-unit base price. Exactly one allowed; must carry <code>amount</code> (not <code>factor</code>); no <code>conditions</code>. <code>base.amount × quantity</code> seeds the running total
|-
| <code>surcharge</code>
| Added on top of base; <code>amount</code> or <code>factor</code> (% of base)
|-
| <code>discount</code>
| Subtracted from the net price; <code>amount</code> or <code>factor</code> (% of net). Filtered/limited by <code>discount_configuration</code>
|-
| <code>tax</code>
| Added on the post-discount taxable price; <code>amount</code> or <code>factor</code> (% of taxable)
|-
| <code>informational</code>
| Carried through without affecting the computed total
|}

=== DiscountApplicability values ===

<code>discount_configuration.applicability_order</code> (<code>care/emr/resources/common/monetary_component.py</code>):

{| class="wikitable"
|-
! Value
! Effect
|-
| <code>total_asc</code>
| Sort candidate discounts by amount ascending before applying <code>max_applicable</code>
|-
| <code>total_desc</code>
| Sort by amount descending before applying <code>max_applicable</code>
|}

<code>max_applicable = 0</code> drops all discounts.

== JSON field shapes ==

=== Coding shape ===

<code>code</code>, plus the <code>code</code> field inside components and <code>override_reason</code> (<code>care/emr/resources/common/coding.py</code>, <code>extra="forbid"</code>):

<syntaxhighlight lang="text">Coding {
system?: str
version?: str
code: str # required
display?: str
}</syntaxhighlight>
=== MonetaryComponent shape ===

Each entry of <code>unit_price_components</code> and <code>total_price_components</code> (<code>care/emr/resources/common/monetary_component.py</code>):

<syntaxhighlight lang="text">MonetaryComponent {
monetary_component_type: base | surcharge | discount | tax | informational # required
code?: Coding
factor?: Decimal(20,6) # percentage; mutually exclusive with amount
amount?: Decimal(20,6) # absolute; mutually exclusive with factor
tax_included_amount?: Decimal(20,6) # base component only
global_component: bool = False # resolved against facility monetary config
conditions: [EvaluatorConditionSpec] = [] # not allowed on base
}</syntaxhighlight>
Validation: exactly one of <code>amount</code>/<code>factor</code> (unless <code>global_component</code> with a <code>code</code>); <code>base</code> must have <code>amount</code>, no <code>factor</code>, no <code>conditions</code>; <code>tax_included_amount</code> only on <code>base</code>; duplicate component <code>code</code>s are rejected.

<code>EvaluatorConditionSpec { metric: str, operation: str, value: dict | str }</code> — conditions are evaluated against patient/facility/encounter context when a definition is applied; a component whose conditions fail is dropped.

=== ChargeItemOverrideReason shape ===

<code>override_reason</code> (<code>care/emr/resources/charge_item/spec.py</code>):

<syntaxhighlight lang="text">ChargeItemOverrideReason {
text: str # required
code?: Coding # no bound value set
}</syntaxhighlight>
=== DiscountConfiguration shape ===

<code>discount_configuration</code> (<code>care/emr/resources/common/monetary_component.py</code>):

<syntaxhighlight lang="text">DiscountConfiguration {
max_applicable: int (>= 0) # 0 drops all discounts
applicability_order: total_asc | total_desc
}</syntaxhighlight>
== Resource specs (API schema) ==

Charge items are exposed through <code>ChargeItemViewSet</code> (create / retrieve / update / upsert / list / tag actions, plus the <code>apply_charge_item_defs</code> and <code>change_account</code> custom actions). The Pydantic specs in <code>care/emr/resources/charge_item/spec.py</code> build on <code>EMRResource</code> (<code>serialize</code> / <code>de_serialize</code>, with <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks).

{| class="wikitable"
|-
! Spec
! Role
! Notes
|-
| <code>ChargeItemSpec</code>
| shared base
| <code>__model__ = ChargeItem</code>, <code>__exclude__ = ["encounter", "account"]</code>. Fields: <code>id</code>, <code>title</code>, <code>description</code>, <code>status</code>, <code>code</code>, <code>quantity</code>, <code>unit_price_components</code>, <code>note</code>, <code>override_reason</code>. Validators: no duplicate component codes, ≤1 <code>base</code> component
|-
| <code>ChargeItemWriteSpec</code>
| write · create
| Extends base with <code>encounter</code>, <code>patient</code>, <code>account</code>, <code>service_resource</code>, <code>service_resource_id</code>, <code>performer_actor</code> (all <code>UUID4</code>/enum, optional). Requires <code>encounter</code> '''or''' <code>patient</code>; requires <code>service_resource_id</code> when <code>service_resource</code> set
|-
| <code>ChargeItemUpdateSpec</code>
| write · update
| Base fields + <code>performer_actor</code>. Does not re-bind patient/encounter/account
|-
| <code>ChargeItemReadSpec</code>
| read · list & detail
| Base fields + server-side: <code>total_price_components</code>, <code>total_price</code>, <code>charge_item_definition</code> (nested), <code>paid_invoice</code> (nested), <code>tags</code> (objects), <code>service_resource(_id)</code>, <code>created_date</code>, <code>modified_date</code>, <code>paid_on</code>, <code>performer_actor</code>, <code>created_by</code>, <code>updated_by</code>, <code>discount_configuration</code>
|}

Notable validation and binding:

* <code>code</code>, <code>override_reason.code</code>, and component <code>code</code>s are FHIR-aligned <code>Coding</code>s with '''no bound value set'''.
* <code>ChargeItemWriteSpec.perform_extra_deserialization</code> resolves <code>patient</code>/<code>encounter</code>/<code>account</code>/<code>performer_actor</code> from external ids; supplying <code>encounter</code> overrides <code>patient</code> with the encounter's patient, and <code>account</code> is looked up scoped to that patient.
* <code>ChargeItemReadSpec.perform_extra_serialization</code> nests the full <code>ChargeItemDefinitionReadSpec</code> and <code>InvoiceReadSpec</code>, renders tags, and resolves <code>performer_actor</code> / <code>created_by</code> / <code>updated_by</code> from the user cache.

=== Nested / related specs ===

{| class="wikitable"
|-
! Spec
! Used by
! Shape
|-
| <code>Coding</code>
| <code>code</code>, component & override codes
| see [[#coding-shape
|-
| <code>MonetaryComponent</code>
| <code>unit_price_components</code>, <code>total_price_components</code>
| see [[#monetarycomponent-shape
|-
| <code>ChargeItemOverrideReason</code>
| <code>override_reason</code>
| <code>{ text, code? }</code>
|-
| <code>DiscountConfiguration</code>
| <code>discount_configuration</code>
| <code>{ max_applicable, applicability_order }</code>
|-
| <code>ChargeItemDefinitionReadSpec</code>
| <code>charge_item_definition</code> (read)
| full nested definition — see [[References/Charge Item Definition]]
|-
| <code>InvoiceReadSpec</code>
| <code>paid_invoice</code> (read)
| full nested invoice — see [[References/Invoice]]
|-
| <code>UserSpec</code>
| <code>performer_actor</code>, audit users (read)
| see [[References/User & Skills
|}

== Related models ==

<code>ChargeItem</code> is a leaf model — it holds foreign keys rather than owning child rows:

<syntaxhighlight lang="text">facility → FK facility.Facility (PROTECT)
patient → FK emr.Patient (CASCADE)
encounter → FK emr.Encounter (CASCADE, nullable)
charge_item_definition → FK emr.ChargeItemDefinition (CASCADE, nullable)
account → FK emr.Account (CASCADE)
paid_invoice → FK emr.Invoice (CASCADE, nullable)
performer_actor → FK users.User (CASCADE, nullable)</syntaxhighlight>
== Methods & save behaviour ==

Cost resolution and status side effects live in the spec helpers and the viewset, not in the model's <code>save()</code>.

* '''Cost sync (<code>sync_charge_item_costs</code>)''' — runs on every create and on update (unless suppressed). It walks <code>unit_price_components</code>: multiplies the <code>base</code> amount by <code>quantity</code> to seed <code>total_price</code>/<code>base</code>, adds <code>surcharge</code>s, applies <code>discount</code>s (filtered by <code>discount_configuration</code> via <code>apply_discount_configuration</code>), then adds <code>tax</code>es on the taxable price. It writes the resolved breakdown to <code>total_price_components</code> and the sum to <code>total_price</code>, and raises <code>ValidationError</code> if <code>total_price < 0</code> on a non-reversal charge.
* '''Apply from definition (<code>apply_charge_item_definition</code> / <code>POST apply_charge_item_defs</code>)''' — builds a <code>ChargeItem</code> from a <code>ChargeItemDefinition</code>: copies <code>title</code>/<code>description</code>, merges category + global components, evaluates each component's <code>conditions</code> against patient/facility/encounter context (dropping unmet ones), sets <code>status = billable</code>, resolves <code>discount_configuration</code>, defaults the account to the patient's default account, and runs cost sync. <code>reverse</code> negates component amounts to produce a credit.
* '''Cancel (<code>handle_charge_item_cancel</code>)''' — fires on update when <code>status</code> moves into <code>CHARGE_ITEM_CANCELLED_STATUS</code> (<code>not_billable</code> / <code>aborted</code> / <code>entered_in_error</code>). If the charge sits on a '''draft''' invoice, it is removed from the invoice, the invoice is rebalanced and saved, and <code>paid_invoice</code> / <code>paid_on</code> are cleared. Cancelling a charge on a non-draft invoice raises <code>ValidationError</code>. Cost sync is skipped for cancellations.
* '''Update guards (<code>validate_data</code> / <code>perform_update</code>)''' — a charge in a cancelled status can't be updated; updates are blocked when the linked invoice is <code>balanced</code>/<code>issued</code>; <code>status</code> can't be moved by hand into <code>billed</code>/<code>paid</code>; and if the source definition has <code>can_edit_charge_item = False</code>, the pricing fields (<code>unit_price_components</code>, <code>total_price_components</code>, <code>total_price</code>, <code>quantity</code>) are reset from the previous object and cost sync is skipped. After update, a draft <code>paid_invoice</code> is re-synced.
* '''Cancel authorization (<code>authorize_cancel</code>)''' — cancellation is free within <code>CHARGE_ITEM_FREE_CANCEL_PERIOD_MINUTES</code> of creation; after that it needs the <code>can_cancel_charge_item_in_facility</code> permission.
* '''Change account (<code>POST change_account</code>)''' — bulk-moves up to 100 <code>billable</code> charge items to a target account, then queues <code>rebalance_account_task</code> for every affected account.

== API integration notes ==

* The viewset sets <code>facility</code> from the URL and ignores any body value; <code>patient</code> is derived from <code>encounter</code> when one is supplied.
* A charge item must resolve to an <code>account</code> — with none supplied, the patient's default account is used. <code>encounter</code> and <code>charge_item_definition</code> are optional.
* <code>total_price</code>, <code>total_price_components</code>, <code>paid_invoice</code>, and <code>paid_on</code> are server-maintained; don't set them from clients.
* Create and update enforce that <code>performer_actor</code> (and, when applying definitions, the actor) belongs to the facility's organization.
* <code>discount_configuration</code> and <code>tags</code> are structured but deployment-tunable: <code>discount_configuration</code> follows <code>DiscountConfiguration</code>, and tags resolve through the single-facility tag manager.

{{Related}}

References/Charge Item - Revision history

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

Admin: OHC identity seed