Functional contract
Billing and finance
Clinic invoice issue from a sales order is built. Payments, cash-up, taxes, and reports remain intended. Clinic invoices are hybrid: the legal header comes from the Location’s Legal Entity; the sale is attributed to the Location where the work or retail happened. Payouts follow the Legal Entity’s merchant account. Drawers close per Location. For TaskPaws platform subscriptions (plans, credits, Stripe), see SaaS billing.
Invoices
Built (v1): issue one invoice from one open sales order under Clinic → Invoices (invoices.*). Do not confuse with Settings → Billing / billing.* / BillingInvoice. Contract: docs/functional/clinic-invoices.md.
When a Location charges a client:
- Legal name, tax ID / EIN, and currency come from that Location’s Legal Entity (fiscal address and tax configuration still intended).
- Line items, providers, and revenue attribution are tagged to that Location.
- Amounts stored on the invoice are the effective prices at the time of sale (Catalog and pricing), frozen with line and order discount shares.
Historical invoices do not change if the Location is later moved to another Legal Entity.
Payments
| Concern | Level | Behavior |
|---|---|---|
| Merchant account (e.g. Stripe Connect) | Legal Entity | Locations A and B that share an entity settle to that entity’s bank; Location C with its own entity settles separately |
| Card terminal | Location | Hardware and “which desk took the payment” are site-local |
| Cash / check | Location | Counted in that site’s drawer |
| Payment application | Location + Legal Entity | Applied to invoices of that Location’s entity; do not silently pay another entity’s AR |
A client may have invoices under more than one Legal Entity in the same Organization. Those are separate balances.
Cross-site balances
If a client owes Location C and presents at Location A:
- Show an alert that there is an outstanding balance at another site (name the Location).
- Do not add C’s balance onto A’s invoice.
- Do not net or auto-collect C’s debt while checking out at A.
- Collecting C’s balance is done in Location C’s context (or by an Organization admin using C’s Legal Entity), so money and tax stay on the correct EIN.
Same-entity, multi-site AR policy (A and B share an EIN) can allow an Organization admin to collect a sister site’s invoice without switching, but the payment remains attributed to the original Location. Default for v1: always collect in the originating Location’s context so behavior is identical for same-EIN and split-EIN groups.
Daily close
Each Location runs its own cash-up (expected vs counted, card totals, discrepancies).
Accounting export (QuickBooks, Xero, or file) groups by Legal Entity, not by mixing EINs in one export. Location is a dimension on the lines so operational profit per site remains available.
Reports
The report module has a three-way context. Every financial and volume report declares which context is active.
| Context | Question it answers |
|---|---|
| Organization | Group performance: gross revenue, visit volume, across every site |
| Legal Entity | Books and tax: activity for one EIN, all of that entity’s Locations rolled up |
| Location | Site profitability: appointments, sales by room, local inventory, drawer |
Filters must not leak Locations the User is not granted (Staff access). Organization admins may choose any of the three contexts. Location managers get Location context for granted sites only.
Acceptance (when built)
- An invoice from Location A shows Legal Entity 1’s EIN; an invoice from Location C shows Legal Entity 2’s EIN.
- Revenue reports by Location still split A and B even when they share an entity.
- A payout configuration on Legal Entity 1 does not receive Location C’s card charges.
- Location A’s daily close does not include Location B’s cash.
- A Legal Entity export contains only that entity’s Locations.
- Checkout at A with an unpaid invoice at C shows the alert and still lets A complete A’s sale without pulling C’s balance into A’s tender.
Out of scope: processor onboarding UI, tax-engine choice, tip lines, payment plans, chart of accounts. Integrations (Stripe, QuickBooks, Xero) are intended destinations; field mapping waits for the first finance implementation.