Billing launch Operation

Canonical	../OperationDefinition/billing-launch
Status	draft · 1.26.0
Invocation	POST [base]/$billing-launch
Level	system
Affects state	yes -- not safe to repeat
Source	FSH · JSON

Open a signed-in ClinicAid session for a clinic, optionally prefilled from one appointment, and return the single-use address to send the person to.

POST [base]/$billing-launch

This is a handoff, not a billing operation. No claim is created here, no money moves, and nothing is adjudicated. The reply is a URL. What happens after a person follows it is ClinicAid's, and this endpoint learns of it only later and only in outline: a separate read-back records that the appointment was invoiced, as a timestamp on the appointment-invoiced extension. No Invoice resource is written by this operation. For fee codes, amounts or claim status, ask ClinicAid.

affectsState is true. The launch spends a clinic's ClinicAid credential and mints a single-use signed-in address, so it is a POST and is neither cacheable nor safe to repeat speculatively. Repeating one in flight is refused as launchInProgress rather than opening a second session.

The destination decides the shape of the request

destination names which ClinicAid screen opens, and it governs two other parameters:

destination	appointment	item
appointmentInvoice (the default)	required	admitted, repeatable
every other destination	refused	refused

A listing sent an appointment or an item is refused, not quietly ignored -- dropping either would open a screen the caller did not ask for, or bill a line it did not send. Omitting destination entirely reads as appointmentInvoice, which is what keeps a caller written before destinations existed meaning what it always meant.

Two shapes for a billing item

An item may be sent as a nested item part carrying its three sub-parts, which is the shape to write against. The three sub-part names are ALSO read at the top level as a legacy single-item shape, still accepted for callers written before item existed. The legacy shape carries at most one item. Do not mix them.

A legacy body carrying billedUnits or diagnosticCode with no healthServiceCode cannot be read as an item at all; it is forwarded to the service as sent rather than dropped, so the service's own validator refuses it loudly instead of this gateway silently unsaying what the caller submitted.

Reading the reply

A reply is published only when the launch launched, so status has exactly one value, launched, and launchUrl is present exactly then.

Every other ending is an OperationOutcome under the HTTP status its reading gives it, carrying the refusal reason as a coding on issue.details from the Billing Launch Refusal Reason set. Match on that coding, never on the advisory sentence beside it: the sentence is developer-facing, is not a translation of the code, and is not stable. Tolerate a reason this guide does not list -- the platform and this guide ship on different cadences, and a launch refused for an unrecognised reason is still refused.

Asking for a launch requires the billing-launch permission. A caller without it is refused before any gate that would name a reason, so that outcome carries no refusal coding.

Request parameters

Parameter	Card.	Type	Documentation
clinicId	1..1	string	The clinic whose ClinicAid account the launch spends. A string that must parse as a UUID; a value that does not parse is refused. Required for every destination.
destination	0..1	code binding: Billing Launch Destination Value Set (required)	Which ClinicAid screen to open. Omitted reads as appointmentInvoice. Echoed on the reply. A word outside the value set names no routable screen and is refused.
appointment	0..1	Reference → Appointment Profile	The appointment to bill, as a literal relative reference of the form Appointment/{id}. REQUIRED when the destination is appointmentInvoice and REFUSED for every other destination. It must be a Reference: a plain string carrying the same text is not read, and a contained resource is refused rather than dropped.
item	0..*	(parts)	One billing item, prefilling one invoice line. Repeatable, and admitted only by the appointmentInvoice destination. An item whose healthServiceCode is absent cannot be built and is refused by the service rather than dropped here.
↳ healthServiceCode	1..1	string	The item's service code, as the vendor spells it. An empty code is forwarded as sent, because the service decides what an empty code means.
↳ billedUnits	0..1	integer	The item's units.
↳ diagnosticCode	0..1	string	The item's diagnostic code, forwarded to the vendor exactly as sent. UNBOUND AND UNTYPED ON PURPOSE: the vendor owns the rule that judges it. In Ontario this is a code from the provincial diagnostic set described by on-ohip-diagnostic-codes, which is ICD-9-like in shape and is NOT ICD-9 -- see that system before deriving one.
healthServiceCode	0..1	string	LEGACY single-item shape, read at the top level for callers written before item existed. Prefer the item part. Do not send both shapes.
billedUnits	0..1	integer	LEGACY single-item shape. Prefer the item part.
diagnosticCode	0..1	string	LEGACY single-item shape. Prefer the item part. See the note on the nested diagnosticCode: it is unbound for the same reason.

Response parameters

Parameter	Card.	Type	Documentation
status	1..1	string	What became of the launch. A reply is published only when the launch launched, so the only value is launched. Every other ending is an OperationOutcome, not a reply. Sent as a STRING, not a code: every part of this reply is published as a string except destination, and a strict parser looking for valueCode here will find nothing.
destination	1..1	code binding: Billing Launch Destination Value Set (required)	The destination that was opened, echoed back. Always present, and always resolved: a request that named none is answered with appointmentInvoice, so the reply says which screen was opened rather than repeating the caller's silence. This is the one part of the reply sent as a code rather than a string, because it is a bounded vocabulary this specification publishes.
launchUrl	1..1	string	The single-use signed-in address to send the person to. Always present on a reply, because a reply is only published when the launch launched. Treat it as a credential: single-use, and not to be logged, stored or shared. Sent as a STRING rather than a url deliberately -- it is opaque, and it must be opened exactly as minted rather than normalised.
appointment	0..1	Reference → Appointment Profile	The appointment the launch was opened for, echoed back. Present exactly when the destination carries one, which today means appointmentInvoice alone -- so its ABSENCE is meaningful and is not an omission: it says the screen opened has no subject.
message	1..1	string	Display words a caller may show.