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

2026-07-06T04:10:41Z

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

← Older revision		Revision as of 09:40, 6 July 2026
Line 277:		Line 277:
	* <code>extensions</code> is the supported place for custom key-value data without schema migrations; <code>ExtensionValidator</code> checks it, and it surfaces only on the retrieve spec.		* <code>extensions</code> is the supported place for custom key-value data without schema migrations; <code>ExtensionValidator</code> checks it, and it surfaces only on the retrieve spec.
	* Gate account data behind permissions that restrict access to users with rights to financial information.		* Gate account data behind permissions that restrict access to users with rights to financial information.

			{{Navbox billing}}

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

Admin: OHC identity seed

2026-07-04T22:44:04Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=billing
|title=Account
|order=1
|introduced=3.0
|model=Account
|concept=Concepts/Patient
|reference=References/Base models & conventions
}}

An <code>Account</code> is the financial bucket that aggregates every transaction made against a patient within a facility. You touch it indirectly: charge items land on a patient's default account, and invoices and reconciliations settle against it.

Several model fields are opaque <code>JSONField</code>s whose real structure lives in the Pydantic resource specs under <code>care/emr/resources/account/</code>. Each field below is paired with the spec-defined enums, JSON shapes, validation, and read/write schemas that govern it.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/account.py <code>care/emr/models/account.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/account/spec.py <code>care/emr/resources/account/spec.py</code>]
* Default account helper: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/account/default_account.py <code>account/default_account.py</code>]
* Balance sync: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/account/sync_items.py <code>account/sync_items.py</code>]
* Base resource: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>care/emr/resources/base.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>Account</code>
| Aggregates charges and balances for one patient in one facility across encounters
|}

<code>Account</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], which contributes <code>external_id</code>, the audit fields <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and <code>history</code>/<code>meta</code> JSON.

Accounts are perpetual. One active, open account exists per patient per facility (see [[#default-account|<code>get_default_account</code>]]), and charge items land on it. After discharge, the account can be balanced and closed. Invoices are raised against an account or against the items within it.

== <code>Account</code> fields ==

=== Identity & scope ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=Account|section=Identity & scope|name=facility|type=FK → facility.Facility (PROTECT)|notes=yes}}
{{Field|model=Account|section=Identity & scope|name=patient|type=FK → emr.Patient (PROTECT)|notes=yes}}
{{Field|model=Account|section=Identity & scope|name=name|type=CharField(255)|notes=yes}}
{{Field|model=Account|section=Identity & scope|name=description|type=TextField|notes=no}}
{{Field|model=Account|section=Identity & scope|name=primary_encounter|type=FK → emr.Encounter (SET_NULL, nullable)|notes=no}}
|}

=== Status ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=Account|section=Status|name=status|type=CharField(255)|notes=yes}}
{{Field|model=Account|section=Status|name=billing_status|type=CharField(255)|notes=yes}}
{{Field|model=Account|section=Status|name=service_period|type=JSONField (default {})|notes=yes (on spec)}}
|}

=== Balances & totals ===

These decimal totals (<code>max_digits=20, decimal_places=6</code>, default <code>0</code>) are platform-maintained aggregates that [[#balance-sync|<code>sync_account_items</code>]] recomputes. None are client-writable, and none appear on a write spec.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Account|section=Balances & totals|name=total_net|type=DecimalField|notes=Net total before adjustments. Not populated — the <code>sync_account_items</code> logic is commented out, so it holds the default <code>0</code>}}
{{Field|model=Account|section=Balances & totals|name=total_gross|type=DecimalField|notes=Sum of <code>total_price</code> over charge items in <code>paid</code> or <code>billed</code> status}}
{{Field|model=Account|section=Balances & totals|name=total_paid|type=DecimalField|notes=Sum of <code>active</code>+<code>complete</code> payment reconciliations, minus credit-note reconciliations}}
{{Field|model=Account|section=Balances & totals|name=total_balance|type=DecimalField|notes=<code>total_gross − total_paid</code>}}
{{Field|model=Account|section=Balances & totals|name=total_billable_charge_items|type=DecimalField|notes=Sum of <code>total_price</code> over charge items in <code>billable</code> status}}
{{Field|model=Account|section=Balances & totals|name=total_price_components|type=JSONField (default {})|notes=Intended price-component breakdown (taxes, discounts, etc.) as a list of <code>MonetaryComponent</code> (see [[#monetarycomponent-shape}}
{{Field|model=Account|section=Balances & totals|name=cached_items|type=JSONField (default {})|notes=Denormalized snapshot of the account's charge items, serialized as a <code>list</code> on retrieve. Not populated — the sync logic is commented out}}
{{Field|model=Account|section=Balances & totals|name=calculated_at|type=DateTimeField (nullable)|notes=When the balances were last computed; set to <code>care_now()</code> on each sync}}
|}

=== Tags & extensions ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Account|section=Tags & extensions|name=tags|type=ArrayField[int] (default [])|notes=Tag IDs applied to the account; rendered through <code>SingleFacilityTagManager</code> on read}}
{{Field|model=Account|section=Tags & extensions|name=extensions|type=JSONField (default {})|notes=Open bag for deployment-specific metadata. <code>ExtensionValidator</code> checks it against <code>ExtensionResource.account</code>; surfaced only on the retrieve spec}}
|}

== Enum values ==

=== <code>AccountStatusOptions</code> values ===

Stored as the raw enum value string in <code>status</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>active</code>
| Open and in use (the default-account state)
|-
| <code>inactive</code>
| No longer actively used
|-
| <code>entered_in_error</code>
| Created in error
|-
| <code>on_hold</code>
| Temporarily paused
|}

Values use underscores (<code>entered_in_error</code>, <code>on_hold</code>), not the FHIR-style hyphenated forms.

=== <code>AccountBillingStatusOptions</code> values ===

Stored as the raw enum value string in <code>billing_status</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>open</code>
| Billing open and accruing (the default-account state)
|-
| <code>carecomplete_notbilled</code>
| Care complete, not yet billed
|-
| <code>billing</code>
| Billing in progress
|-
| <code>closed_baddebt</code>
| Closed as bad debt
|-
| <code>closed_voided</code>
| Closed and voided
|-
| <code>closed_completed</code>
| Closed, billing completed
|-
| <code>closed_combined</code>
| Closed, combined into another account
|}

== JSON field shapes ==

=== <code>service_period</code> shape ===

<code>service_period</code> stores a <code>PeriodSpec</code> (from [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>resources/base.py</code>]):

<syntaxhighlight lang="text">PeriodSpec {
start: datetime | null # ISO 8601, timezone-aware
end: datetime | null # ISO 8601, timezone-aware
}</syntaxhighlight>
<code>PeriodSpec.validate_period</code> enforces three rules:

* <code>start</code>, if present, must be timezone-aware — a naive datetime raises <code>"Start Date must be timezone aware"</code>.
* <code>end</code>, if present, must be timezone-aware — <code>"End Date must be timezone aware"</code>.
* With both present, <code>start <= end</code>, or <code>"Start Date cannot be greater than End Date"</code>.

The default account sets only <code>start</code>, formatted as <code>"%Y-%m-%dT%H:%M:%S.%fZ"</code> from <code>care_now()</code>.

The FHIR-style [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/period.py <code>Period</code>] common type (<code>{ id?, start?, end? }</code>, <code>extra="forbid"</code>) is a related but distinct shape — <code>Account</code> binds <code>service_period</code> to <code>PeriodSpec</code>, not <code>Period</code>.

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

<code>total_price_components</code> is meant to hold a list of [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/monetary_component.py <code>MonetaryComponent</code>] entries, the same shape used across billing:

<syntaxhighlight lang="text">MonetaryComponent {
monetary_component_type: base | surcharge | discount | tax | informational
code: Coding | null
factor: Decimal(max_digits=20, decimal_places=6) | null
amount: Decimal(max_digits=20, decimal_places=6) | null
tax_included_amount: Decimal(max_digits=20, decimal_places=6) | null
global_component: bool = false
conditions: EvaluatorConditionSpec[] = []
}</syntaxhighlight>
<code>MonetaryComponent</code> validation: <code>tax_included_amount</code> is allowed only on a <code>base</code> component; a <code>base</code> component must carry an <code>amount</code>, no <code>factor</code>, and no <code>conditions</code>; <code>amount</code> and <code>factor</code> are mutually exclusive; exactly one of <code>amount</code>/<code>factor</code> is required unless the entry is a <code>global_component</code> with a <code>code</code>.

== Resource specs (API schema) ==

The API layer lives in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/account/spec.py <code>resources/account/spec.py</code>]. Every spec builds on <code>EMRResource</code> (<code>serialize</code> / <code>de_serialize</code>, with the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks). <code>AccountSpec</code> sets <code>__exclude__ = ["patient"]</code> and binds <code>___extension_resource_type__ = ExtensionResource.account</code>.

{| class="wikitable"
|-
! Spec class
! Role
! Fields exposed (beyond base)
|-
| <code>AccountSpec</code>
| shared base
| <code>id</code>, <code>status</code>, <code>billing_status</code>, <code>name</code>, <code>service_period</code> (<code>PeriodSpec</code>), <code>description</code>
|-
| <code>AccountCreateSpec</code>
| write · create
| base + <code>patient</code> (UUID, required)
|-
| <code>AccountUpdateSpec</code>
| write · update
| base + <code>primary_encounter</code> (UUID, optional)
|-
| <code>AccountMinimalReadSpec</code>
| read · minimal
| base + <code>total_gross</code>, <code>total_paid</code>, <code>total_balance</code>, <code>total_billable_charge_items</code> (all <code>Decimal</code> 20/6), <code>calculated_at</code>, <code>created_date</code>, <code>modified_date</code>
|-
| <code>AccountReadSpec</code>
| read · list
| minimal + <code>patient</code> (serialized <code>PatientListSpec</code>), <code>tags</code> (rendered tag dicts)
|-
| <code>AccountRetrieveSpec</code>
| read · detail
| read + <code>patient</code> (serialized <code>PatientRetrieveSpec</code>), <code>primary_encounter</code> (serialized <code>EncounterRetrieveSpec</code> when set), <code>cached_items</code> (<code>list</code>), <code>total_price_components</code> (<code>dict</code>), <code>extensions</code> (<code>dict</code>)
|}

=== Validation & server-side behaviour ===

* '''Create''' (<code>AccountCreateSpec</code>): mixes in <code>ExtensionValidator</code> to validate <code>extensions</code>, and requires <code>patient</code> as a UUID. <code>perform_extra_deserialization</code> resolves it via <code>get_object_or_404(Patient, external_id=...)</code> and assigns <code>obj.patient</code>; <code>patient</code> is otherwise excluded from the base serialize loop.
* '''Update''' (<code>AccountUpdateSpec</code>): mixes in <code>ExtensionValidator</code>; <code>primary_encounter</code> is optional. When supplied, <code>perform_extra_deserialization</code> resolves it via <code>get_object_or_404(Encounter, external_id=...)</code> and assigns <code>obj.primary_encounter</code>.
* '''Status / billing_status''': the Pydantic enums <code>AccountStatusOptions</code> / <code>AccountBillingStatusOptions</code> reject any value outside their members.
* '''Read serialization''': <code>perform_extra_serialization</code> sets <code>mapping["id"] = obj.external_id</code>. <code>AccountReadSpec</code> serializes the patient (<code>PatientListSpec</code>) and renders tags via <code>SingleFacilityTagManager</code>; <code>AccountRetrieveSpec</code> serializes the full patient (<code>PatientRetrieveSpec</code>, scoped to <code>obj.facility</code>) and, when present, the primary encounter (<code>EncounterRetrieveSpec</code>).
* '''Totals are read-only''': balance and aggregate fields appear only on read specs. <code>sync_account_items</code> recomputes them; client payloads never set them.

<a id="default-account"></a>

=== Default account ===

<code>get_default_account(patient, facility)</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/account/default_account.py <code>default_account.py</code>]) returns the first account for that <code>patient</code> + <code>facility</code> with <code>status = active</code> and <code>billing_status = open</code>. If none exists, it creates one with:

* <code>status = active</code>, <code>billing_status = open</code>
* <code>service_period = { "start": care_now() }</code> (start only)
* <code>name = "{patient.name} {YYYY-MM-DD}"</code>

This runs when the first charge item is added, so the default account materializes on demand. Clients normally never create accounts directly.

<a id="balance-sync"></a>

=== Balance sync ===

<code>sync_account_items(account)</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/account/sync_items.py <code>sync_items.py</code>]) recomputes the totals under an <code>AccountLock</code>:

* <code>total_billable_charge_items</code> = <code>Σ total_price</code> of charge items with status <code>billable</code>
* <code>total_gross</code> = <code>Σ total_price</code> of charge items with status <code>paid</code> or <code>billed</code>
* <code>total_paid</code> = <code>Σ amount</code> of <code>active</code> + <code>complete</code> non-credit-note payment reconciliations − the same for credit notes
* <code>total_balance</code> = <code>total_gross − total_paid</code>
* <code>calculated_at</code> = <code>care_now()</code>

Every sum runs through <code>care_round</code>. <code>total_net</code>, <code>cached_items</code>, and <code>total_price_components</code> are not updated — their logic is commented out — so they hold their defaults. <code>rebalance_account_task(account_id)</code> is the Celery wrapper that runs the sync and saves.

== Related models ==

<code>Account</code> is the only class in <code>account.py</code>. Its relationships:

<syntaxhighlight lang="text">facility → FK facility.Facility (PROTECT)
patient → FK emr.Patient (PROTECT)
primary_encounter → FK emr.Encounter (SET_NULL, nullable)</syntaxhighlight>
[[References/Charge Item|Charge items]] reference the account they belong to and drive its totals; [[References/Invoice|invoices]] and [[References/Payment Reconciliation|payment reconciliations]] settle against the account or its items.

== API integration notes ==

* The REST API aligns to the FHIR <code>Account</code> resource, but spec field names and enum values differ (enums use underscores, not hyphens).
* <code>get_default_account</code> creates the default account when the first charge item is added for a patient in a facility; clients normally do not create accounts directly.
* On '''create''', supply <code>patient</code> as the patient's <code>external_id</code> (UUID); <code>facility</code> is server-scoped.
* On '''update''', <code>primary_encounter</code> accepts an encounter <code>external_id</code> (UUID); only the base fields plus <code>primary_encounter</code> are mutable.
* Balance and aggregate fields (<code>total_net</code>, <code>total_gross</code>, <code>total_paid</code>, <code>total_balance</code>, <code>total_billable_charge_items</code>, <code>total_price_components</code>, <code>cached_items</code>, <code>calculated_at</code>) are platform-maintained and appear only on read specs — never set them from clients.
* <code>service_period</code> requires timezone-aware datetimes with <code>start <= end</code>.
* <code>extensions</code> is the supported place for custom key-value data without schema migrations; <code>ExtensionValidator</code> checks it, and it surfaces only on the retrieve spec.
* Gate account data behind permissions that restrict access to users with rights to financial information.

{{Related}}

References/Account - Revision history

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

Admin: OHC identity seed