Invoice Profile

Canonical	../StructureDefinition/nexus-emr-core-invoice
Status	draft · 1.26.0
Base	Invoice (constraint)
CQL primary code path	type — what this means
Source	FSH · JSON

Nexus EMR profile for Invoice representing Canadian provider-side billing records. Aligned with Oscar Pro's billing model: one invoice per claim header, with its line items inline. Phase 1 scope: Ontario OHIP billing via Oscar Pro.

TypedFhir API / Pydantic schema

The typed accessor surface Invoice exposes for Invoice — generated from this IG's compiled profile; each typed accessor has a validating raw-FHIR twin (xRaw) where marked. The three ports are parity-enforced.

The AI-facing shape: from typed_fhir.facade.generated.schemas import InvoiceSchema — model_json_schema() is a structured-output / tool definition; instantiating validates an extraction. Generated source.

class InvoiceSchema(BaseModel):
    """AI-facing shape of the Invoice profile: the facade's typed accessor
    surface (curated + salient fields) as a pydantic model. `model_json_schema()` is a
    structured-output / tool schema; instantiating validates an extraction."""

    model_config = ConfigDict(extra="forbid")

    status: Literal["balanced", "cancelled", "draft", "entered-in-error", "issued"] | None = Field(
        None,
        description=(
            "draft | issued | balanced | cancelled | entered-in-error. FHIR `InvoiceStatus`. "
            "**Required binding — cannot carry raw Oscar status codes directly.** Use the "
            "`oscar-billing-status-extension` on this invoice to preserve the 10-code Oscar enum. "
            "Oscar → FHIR status mapping (see oscar-to-fhir feature docs): | Oscar | FHIR "
            "Invoice.status | Notes | |---|---|---| | O (Bill OHIP) | `issued` | | | P (Bill "
            "Patient) | `issued` | + `payProgram` extension | | W (Bill WCB) | `issued` | + "
            "`payProgram=WCB` | | B (Submitted OHIP) | `issued` | awaiting adjudication | | X "
            "(Bad Debt) | `cancelled` | + `oscarBillingStatus=X` | | H (Capitated) | `balanced` | "
            "+ `shadowBill=true` | | I (Bonus Codes) | `issued` | + `oscarBillingStatus=I` | | S "
            "(Settled) | `balanced` | | | D (Deleted) | `cancelled` | | | N (Do Not Bill) | "
            "`entered-in-error` | | The table is the contract. A reader meeting an Invoice whose "
            "`status` does not match the source status it was converted from is meeting a "
            "converter that has not caught up, and should read the table rather than the value. "
            "Invoice.status — 1..1"
        ),
    )
    type: Concept | None = Field(
        None,
        description=(
            "Type of invoice — carries pay_program coding for Canadian billing. FHIR "
            "`Invoice.type` carries the destination payer / program classification for a bill. In "
            "1.9.8 this lived on a custom `payProgram` extension; 1.9.9 migrated it to "
            "`Invoice.type.coding` using the same OscarPayProgramCS code system so FHIR consumers "
            "can read it without unpacking a custom extension. The extensible binding permits "
            "additional coding systems alongside the Oscar coding (e.g. future AHCIP/MSP payer "
            "program codes). Invoice.type — 0..1"
        ),
    )
    subject: Reference | None = Field(
        None,
        description=(
            "The patient who received the services. The individual or set of individuals "
            "receiving the goods and services billed in this invoice. Invoice.subject — 1..1"
        ),
    )
    date: FuzzyDate | None = Field(
        None,
        description=(
            "Billing date. Date/time(s) of when this Invoice was posted. Note: The list of types "
            "may be constrained as appropriate for the type of charge item. Invoice.date — 0..1"
        ),
    )
    participant: dict | None = Field(
        None,
        description=(
            "Billing provider and related roles (billing, appointment, assistant, referring). "
            "Indicates who or what performed or participated in the charged service. "
            "Invoice.participant — 0..*"
        ),
    )
    issuer: Reference | None = Field(
        None,
        description=(
            "Organization issuing the invoice. The organizationissuing the Invoice. Note: "
            "Practitioners and Devices can be associated with multiple organizations. It has to "
            "be made clear, on behalf of which Organization the services have been rendered. "
            "Invoice.issuer — 0..1"
        ),
    )
    line_item: dict | None = Field(
        None,
        description=(
            "One line per billing service code. One line item per billed service. Each line "
            "carries an OHIP fee code (`chargeItemCodeableConcept`), a price component (fee "
            "amount + quantity), and up to three diagnostic code extensions (`DIAGNOSTIC_1` / "
            "`DIAGNOSTIC_2` / `DIAGNOSTIC_3`). **Note on OHIP submission:** Oscar stores up to 3 "
            "dx codes per line as a product feature, but OHIP's H-file format allows only 1 dx "
            "per service line at submission time. Extra slots are preserved in FHIR for "
            "round-trip fidelity. Invoice.lineItem — 1..*"
        ),
    )
    total_gross: dict | None = Field(
        None,
        description=(
            "Total gross amount. Invoice total, tax included. Note: There is no reason to carry "
            "the price in the instance of a ChargeItem unless circumstances require a manual "
            "override. The list prices or are usually defined in a back catalogue of the billing "
            "codes (see ChargeItem.definition). Derived profiles may require a "
            "ChargeItem.overrideReason to be provided if either factor or price are manually "
            "overridden. Invoice.totalGross — 0..1"
        ),
    )
    note: dict | None = Field(
        None,
        description=(
            "Free-text comment. Comments made about the invoice by the issuer, subject, or other "
            "participants. Invoice.note — 0..*"
        ),
    )