Add Invoice flow docs and refresh billing concept and reference for 3.1

versioned_docs/version-3.1/concepts/billing/invoice.mdx

@@ -12,15 +12,6 @@ In Care's FHIR-aligned model, an invoice maps to the **Invoice** resource. It pu
 
 The key distinction is that an invoice is not a payment. It states what is owed; the act of paying it down — and any credit notes against it — lives in [payment reconciliation](../../references/billing/payment-reconciliation.mdx). One account can produce several invoices over time as new charges accumulate, and the invoice's detail view reports what has been paid against each so you can always see the remaining balance.
 
-## How it connects
-
-An invoice sits at the meeting point of several billing primitives:
-
-- **[Account](../../references/billing/account.mdx)** — every invoice settles exactly one account, and takes its patient from there.
-- **[Charge items](../../references/billing/charge-item.mdx)** — the line items. A charge item is each individual billable thing; the invoice is the envelope that totals them up.
-- **[Charge item definitions](../../references/definitions/charge-item-definition.mdx)** — the priced catalogue entries charge items are built from, used when Care generates a refund invoice automatically.
-- **[Payment reconciliation](../../references/billing/payment-reconciliation.mdx)** — the payments and credit notes recorded against the invoice once it is issued.
-
 ## Lifecycle
 
 An invoice moves through a small set of statuses, and a crucial thing happens partway through. While an invoice is still a `draft` it shows the live charges — edit a charge item and the invoice follows. The instant it is **issued**, Care takes a frozen snapshot of those line items and computes the totals once. From then on the invoice shows that snapshot, not the live charges. This is deliberate: a bill the patient was handed must not silently change if someone later edits an underlying charge.
@@ -36,31 +27,52 @@ draft → issued → balanced
 - **cancelled** — voided after issue; no longer collectible
 - **entered_in_error** — recorded by mistake and retracted
 
-`cancelled` and `entered_in_error` are the two terminal void states. Drive these transitions through the billing workflow rather than editing records directly, since each one also adjusts the linked charge items and the account.
+Care allows only one path through the ordinary statuses: `draft` to `issued` (once the invoice holds at least one charge item), then `issued` to `balanced`. Any other change is refused, such as jumping straight from `draft` to `balanced` or reopening a `balanced` invoice. `cancelled` and `entered_in_error` are the two terminal void states, reached only through a dedicated cancel action rather than an ordinary status change, since cancelling also returns the linked charge items to billable and adjusts the account.
 
 ## Refunds
 
 A normal invoice has positive totals. When goods are returned or a charge is reversed, Care creates a separate **refund invoice** with negative totals. These are flagged as refunds, and Care refuses to save a negative-total invoice that is not marked as one — a guardrail that keeps refunds from being mistaken for ordinary bills.
 
 ## Locking
 
-An issued invoice can be **locked** to freeze it against any further edits — useful once a bill has been formally closed out or handed to an external system. Locking is a privileged action, separate from everyday read and write access.
+Care can **lock** an invoice at any status. A lock does not change the status of the invoice. A lock freezes the invoice and hides its money. While an invoice is locked, Care reports the net total and the gross total as zero to every user who reads the invoice. The invoice list shows a **Locked** badge in place of the amount.
+
+Only a user with the `can_manage_locked_invoice` permission can open a locked invoice. Care refuses the request from every other user. The same permission is necessary to lock an invoice and to unlock it. Care also keeps a lock history, and records the user and the time for each lock and each unlock.
+
+## How it connects
+
+An invoice sits at the meeting point of several billing primitives:
+
+- **[Account](../../references/billing/account.mdx)** — every invoice settles exactly one account, and takes its patient from there.
+- **[Charge items](../../references/billing/charge-item.mdx)** — the line items. A charge item is each individual billable thing; the invoice is the envelope that totals them up.
+- **[Charge item definitions](../../references/definitions/charge-item-definition.mdx)** — the priced catalogue entries charge items are built from, used when Care generates a refund invoice automatically.
+- **[Payment reconciliation](../../references/billing/payment-reconciliation.mdx)** — the payments and credit notes recorded against the invoice once it is issued.
 
 ## Permissions
 
 Access to invoices is governed by facility-scoped permissions:
 
 | Permission | Description | System Roles |
 | --- | --- | --- |
-| `can_write_invoice` | Create and update invoices, including attaching or removing charge items and issuing or balancing them. Also gates cancelling an invoice within the free-cancel window. | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist |
+| `can_write_invoice` | Create and update invoices, including attaching or removing charge items and issuing or balancing them. Also gates a cancel action inside the free-cancel period. | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist |
 | `can_read_invoice` | List and retrieve invoices, their line items, totals, and reconciliation history. | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist |
-| `can_destroy_invoice` | Cancel an invoice after the free-cancel window has elapsed. | Facility Admin, Admin |
-| `can_manage_locked_invoice` | Lock and unlock invoices, and retrieve a locked invoice. | Facility Admin, Admin |
+| `can_destroy_invoice` | Cancel an invoice after the free-cancel period ends. The free-cancel period is a deployment setting, and its default value is zero minutes, so a cancel action needs this permission in a default deployment. | Facility Admin, Admin |
+| `can_manage_locked_invoice` | Lock an invoice, unlock an invoice, and read a locked invoice. Care refuses a read of a locked invoice for every other user. | Facility Admin, Admin |
 
 Roles are granted through a user's facility and organization memberships, and permissions cascade down the organization tree, so access at a parent organization carries to the facilities beneath it.
 
 ## Related
 
+- Flow: [View invoices](../../flows/billing/invoice/view-invoices.mdx)
+- Flow: [Create an invoice](../../flows/billing/invoice/create-invoice.mdx)
+- Flow: [Edit invoice details](../../flows/billing/invoice/edit-invoice-details.mdx)
+- Flow: [Edit the items on an invoice](../../flows/billing/invoice/edit-invoice-items.mdx)
+- Flow: [Issue an invoice](../../flows/billing/invoice/issue-invoice.mdx)
+- Flow: [Print an invoice](../../flows/billing/invoice/print-invoice.mdx)
+- Flow: [Record a payment against an invoice](../../flows/billing/invoice/record-invoice-payment.mdx)
+- Flow: [Mark an invoice as balanced](../../flows/billing/invoice/mark-invoice-as-balanced.mdx)
+- Flow: [Lock and unlock an invoice](../../flows/billing/invoice/lock-and-unlock-invoice.mdx)
+- Flow: [Cancel an invoice](../../flows/billing/invoice/cancel-invoice.mdx)
 - Reference: [Invoice (technical)](../../references/billing/invoice.mdx)
 - Reference: [Account](../../references/billing/account.mdx)
 - Reference: [Charge Item](../../references/billing/charge-item.mdx)

versioned_docs/version-3.1/flows/billing/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Billing",
+  "position": 4,
+  "key": "billing-flows"
+}

versioned_docs/version-3.1/flows/billing/invoice/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Invoice",
+  "position": 1,
+  "key": "billing-invoice-flows"
+}

versioned_docs/version-3.1/flows/billing/invoice/cancel-invoice.mdx

@@ -0,0 +1,109 @@
+---
+sidebar_position: 10
+---
+
+# Cancel an invoice
+
+## Overview
+
+This flow describes how to void an [invoice](../../../concepts/billing/invoice.mdx) in Care. Void an invoice when the invoice is no longer collectible, or when someone raised the invoice by mistake.
+
+## Pre-requisites
+
+- The invoice is raised at the facility, and you can open the invoice.
+- You know why you void the invoice. The invoice is no longer collectible, or someone recorded the invoice by mistake.
+- If the invoice is locked, you have the extra permission listed below.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Read Invoice | Lets you open the invoice. |
+| Can Write Invoice | Lets you cancel an invoice inside the free-cancel period. |
+| Can Destroy Invoice | Lets you cancel an invoice after the free-cancel period. Granted to the Facility Admin role and the Admin role. |
+| Can Manage Locked Invoice | Needed in addition if the invoice is locked. |
+
+:::info The free-cancel period
+The permission that Care needs depends on the age of the invoice. Inside the free-cancel period after the invoice was created, Can Write Invoice is enough. After that period, Care needs Can Destroy Invoice. The length of the free-cancel period is a deployment setting. The period is zero minutes unless your deployment changes the setting. With the default setting, a cancellation always needs Can Destroy Invoice.
+:::
+
+:::warning
+The invoice screens do not hide these menu items. A user without the permission sees the menu items. Care refuses the action and shows the message "Cannot cancel invoice".
+:::
+
+## Steps
+
+### 1. Open the invoice
+
+1. Select **Billing** in the facility sidebar.
+2. Select **Invoices**.
+3. Select **See Invoice** for the invoice that you want to void.
+
+### 2. Open the more-options menu
+
+Select the more-options menu next to **Print**. The more-options menu shows a vertical ellipsis.
+
+### 3. Select the menu item for your reason
+
+The menu has two choices.
+
+| Menu item | When to use the menu item |
+| --- | --- |
+| **Mark as Cancelled** | The invoice is no longer collectible. |
+| **Mark as entered in error** | Someone recorded the invoice by mistake. Care retracts the invoice. |
+
+### 4. Confirm the action
+
+Care shows a dialog with the title **Confirm**.
+
+- For **Mark as Cancelled**, the dialog reads "Are you sure you want to mark this invoice as cancelled?".
+- For **Mark as entered in error**, the dialog reads "Are you sure you want to mark this invoice as entered in error?".
+
+Select **Confirm** to continue. Select **Cancel** to keep the invoice.
+
+### 5. Review the active payments and credit notes
+
+If the invoice has active payments or credit notes, Care shows a second step. The heading is "Cancel Invoice with Active Payments". For the other menu item, the heading is "Mark as Entered in Error with Active Payments".
+
+The step reads: "This invoice has active payments or credit notes. Cancelling this invoice will not automatically cancel those transactions. You may need to cancel the payments or issue refunds as needed."
+
+Care lists the **Active Payments** and the **Active Credit Notes** with their totals. Read the lists before you continue.
+
+Select **Proceed** to void the invoice. Select **Cancel** to keep the invoice.
+
+:::warning Care does not reverse the money
+Care does not reverse the payments and the credit notes that you recorded against the invoice. Cancel those payments separately, or issue the refunds separately. See [Record a payment against an invoice](./record-invoice-payment.mdx).
+:::
+
+## Expected Outcome
+
+- Care shows the message "Invoice cancelled successfully".
+- The status badge changes to **Cancelled** or to **Entered in Error**.
+- Every charge item on the invoice returns to the status Billable. Care clears the link to the invoice and the paid date. You can put those charge items on a new invoice.
+- Care keeps the payments and the credit notes that you already recorded.
+- If the action fails, Care shows the message "Failed to cancel invoice".
+
+:::note Both statuses are end states
+You cannot void the invoice a second time. Care answers "Invoice is already cancelled". You cannot move the invoice back to **Draft**, **Issued**, or **Balanced**. Care answers "Invoice is already cancelled" again.
+
+An ordinary status change cannot reach **Cancelled** or **Entered in Error**. Care answers "Call the cancel invoice API to cancel the invoice". Use the menu items in this flow.
+:::
+
+## Related
+
+Concepts:
+
+- [Invoice](../../../concepts/billing/invoice.mdx)
+
+Flows:
+
+- [Issue an invoice](./issue-invoice.mdx)
+- [Mark an invoice as balanced](./mark-invoice-as-balanced.mdx)
+- [Record a payment against an invoice](./record-invoice-payment.mdx)
+
+References:
+
+- [Invoice](../../../references/billing/invoice.mdx)
+- [Charge Item](../../../references/billing/charge-item.mdx)
+- [Payment Reconciliation](../../../references/billing/payment-reconciliation.mdx)

versioned_docs/version-3.1/flows/billing/invoice/create-invoice.mdx

@@ -0,0 +1,137 @@
+---
+sidebar_position: 2
+---
+
+# Create an invoice
+
+## Overview
+
+This flow describes how to build a draft [invoice](../../../concepts/billing/invoice.mdx) from the billable charge items on a billing account of a patient.
+
+## Pre-requisites
+
+- The patient has a billing account at the facility.
+- The account is active and billable. Care shows the **Create Invoice** button only for an active and billable account.
+- The account has charge items with the status Billable, or you add charge items in this flow.
+- The account belongs to the facility that you work in.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Write Invoice | Lets you create an invoice in the facility. |
+| Can Read Invoice | Lets you open the invoice after Care creates it. |
+
+## Steps
+
+### 1. Open the billing account
+
+1. In the facility sidebar, select **Billing**.
+2. Select **Accounts**.
+3. Select the account.
+
+### 2. Start the invoice
+
+Select **Create Invoice**. On a small screen the same button reads **Invoice**.
+
+Note: Press `i` on the account screen to start the invoice.
+
+Care opens the **Create Invoice** screen. The top of the screen shows the patient name, the account, and the account status. A **Draft** badge is next to the page title.
+
+### 3. Select the items to bill
+
+The screen lists the charge items on the account that have the status Billable. The oldest charge item is first. Select the checkbox for each charge item to include.
+
+The table shows these columns.
+
+| Components | What it captures |
+| --- | --- |
+| Items | The charge item to bill. |
+| Quantity | The number of units. |
+| Unit Price | The price for one unit. |
+| Performer | The user who did the work. |
+| Amount | The total for the line. |
+
+**Unit Price** and **Amount** show the configured currency symbol.
+
+If the account has no billable charge item, Care shows "No Billable Items Found". If more charge items exist, select **Load more**.
+
+### 4. Add more charge items
+
+To add a charge item that is not in the list, use one of these actions.
+
+- Select **Quick Add** to open the quick add sheet.
+- Select **Add Charge Items** to open the full add sheet.
+
+You can also add a charge item in the inline row on the screen.
+
+| Components | What it captures |
+| --- | --- |
+| Charge item definition | The charge item to add. The placeholder is **Select charge item definition**. |
+| Quantity | The number of units. The quantity must be more than zero. |
+| Performer | The user who did the work. The placeholder is **Select performer**. Optional. |
+
+Confirm the row to add the charge item.
+
+Note: Press `Enter` to confirm the row. Press `Esc` to cancel the row.
+
+Care shows "Charge items added successfully" when Care adds the charge items. Care shows "Failed to add charge items" when Care cannot add the charge items. Care shows "Quantity must be positive" when the quantity is zero or less.
+
+### 5. Check the total
+
+Below the table Care shows the number of selected charge items. If you select no charge item, Care shows "No items selected".
+
+Care also shows the **Invoice Total**, with the note "Includes all applicable taxes".
+
+### 6. Enter the optional details
+
+Expand **Issue Date, Payment Terms & Note** to record more detail. All three fields are optional.
+
+| Components | What it captures |
+| --- | --- |
+| Issue Date | The date and the time of issue. Select the values in the picker. You cannot enter a future date. |
+| Payment Terms | The payment terms, as free text. The placeholder is **Enter Payment Terms**. Your deployment can set a default value. |
+| Note | A free-text note for the invoice. The placeholder is **Enter Invoice Note**. |
+
+Note: If you enter a future issue date, Care shows "Issue date cannot be in the future".
+
+### 7. Create the invoice
+
+Select **Create Invoice**. The button reads **Creating** while Care creates the invoice.
+
+To leave the screen without an invoice, select **Cancel**.
+
+:::warning
+If the account belongs to another facility, Care refuses the request with "Account is not associated with the facility".
+:::
+
+## Expected Outcome
+
+- Care shows "Invoice Created Successfully" and opens the new invoice.
+- The status of the new invoice is Draft.
+- Care accepts only the charge items on the account that have the status Billable. Care drops every other selected charge item without a message.
+- Each included charge item changes from Billable to Billed, and links to the invoice.
+- Care generates the invoice number from the invoice number expression of the facility, unless the invoice has a supplied number. The expression can use the invoice count of the facility and the current year.
+- Care computes the net total as the base amounts, plus the surcharges, minus the discounts. The gross total adds the tax.
+- Care recalculates the balance of the account.
+- Care takes the patient from the account. You never select the patient.
+
+## Related
+
+Concepts:
+
+- [Invoice](../../../concepts/billing/invoice.mdx)
+
+Flows:
+
+- [View invoices](./view-invoices.mdx)
+- [Edit the items on an invoice](./edit-invoice-items.mdx)
+- [Edit invoice details](./edit-invoice-details.mdx)
+- [Issue an invoice](./issue-invoice.mdx)
+
+References:
+
+- [Invoice](../../../references/billing/invoice.mdx)
+- [Charge Item](../../../references/billing/charge-item.mdx)
+- [Account](../../../references/billing/account.mdx)