Appointment Invoiced Extension

Canonical	../StructureDefinition/appointment-invoiced
Status	draft · 1.26.0
Base	Extension (constraint)
Context	Appointment (element)
Source	FSH · JSON

That an invoice covering this appointment's visit has been observed at the billing vendor, and the instant it was observed.

FSH

The authored source of truth: extensions/AppointmentInvoicedExtension.fsh (edit on GitHub). One FSH file may define several related artifacts.

// AppointmentInvoicedExtension.fsh
// That an invoice for this appointment's visit has been SEEN at the billing vendor, and when it was
// seen. Carried on `Appointment`.
//
// IT IS AN OBSERVATION, NOT A WORKFLOW STATE, and that is the whole reason it is a separate element
// rather than a status. `Appointment.status` carries the states a clinic sets by hand, including
// the ones a clinic uses to mean "billed". This carries only what a read-back of the billing vendor
// confirmed. The two answer different questions, and neither can be derived from the other: an
// appointment marked billed by hand may have no invoice, and an invoiced visit may never have been
// marked.
//
// ABSENCE IS NOT "NOT INVOICED", AND THE DIFFERENCE MATTERS MOST WHERE IT IS EASIEST TO MISS. The
// extension is written only when an invoice was observed. It is absent while the read-back has not
// run, while it has run and not yet found one, and wherever no read-back exists at all. A user
// interface may render absence as "not invoiced" -- erring toward prompting a human look is a
// reasonable UI choice -- but a COUNT of invoiced visits taken as "carries the extension" and a
// count of uninvoiced visits taken as "does not" are not complements, and the second under-reports.
// Anything reporting on billing coverage has to treat absence as unknown.
//
// THE INSTANT IS WHEN THE INVOICE WAS OBSERVED, not when it was raised, not when the service was
// delivered, and not when the appointment was marked anything. Once stored the observation is not
// rewritten, so the instant names the first confirmation rather than the most recent check.
//
// THE CANONICAL HERE IS NOT THE ONE THE SOFTWARE WRITES TODAY. The migration note is in the
// Description below, which is the text that travels inside the package; the handbook states the
// rule and indexes every published artifact in this position, in
// `docs/guide/patterns/canonical-urls.md`.

Extension: AppointmentInvoiced
Id: appointment-invoiced
Title: "Appointment Invoiced Extension"
Description: """
That an invoice covering this appointment's visit has been observed at the billing vendor, and the
instant it was observed.

**An observation, not a workflow state.** `Appointment.status` carries the states a clinic sets by
hand; this carries only what a read-back of the vendor confirmed. Neither can be derived from the
other, and a status that reads as billed is not evidence that this extension would be present.

**Absence means the observation has not been made -- NOT that the visit was not invoiced.** The
extension is written only when an invoice was seen. It is absent while a read-back has not run,
while it has run without finding one, and wherever no read-back exists. Rendering absence as "not
invoiced" in a user interface is a defensible choice; counting it as "no invoice exists" is not, and
a report built that way under-states billing coverage. Treat absence as unknown.

**The instant is when the invoice was observed**, not when it was raised and not when the service
was delivered. The observation is not rewritten once stored, so the instant names the first
confirmation rather than the most recent check.

**Written at most once per appointment.** A reader encountering more than one copy should take the
first rather than merge them.

**MIGRATION.** Nexus EMR writes this extension today at
`http://services.well.com/fhir/StructureDefinition/appointment-invoiced` (FHIR-378). That address is
live in stored appointments and in code, and is under migration to the canonical declared here.
Write the canonical; when reading, match on the URL suffix `appointment-invoiced` so that
appointments filed under either address are seen.
"""
* ^url = "../StructureDefinition/appointment-invoiced"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "Appointment"
* value[x] 0..0
* extension contains
    invoiced 1..1 MS and
    observedAt 1..1 MS
* extension[invoiced] ^short = "The observed fact: an invoice for this visit exists"
* extension[invoiced].value[x] 1..1 MS
* extension[invoiced].value[x] only boolean
* extension[invoiced].valueBoolean ^definition = "The observed fact. Only `true` is written: the extension records a positive observation and is absent otherwise. A reader MUST require `true` and treat any other value, or a missing child, as no observation at all rather than as a statement that no invoice exists."
* extension[observedAt] ^short = "When the invoice was observed at the vendor"
* extension[observedAt].value[x] 1..1 MS
* extension[observedAt].value[x] only instant
* extension[observedAt].valueInstant ^definition = "When the read-back observed the invoice. NOT when the invoice was raised, when the service was delivered, or when the appointment was marked billed. Required: an observation with no instant cannot be aged, and a reader should treat one lacking a usable instant as no observation."