# Billing Workflows

> Use this guide for invoice creation, payment capture, receipts, and day-to-day billing desk operations.

For current rollout status, see [Module Status](../shared/module-status.md).

## What Billing Means in Practice

Billing turns care and service activity into **invoices and payments** so staff know what is owed, paid, or still outstanding.

Billing stays anchored to the underlying clinical or service activity:

- charge lines usually originate from `RequestItem` or manually added invoice lines
- payments are recorded against invoices through the billing desk or gateway flows

## Who Uses This Workflow

- billing clerks and cashiers
- reception staff collecting payments at check-in or checkout
- finance staff reviewing revenue reports
- administrators configuring branch payment gateways

## The Basic Flow

```text
Chargeable activity becomes invoice line(s)
        ->
Invoice is issued with totals and status
        ->
Payment is recorded or collected through a gateway
        ->
Allocations update balance and paid/partially-paid state
```

## Common Scenarios

### 1. Issue an invoice for a patient

1. Open the **Billing** cluster.
2. Go to **Invoices** and create or open the relevant invoice.
3. Review or add invoice lines.
4. Issue the invoice when totals and line items are correct.

### 2. Record a payment at the billing desk

1. Open **Billing Desk** or the relevant invoice.
2. Enter the payment amount and method.
3. Save the payment and confirm the invoice balance updates.
4. Print or send a receipt if your branch uses that workflow.

### 3. Record a patient deposit

Walk-in and guest clients appear as **Client** on invoices, receipts, and reports — with the guest name and phone when no registered patient is linked.

1. Open the patient's **Payments** tab or use **Record deposit** from billing surfaces.
2. Enter the deposit amount and payment method.
3. Save — the amount is held as **prepaid credit** on the patient's account (not yet applied to an invoice).

### 4. Apply a deposit to an invoice

1. Open **Billing Desk** or the relevant issued invoice with an outstanding balance.
2. Choose **Apply deposit** when the patient has active deposit credit.
3. Select the deposit, amount (or full invoice), and optional line items.
4. Confirm — the invoice balance updates and the deposit's unallocated balance decreases.

### 5. Appointment check-in billing

When **Auto-invoice on appointment check-in** is enabled in Core billing settings, checking in a cash appointment with a linked service automatically creates and issues an invoice for that service fee.

### 6. Unpaid / overdue reminders

The `invoices:check-overdue` command runs daily (08:00) when the Laravel scheduler is active. It sends **InvoiceUnpaidMail** reminders for overdue invoices, respecting a configurable **cooldown** so patients are not reminded more than once per invoice within that window (default: 7 days).

### 7. Create and collect on a payment plan

A **payment plan** splits an issued invoice balance into a down payment (optional) plus scheduled installments. Each collected installment creates a real **Payment** allocated to the invoice.

**Create a plan**

1. Open an **issued** or **partially paid** invoice that still has an outstanding balance.
2. Create the plan from either surface:
   - **Billing → Payment Plans → Create** (pick the invoice), or
   - The invoice **Payment plans** tab → **Create payment plan** (invoice is already in context).
3. Enter down payment, number of installments, frequency (days between installments), and optional notes.
4. Save — the system generates installment rows with due dates.

**Collect installments**

1. Open the plan from **Billing → Payment Plans** (view page) or use installment collection on **Billing Desk**.
2. Choose **Collect installment**, select the installment, and enter amount and payment method.
3. Confirm — the invoice balance updates and the installment shows as paid (or partially paid).

**Rules**

- Plans are only allowed on **issued** or **partially paid** invoices with balance greater than zero.
- Only **one active plan** per invoice at a time.
- Down payment cannot exceed the invoice balance.

### 8. Review branch revenue

1. Open **Revenue Report** in the Billing cluster.
2. Review collection widgets and branch summaries for the selected period.
3. Export or drill into invoices/payments as needed.

## Current Filament Surfaces

| Surface | Purpose |
|---------|---------|
| Invoices | Invoice CRUD, line management, issue workflow |
| Payments | Payment history, allocations, refunds |
| Payment Intents | Gateway checkout session troubleshooting |
| Billing Webhook Events | Webhook idempotency and reconciliation |
| Payment Plans | Installment schedules, view/collect installments, cancel active plans |
| Billing Desk | Operational payment capture, deposit application, and installment collection |
| Revenue Report | Charts and tables for collections and aging |
| Branch Payment Gateway Configs | Per-branch gateway credentials and settings |

## Insurance Interaction

When Insurance is enabled, some invoice lines may later feed claim generation and reconciliation. Billing remains the financial source of truth; insurance modules consume billing outcomes rather than replacing invoices.

## Related Guides

- [Pharmacy Workflows](pharmacy.md)
- [Admin: Billing Configuration](../admin-guide/billing.md)
- [Billing Module README](../../Modules/Billing/README.md)