End-to-end flow

Appointment → visit → sales order → invoice

How a booking becomes money owed. The appointment is the booking, the visit is the encounter, the sales order collects charges at the desk, and the clinic invoice freezes them under the Legal Entity.

Appointment, visit, sales order, invoice issue shipped Payments later

On this page Overview 1. Book 2. Arrive 3. Care 4. Ready to bill 5. Checkout 6. Invoice 7. Complete Key rules

Overview

Appointment (scheduled) Schedule appointments.manage │ check-in ── or ── walk-in (no appointment) ▼ Visit (checked_in → in_room ⇄ waiting) Whiteboard visits.manage │ SOAP note, diagnostic orders (lab works), treatment plans │ owner approves plan ─────────────┐ ▼ │ charges Visit (ready_to_bill) ── Checkout ──► SalesOrder (open) Checkout checkout.manage │ │ split / merge / void / discounts ▼ ▼ Visit (completed) Invoice (built) per Legal Entity │ ▼ Payment (intended) per Location drawer

Record	Code	Statuses	Scope
`Appointment`	—	`scheduled` \| `checked-in` \| `canceled` \| `no-show`	Location
`Visit`	`VI-000123`	`checked_in` → `in_room` ⇄ `waiting` → `ready_to_bill` → `completed`	Location
`TreatmentPlan`	`TP-000123`	`draft` → `pending_approval` → `approved` \| `rejected`	Patient, origin Location
`LabWork`	via order	`requested` … `completed` \| `cancelled`	Diagnostic order
`SalesOrder`	`SO-000123`	`open` \| `merged` \| `voided` \| `invoiced`	Location (one Legal Entity, one currency)
`Invoice`	`INV-000123`	`issued`	Legal Entity header, Location attribution

1. Book

Front desk books an Appointment on the Schedule: patient, time, optional staff and rooms/equipment. Recurring series create virtual slots until they are touched.
canceled and no-show are terminal and never create a visit.
An appointment carries no charges. Nothing billable hangs off it.

2. Arrive

Check-in (Schedule popover): appointment → checked-in, creates a Visit in checked_in, Waiting, arrived_at now, staff copied from the booking. Idempotent.
Walk-in (New Visit): creates a visit with no appointment. Linking a same-day scheduled appointment is optional and stamps it checked-in.
One visit per patient. A client with two pets is two visits.
Undo check-in only while the visit is still checked_in in Waiting. It destroys the visit and returns the appointment to scheduled.

3. Care

The visit moves across the Whiteboard (in_room in any room; waiting when seen and sent back to the waiting room). The clinical documents linked to the visit decide what will be charged:

Document	Billable when	Charge
SOAP note	Never	Clinical record only
Treatment plan (visit-linked)	`approved` by the owner (email link / QR) or by staff	One line per plan item at its snapshotted price; plus an `adjustment` line if the final price was overridden (`price − items_total`, may be negative)
Lab work on a visit-linked diagnostic order	Has a catalog item and is not `cancelled`	One line at the Location-effective catalog price at checkout time

Draft, pending, and rejected plans are never charged. Chart-origin plans (no visit) are not picked up by checkout.

4. Ready to bill

Staff set the visit to ready_to_bill. The room is cleared, the card leaves Floor and stays on Pipeline. ready_to_bill_at is stamped.
The card (and the visit page) shows Checkout for Staff with checkout.manage when the plan includes the checkout feature.

5. Checkout (sales order)

POST /app/visits/:id/checkout picks the target order, appends every visit charge not already on an order, and redirects to it.

The visit’s linked open sales order (home), else
an open order at this Location that already holds lines for the visit, else
a new open order (payer = primary pet parent, opened_by = current Staff).

Each visit gets its own order by default. Staff merge or split at the desk when charges should share a bill. After a partial split a visit may span several open orders: auto-charges stay on the home order; the visit cart can add a line to another associated open order without changing the home link. Full merge/split retargets the home when all of a visit’s lines move. Lines are grouped by patient and show the visit code.

Keeping the order in sync

Event	Effect on open orders
Checkout clicked again	Nothing new (idempotent)
Visit-linked plan approved after checkout	Its lines are appended automatically to the open order already holding that visit
Lab work cancelled	Its line is removed from any open order
Sync charges on the order	Re-scans every visit on the order and appends missing charges
Catalog price changed	Existing lines keep their snapshotted price

At the desk

Manual lines: add catalog items (retail, extras) at the Location-effective price.
Discounts: per line and per order (percent or fixed amount). Totals are computed, not stored.
Split: move selected lines to a new order, optionally for another payer (e.g. two owners share a bill). Neither side may go negative.
Merge: pull other open orders at the same Location into one. Sources become merged.
Void: deletes the lines so their sources can be charged again on another order.

Split and merge keep the combined total to the cent. Details: docs/functional/checkout.md.

6. Invoice Built (issue)

Clinic AR vs SaaS Clinic invoices live under Clinic → Invoices (invoices.*). BillingInvoice / Settings → Billing / billing.* remain SaaS (TaskPaws charging the clinic). Payments, taxes, PDF, and cross-site AR alerts are still later.

Issue an invoice from an open order (POST /app/checkout/:id/invoice); the order becomes invoiced and locks.
Numbering per Legal Entity (INV-000123). Issuer snapshot: legal name, tax ID, currency (fiscal address still intended).
Bill-to = payer address snapshot; ship-to = selectable parent from payer_candidates; optional notes frozen at issue.
Lines, prices, line and order discounts (including each line's share of the order discount) are frozen. Revenue is attributed to the Location.
Payments, stock deduction, and unpaid balances at other Locations remain intended.

See Billing and finance and docs/functional/clinic-invoices.md.

7. Complete

Staff set the visit to completed (Pipeline). completed_at is stamped; it is hidden from Floor and, by default, from Pipeline.
Completing a visit does not touch its order, and checkout does not complete the visit. The two are independent today.

Key rules

Charges belong to the visit, never to the appointment.
One source, one line: each plan item, overridden plan, and lab work can sit on exactly one line across all orders (unique index). Moving a line keeps its source, so a later sync never duplicates it.
Prices are snapshotted when the line is created and never change on split or merge.
Location comes from the workspace, never from params. Orders from another Location or Organization return 404.
Only open orders change. merged, voided, and invoiced are read-only.

Who does what

Role	Book	Check-in / move visit	Approve plan	Checkout	Invoices
Organization administrator	Yes	Yes	Yes	Manage	Manage
Organization manager	No	Read	No	Read	Read
Location administrator	Yes	Yes	Yes	Manage	Manage
Receptionist	Yes	Yes	No	Manage	Manage
Veterinarian	No	Yes	Yes	Read	Read

Plan approval by staff needs soap.manage; owners approve from the emailed link without a session. Full grants: RBAC.