Billing

Charge Item

A ChargeItem 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 ; it always…

3.1 · versioned documentation · 10 min read

A ChargeItem 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 Account.

Source:

• Model: care/emr/models/charge_item.py
• Resource specs: care/emr/resources/charge_item/ (spec.py, sync_charge_item_costs.py, apply_charge_item_definition.py, handle_charge_item_cancel.py)
• Viewset: care/emr/api/viewsets/charge_item.py

The Django model is only the storage layer. Several fields are opaque JSONFields whose structure lives in the Pydantic resource specs under care/emr/resources/charge_item/, 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

ChargeItem extends EMRBaseModel (shared MANSOQ EMR base with external_id, audit fields — created_by/updated_by/created_date/modified_date — and soft-delete semantics — see Base model).

ChargeItem fields

Context & relationships

Description & status

Pricing

Service source

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

Invoicing & tags

Enums

Status values

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

(planned exists in the source as a commented-out option and is not currently selectable.)

not_billable, aborted, and entered_in_error form the cancelled set (CHARGE_ITEM_CANCELLED_STATUS). Moving into this set on update triggers the cancel side effect (see Methods & save behaviour). billed and paid cannot be set by hand — the viewset rejects manual transitions into them.

Service resource types

service_resource is constrained by ChargeItemResourceOptions:

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

MonetaryComponentType values

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

DiscountApplicability values

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

max_applicable = 0 drops all discounts.

JSON field shapes

Coding shape

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

Coding {
  system?:  str
  version?: str
  code:     str        # required
  display?: str
}

MonetaryComponent shape

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

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
}

Validation: exactly one of amount/factor (unless global_component with a code); base must have amount, no factor, no conditions; tax_included_amount only on base; duplicate component codes are rejected.

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

ChargeItemOverrideReason shape

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

ChargeItemOverrideReason {
  text: str            # required
  code?: Coding        # no bound value set
}

DiscountConfiguration shape

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

DiscountConfiguration {
  max_applicable:      int (>= 0)               # 0 drops all discounts
  applicability_order: total_asc | total_desc
}

Resource specs (API schema)

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

Notable validation and binding:

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

Nested / related specs

Related models

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

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)

Methods & save behaviour

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

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

API integration notes

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

Related

• Reference: Account
• Reference: Charge Item Definition
• Reference: Invoice
• Reference: Payment Reconciliation
• Reference: Patient
• Reference: Encounter
• Reference: User
• Reference: Base model
• Source: charge_item.py on GitHub
• Source: charge_item resource specs on GitHub

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/billing/charge-item.mdx:1 · f6e9f05f