From 35b24897c76b236e6c1b7d0c1275b8f9bc676069 Mon Sep 17 00:00:00 2001 From: gauritejusa Date: Tue, 11 Aug 2026 15:31:40 +0530 Subject: [PATCH 1/3] Add Invoice flow docs and refresh billing concept and reference for 3.1 Add ten flow documents for the Invoice resource under flows/billing/invoice: view, create, edit details, edit items, issue, print, record payment, mark as balanced, lock and unlock, and cancel. Register them in the 3.1 sidebar with Billing and Invoice categories. Correct the concept page: a lock applies at any status rather than only after issue, it hides the totals, and it needs Can Manage Locked Invoice even to read. Document the free-cancel period that decides whether cancelling needs Can Write Invoice or Can Destroy Invoice, and add the permitted status transitions. Extend the reference page with the API endpoints and custom actions, filtering and ordering, the permission matrix with roles, the status transition rules, and the INVOICE_FREE_CANCEL_PERIOD_MINUTES setting. Correct the claim that invoice numbers are generated only for return invoices; they are generated on every create when the client does not supply one. --- .../version-3.1/concepts/billing/invoice.mdx | 34 ++++- .../version-3.1/flows/billing/_category_.json | 5 + .../flows/billing/invoice/_category_.json | 5 + .../flows/billing/invoice/cancel-invoice.mdx | 109 ++++++++++++++ .../flows/billing/invoice/create-invoice.mdx | 137 ++++++++++++++++++ .../billing/invoice/edit-invoice-details.mdx | 83 +++++++++++ .../billing/invoice/edit-invoice-items.mdx | 131 +++++++++++++++++ .../flows/billing/invoice/issue-invoice.mdx | 105 ++++++++++++++ .../invoice/lock-and-unlock-invoice.mdx | 97 +++++++++++++ .../invoice/mark-invoice-as-balanced.mdx | 105 ++++++++++++++ .../flows/billing/invoice/print-invoice.mdx | 92 ++++++++++++ .../invoice/record-invoice-payment.mdx | 114 +++++++++++++++ .../flows/billing/invoice/view-invoices.mdx | 115 +++++++++++++++ .../references/billing/invoice.mdx | 104 ++++++++++++- versioned_sidebars/version-3.1-sidebars.json | 24 +++ 15 files changed, 1253 insertions(+), 7 deletions(-) create mode 100644 versioned_docs/version-3.1/flows/billing/_category_.json create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/_category_.json create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/cancel-invoice.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/create-invoice.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/edit-invoice-details.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/edit-invoice-items.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/issue-invoice.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/lock-and-unlock-invoice.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/mark-invoice-as-balanced.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/print-invoice.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/record-invoice-payment.mdx create mode 100644 versioned_docs/version-3.1/flows/billing/invoice/view-invoices.mdx diff --git a/versioned_docs/version-3.1/concepts/billing/invoice.mdx b/versioned_docs/version-3.1/concepts/billing/invoice.mdx index 5831d4a8..6eed31f2 100644 --- a/versioned_docs/version-3.1/concepts/billing/invoice.mdx +++ b/versioned_docs/version-3.1/concepts/billing/invoice.mdx @@ -36,7 +36,19 @@ 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 permits only one path through the ordinary statuses: `draft` to `issued`, then `issued` to `balanced`. + +| Status change | Permitted | +| --- | --- | +| `draft` to `issued` | Yes, if the invoice has at least one charge item | +| `issued` to `balanced` | Yes | +| `draft` to `balanced` | No | +| `issued` to `draft` | No | +| `balanced` to any other status | No | + +`cancelled` and `entered_in_error` are the two terminal void states. Care never sets them with an ordinary status change. Care sets them only with the dedicated cancel action, which also adjusts the linked charge items and the account. + +The permission Care requires for a cancel action depends on the age of the invoice. Inside a configurable free-cancel period, `can_write_invoice` is enough. After that period, `can_destroy_invoice` is necessary. The free-cancel period is a deployment setting, and its default value is zero minutes. With the default configuration, a cancel action always needs `can_destroy_invoice`. ## Refunds @@ -44,7 +56,9 @@ A normal invoice has positive totals. When goods are returned or a charge is rev ## 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. ## Permissions @@ -52,15 +66,25 @@ 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) diff --git a/versioned_docs/version-3.1/flows/billing/_category_.json b/versioned_docs/version-3.1/flows/billing/_category_.json new file mode 100644 index 00000000..5a5ebd73 --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Billing", + "position": 4, + "key": "billing-flows" +} diff --git a/versioned_docs/version-3.1/flows/billing/invoice/_category_.json b/versioned_docs/version-3.1/flows/billing/invoice/_category_.json new file mode 100644 index 00000000..75b528fe --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Invoice", + "position": 1, + "key": "billing-invoice-flows" +} diff --git a/versioned_docs/version-3.1/flows/billing/invoice/cancel-invoice.mdx b/versioned_docs/version-3.1/flows/billing/invoice/cancel-invoice.mdx new file mode 100644 index 00000000..aa43905f --- /dev/null +++ b/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) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/create-invoice.mdx b/versioned_docs/version-3.1/flows/billing/invoice/create-invoice.mdx new file mode 100644 index 00000000..087d600e --- /dev/null +++ b/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 `c` 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) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/edit-invoice-details.mdx b/versioned_docs/version-3.1/flows/billing/invoice/edit-invoice-details.mdx new file mode 100644 index 00000000..79aef2da --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/edit-invoice-details.mdx @@ -0,0 +1,83 @@ +--- +sidebar_position: 3 +--- + +# Edit invoice details + +## Overview + +This flow describes how to change the issue date, the payment terms, or the note on a draft [invoice](../../../concepts/billing/invoice.mdx) in Care. + +## Pre-requisites + +- The invoice exists in the facility, and you open that invoice. +- The invoice status is Draft. You can edit these details only for a draft invoice. +- If the invoice is locked, you have the permission to manage a locked invoice. +- You have the permissions listed below. + +## Permissions + +| Permission | Access | +| --- | --- | +| Can Read Invoice | Lets you open the invoice. | +| Can Write Invoice | Lets you change the invoice in the facility. | +| Can Manage Locked Invoice | Needed in addition if the invoice is locked. | + +## Steps + +### 1. Open the invoice + +1. In the facility sidebar, select **Billing**. +2. Select **Invoices**. +3. For the invoice that you want to change, select **See Invoice**. + +### 2. Start the edit + +Select **Edit Details**. Care shows this button only when the invoice status is Draft. + +Care opens the dialog **Edit Invoice Details**. The fields show the current values of the invoice. + +Note: Selecting outside the dialog does not close the dialog. + +### 3. Change the details + +Change one or more of the fields. All three fields are optional. + +| Components | What it captures | +| --- | --- | +| Issue Date | The date and the time of the invoice. Select the date and the time in the picker. | +| Payment Terms | The payment terms for the invoice. Free text. | +| Note | A free-text note for the invoice. | + +:::note +You cannot enter a future issue date. For a future date, Care shows the message "Issue date cannot be in the future". +::: + +### 4. Save the changes + +Submit the form to save the changes. + +## Expected Outcome + +- Care saves the new issue date, payment terms, and note on the invoice. +- Care shows the message "Invoice updated successfully". +- Care closes the dialog. +- The invoice status stays Draft. This dialog does not change the status. +- If the save fails, Care shows the message "Failed to update invoice". The invoice keeps the earlier values. + +## Related + +Concepts: + +- [Invoice](../../../concepts/billing/invoice.mdx) + +References: + +- [Invoice](../../../references/billing/invoice.mdx) + +Flows: + +- [Create an invoice](./create-invoice.mdx) +- [Edit the items on an invoice](./edit-invoice-items.mdx) +- [Issue an invoice](./issue-invoice.mdx) +- [Lock and unlock an invoice](./lock-and-unlock-invoice.mdx) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/edit-invoice-items.mdx b/versioned_docs/version-3.1/flows/billing/invoice/edit-invoice-items.mdx new file mode 100644 index 00000000..42e25271 --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/edit-invoice-items.mdx @@ -0,0 +1,131 @@ +--- +sidebar_position: 4 +--- + +# Edit the items on an invoice + +## Overview + +This flow describes how to add, change, discount, or remove the charge items on a draft [invoice](../../../concepts/billing/invoice.mdx) in Care. + +## Pre-requisites + +- The invoice exists in the facility, and you open that invoice. +- The invoice status is Draft. For any other status, Care refuses the change with the message "Invoice is not in draft". +- The charge items that you want to add belong to the same account as the invoice. +- The status of each charge item that you want to add is Billable. +- If the invoice is locked, you have the permission to manage a locked invoice. +- You have the permissions listed below. + +## Permissions + +| Permission | Access | +| --- | --- | +| Can Read Invoice | Lets you open the invoice. | +| Can Write Invoice | Lets you add, change, and remove the items on an invoice. | +| Can Manage Locked Invoice | Needed in addition if the invoice is locked. | + +:::note +The invoice screen does not hide these actions. If you do not have the permission for an action, Care refuses the change. +::: + +## Steps + +### 1. Open the invoice + +1. In the facility sidebar, select **Billing**. +2. Select **Invoices**. +3. For the invoice that you want to change, select **See Invoice**. + +### 2. Add charge items + +Select **Add Charge Item**. Care opens the sheet **Add Charge Items to Invoice**. + +1. In the search box, enter the name of the charge item. The placeholder is "Search charge items". +2. To see more charge items, select **Other Charge Items**. The keyboard shortcut is `o`. +3. Select the charge items that you want to add. +4. Select **Add Selected Items**. + +The table in the sheet has these columns. + +| Column | What it shows | +| --- | --- | +| Item | The name of the charge item. | +| Quantity | The number of units. | +| Unit Price | The price for one unit. | +| Performer | The user who did the work. | +| Total | The total amount for the charge item. | + +To close the sheet without a change, select **Cancel**. + +:::note +Care lists only the charge items on the same account with the status Billable. When there is no such charge item, the table reads "No charge items found". +::: + +### 3. Open the item table + +Select **Edit Items** on the invoice. The keyboard shortcut is `e`. + +Care opens the dialog **Edit Invoice Items** with an editable table. The table has these columns. + +| Column | What it captures | +| --- | --- | +| Item | The charge item on the invoice. | +| Performer | The user who did the work. The placeholder is "Select performer". | +| Unit Price | The price for one unit. The cell shows the configured currency symbol. | +| Quantity | The number of units. | +| Discounts | The discounts for the charge item. | +| Note | Free text for the charge item. The placeholder is "Add notes". | + +To copy one value to every row, select **Apply to all**. The Performer column and the Discounts column each have this control. + +Note: When the invoice has no items, the dialog reads "No charge items found". + +### 4. Change the discounts + +To add a discount, select **Add Discount** in the Discounts cell. To remove every discount for the charge item, select **Clear all**. When the charge item has no discount, the cell reads "No discounts". + +### 5. Save the item table + +Select **Save**. While Care saves the changes, the button reads **Saving**. + +To close the dialog without a change, select **Cancel**. + +### 6. Remove a charge item + +1. On the invoice, find the row of the charge item. +2. Select **Remove**. Care opens the dialog **Remove Charge Item**. +3. Read the question "Are you sure you want to remove this charge item from the invoice?". +4. Select **Remove**. While Care removes the charge item, the button reads **Removing...**. + +To keep the charge item on the invoice, select **Cancel**. + +## Expected Outcome + +- Care shows the message "Invoice updated successfully" after a save in the item table. If the save fails, Care shows the message "Failed to update invoice". +- Care shows the message "Charge item removed successfully" after a remove. If the remove fails, Care shows the message "Failed to remove charge item". +- Each added charge item changes to the status Billed, and links to the invoice. +- Each removed charge item returns to the status Billable. Care clears the link to the invoice and the paid date of that charge item. +- Care calculates the invoice totals and the account balance again after each add and after each remove. +- The invoice status stays Draft. No step in this flow changes the status. + +:::info +A draft invoice shows the live charge items. When you issue the invoice, Care makes a snapshot of the line items. After that, a change to a charge item does not change the invoice. +::: + +## Related + +Concepts: + +- [Invoice](../../../concepts/billing/invoice.mdx) + +References: + +- [Invoice](../../../references/billing/invoice.mdx) +- [Charge Item](../../../references/billing/charge-item.mdx) + +Flows: + +- [Create an invoice](./create-invoice.mdx) +- [Edit invoice details](./edit-invoice-details.mdx) +- [Issue an invoice](./issue-invoice.mdx) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/issue-invoice.mdx b/versioned_docs/version-3.1/flows/billing/invoice/issue-invoice.mdx new file mode 100644 index 00000000..ec24f080 --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/issue-invoice.mdx @@ -0,0 +1,105 @@ +--- +sidebar_position: 5 +--- + +# Issue an invoice + +## Overview + +This flow describes how to finalise a draft [invoice](../../../concepts/billing/invoice.mdx) in Care. After you issue the invoice, you can give it to the patient or to the payer. You can also collect payment against it. + +## Pre-requisites + +- The invoice status is Draft. Care shows the **Issue Invoice** action only for a draft invoice. +- The invoice has at least one charge item. +- If the invoice is locked, you have the permission to manage a locked invoice. +- You have the permissions listed below. + +## Permissions + +| Permission | Access | +| --- | --- | +| Can Read Invoice | Lets you open the invoice. | +| Can Write Invoice | Lets you issue the invoice. | +| Can Manage Locked Invoice | Needed in addition if the invoice is locked. | + +## Steps + +### 1. Open the invoice + +1. Select **Billing** in the facility sidebar. +2. Select **Invoices**. +3. Select **See Invoice** for the invoice to issue. + +### 2. Check the items before you issue + +Check the charge items and the amounts on the invoice. + +A draft invoice shows the live charge items. A change to a charge item changes the draft invoice. + +To correct the items, see [Edit the items on an invoice](./edit-invoice-items.mdx). + +:::warning +After you issue the invoice, you cannot change the items on the invoice. Check the items first. +::: + +### 3. Issue the invoice + +Select **Issue Invoice**. Care disables the button while the change is in progress. + +Note: Press `i` to start this action. + +:::warning +Care does not issue an invoice that has no charge items. Care shows the message "Invoice must have at least one charge item". Add at least one charge item, then issue the invoice again. +::: + +## Expected Outcome + +- Care shows the message "Invoice updated successfully". +- The status badge changes from **Draft** to **Issued**. +- Care stores the line items on the invoice. A later change to a charge item does not change the invoice. This protects a bill that you already gave to the patient. +- Care computes and stores the totals. The net total is the base amounts plus the surcharges, minus the discounts. The gross total adds the tax. +- The invoice can now take payments. You can also mark the invoice as balanced. +- Care no longer shows **Edit Details** and **Edit Items**. Care refuses an item change with the message "Invoice is not in draft". + +## Status rules + +Care uses these invoice statuses. + +| Stored value | Display label | +| --- | --- | +| draft | Draft | +| issued | Issued | +| balanced | Balanced | +| cancelled | Cancelled | +| entered_in_error | Entered in Error | + +The permitted path is Draft, then Issued, then Balanced. Cancelled and Entered in Error are the two end states. To reach an end state, use the cancel action. + +Care applies these rules to a status change. + +- Care does not issue an invoice that has no charge items. The message is "Invoice must have at least one charge item". +- An issued invoice cannot go back to Draft. The message is "Invoice is already issued". +- A draft invoice cannot move straight to Balanced. The message is "Invoice needs to be issued before balancing". +- A balanced invoice cannot change status. The message is "Invoice is already balanced". +- A cancelled invoice cannot open again. The message is "Invoice is already cancelled". +- A status change does not cancel an invoice. Use the cancel action. The message is "Call the cancel invoice API to cancel the invoice". + +## Related + +Concepts: + +- [Invoice](../../../concepts/billing/invoice.mdx) + +Flows: + +- [Create an invoice](./create-invoice.mdx) +- [Edit the items on an invoice](./edit-invoice-items.mdx) +- [Print an invoice](./print-invoice.mdx) +- [Record a payment against an invoice](./record-invoice-payment.mdx) +- [Mark an invoice as balanced](./mark-invoice-as-balanced.mdx) +- [Cancel an invoice](./cancel-invoice.mdx) + +References: + +- [Invoice](../../../references/billing/invoice.mdx) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/lock-and-unlock-invoice.mdx b/versioned_docs/version-3.1/flows/billing/invoice/lock-and-unlock-invoice.mdx new file mode 100644 index 00000000..bfaf1b9a --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/lock-and-unlock-invoice.mdx @@ -0,0 +1,97 @@ +--- +sidebar_position: 9 +--- + +# Lock and unlock an invoice + +## Overview + +This flow describes how to lock an [invoice](../../../concepts/billing/invoice.mdx) in Care, and how to unlock it again. A lock hides the amounts on the invoice, and restricts the invoice to privileged users. + +## Pre-requisites + +- The invoice exists at the facility, and you open it from the invoice list of the facility. +- If you lock an invoice, the invoice is not locked already. +- If you unlock an invoice, the invoice is locked. +- You have the permissions listed below. + +## Permissions + +| Permission | Access | +| --- | --- | +| Can Manage Locked Invoice | Lets you lock an invoice, unlock it, and open a locked invoice. Care grants this permission to the Facility Admin and Admin roles. | +| Can Read Invoice | Lets you open the invoice list and unlocked invoices. | + +:::warning +The invoice screens do not hide **Lock Invoice** and **Unlock Invoice**. A user without the Can Manage Locked Invoice permission sees both menu items. Care refuses the action on the server. +::: + +## Steps + +### 1. Open the invoice + +1. Select **Billing** in the facility sidebar. +2. Select **Invoices**. +3. Select **See Invoice** for the invoice to lock or unlock. + +### 2. Open the more-options menu + +Select the more-options menu next to **Print**. The more-options menu is the vertical ellipsis. + +The menu shows **Lock Invoice** when the invoice is not locked. The menu shows **Unlock Invoice** when the invoice is locked. + +### 3. Lock the invoice + +Select **Lock Invoice**. + +Care shows the message "Invoice locked successfully". If the lock fails, Care shows the message "Failed to lock invoice". + +### 4. Unlock the invoice + +To release the invoice, open the more-options menu again. Select **Unlock Invoice**. + +Care shows the message "Invoice unlocked successfully". If the unlock fails, Care shows the message "Failed to unlock invoice". + +## Expected Outcome + +- Care shows a **Locked** badge next to the status badge on the invoice. +- The invoice list shows the **Locked** badge in the Total column, in place of the amount. +- Care reports the net total and the gross total of the invoice as zero to every reader. +- Only a user with the Can Manage Locked Invoice permission can open the invoice. Care refuses every other user with the message "Locked invoice permission denied." +- Care records each lock and each unlock in the lock history of the invoice. Each record holds the user and the time. +- After an unlock, Care shows the amounts again. Every user with the Can Read Invoice permission can open the invoice. + +## Lock rules + +Care applies these rules when you lock or unlock an invoice. + +- Care refuses a lock on a locked invoice. The message is "Invoice is already locked". +- Care refuses an unlock on an invoice that is not locked. The message is "Invoice is not locked". +- A lock and an unlock both need the Can Manage Locked Invoice permission. A read of a locked invoice needs the same permission. +- A lock does not change the invoice status. You can lock an invoice at any status. + +Care uses these invoice statuses. + +| Status | Display label | +| --- | --- | +| draft | Draft | +| issued | Issued | +| balanced | Balanced | +| cancelled | Cancelled | +| entered_in_error | Entered in Error | + +## Related + +Concepts: + +- [Invoice](../../../concepts/billing/invoice.mdx) + +Flows: + +- [View invoices](./view-invoices.mdx) +- [Issue an invoice](./issue-invoice.mdx) +- [Cancel an invoice](./cancel-invoice.mdx) + +References: + +- [Invoice](../../../references/billing/invoice.mdx) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/mark-invoice-as-balanced.mdx b/versioned_docs/version-3.1/flows/billing/invoice/mark-invoice-as-balanced.mdx new file mode 100644 index 00000000..69a47448 --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/mark-invoice-as-balanced.mdx @@ -0,0 +1,105 @@ +--- +sidebar_position: 8 +--- + +# Mark an invoice as balanced + +## Overview + +This flow describes how to close out an issued [invoice](../../../concepts/billing/invoice.mdx) in Care when the invoice is settled. + +## Pre-requisites + +- The invoice status is Issued. Care shows the **Mark as balanced** action only for an issued invoice. +- If the invoice still has an outstanding balance, you accept that Care moves the unpaid amount to the account balance. +- If the invoice is locked, you have the permission to manage a locked invoice. +- You have the permissions listed below. + +## Permissions + +| Permission | Access | +| --- | --- | +| Can Read Invoice | Lets you open the invoice. | +| Can Write Invoice | Lets you mark the invoice as balanced. | +| Can Manage Locked Invoice | Needed in addition if the invoice is locked. | + +## Steps + +### 1. Open the invoice + +1. Select **Billing** in the facility sidebar. +2. Select **Invoices**. +3. Select **See Invoice** for the invoice to close out. + +### 2. Start the action + +Select **Mark as balanced**. + +Note: Press `b` to start this action. + +### 3. Check the amounts in the confirmation dialog + +Care shows the **Confirm** dialog. The dialog asks "Are you sure you want to mark this invoice as balanced?". + +| Components | What it shows | +| --- | --- | +| Invoice Total | The total amount of the invoice. | +| Total Payments Received | The amount paid against the invoice. | +| Total Credit Notes | The credit notes for the invoice. Care shows this amount only when the invoice has credit notes. | +| Outstanding Balance | The amount that is still owed. | + +:::warning +When the invoice has an outstanding balance, the dialog adds this warning: "This invoice has an outstanding balance. The unpaid amount will be moved to the account balance." +::: + +### 4. Confirm the action + +Select **Confirm** to mark the invoice as balanced. Select **Cancel** to keep the invoice as it is. + +:::warning +Balanced is an end state. A balanced invoice cannot change status again. Check the amounts before you select **Confirm**. +::: + +## Expected Outcome + +- Care shows the message "Invoice updated successfully". +- The status badge changes to **Balanced**. +- Every charge item on the invoice with the status Billed moves to Paid. Care links each charge item to the invoice, and records a paid date. +- Care recalculates the account balance. +- Care moves any unpaid amount to the account. The invoice records that the amount "was unpaid and has been added to the account due". + +## Status rules + +Care uses these invoice statuses. + +| Status | Display label | +| --- | --- | +| draft | Draft | +| issued | Issued | +| balanced | Balanced | +| cancelled | Cancelled | +| entered_in_error | Entered in Error | + +Care applies these rules when you mark an invoice as balanced. + +- Only an issued invoice can move to Balanced. A draft invoice cannot move straight to Balanced. Care shows the message "Invoice needs to be issued before balancing". Issue the invoice first. +- A balanced invoice cannot change status again. Care shows the message "Invoice is already balanced". +- A cancelled invoice cannot move to Balanced. Care shows the message "Invoice is already cancelled". + +## Related + +Concepts: + +- [Invoice](../../../concepts/billing/invoice.mdx) + +Flows: + +- [Issue an invoice](./issue-invoice.mdx) +- [Record a payment against an invoice](./record-invoice-payment.mdx) +- [Cancel an invoice](./cancel-invoice.mdx) + +References: + +- [Invoice](../../../references/billing/invoice.mdx) +- [Account](../../../references/billing/account.mdx) +- [Charge Item](../../../references/billing/charge-item.mdx) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/print-invoice.mdx b/versioned_docs/version-3.1/flows/billing/invoice/print-invoice.mdx new file mode 100644 index 00000000..435aa227 --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/print-invoice.mdx @@ -0,0 +1,92 @@ +--- +sidebar_position: 6 +--- + +# Print an invoice + +## Overview + +This flow describes how to print an [invoice](../../../concepts/billing/invoice.mdx) in Care. The printable page gives the patient or the payer a copy of the bill. + +## Pre-requisites + +- The invoice exists in the facility, and you open the invoice list of that facility. +- If the invoice is locked, you have the permission to manage a locked invoice. +- You have the permissions listed below. + +:::note +You can print an invoice at any status. Care does not require you to issue the invoice first. For a draft invoice, the printable page marks the document as a draft. +::: + +## Permissions + +| Permission | Access | +| --- | --- | +| Can Read Invoice | Lets you open and print the invoice. | +| Can Manage Locked Invoice | Needed in addition if the invoice is locked. | + +:::note +The invoice screens do not hide these actions. If you do not have the permission for an action, Care refuses the request. +::: + +## Steps + +### 1. Open the invoice list + +1. In the facility sidebar, select **Billing**. +2. Select **Invoices**. + +### 2. Open the printable page + +Care gives two entry points. Both use the button **Print**. + +| Entry point | What to do | +| --- | --- | +| The invoice list | In the Actions column of the row, select **Print**. | +| The invoice | Open the invoice, then select **Print**. Press `p` for the same action. | + +If the invoice has related invoices, the **Print** button on the invoice opens a combined document. The combined document prints those invoices together. For an invoice with no related invoice, Care prints the one invoice. + +### 3. Check the printable page + +The printable page has the title **Invoice** and the invoice number. Check the content before you print. + +| Part | What it shows | +| --- | --- | +| Heading | The heading **Invoice** and the **Issue Date**. | +| Bill To | The patient details and the **Address**. For an invoice with no address, this block shows "No address provided". | +| QR code | A code for this invoice. Scan the code on the invoice list to open this invoice. | +| Item table | The columns **Item**, **Unit Price**, **Qty**, **Discount**, and **Total**. **Unit Price** and **Total** show the configured currency symbol. For an invoice with no items, the table shows "No charge items found". | +| Totals | The base amount, **Surcharge**, **Discount**, **Net Amount**, **Tax**, and **Total**. | +| Payments | For an invoice with payments, a table with the columns **Date and Time**, **Payment Method**, **Reference**, and **Amount**. The table also has a **Total Received** line. | +| Credit notes | For an invoice with credit notes, a table with the heading "Credit notes issued against this invoice". The table has the same columns and a **Total Credit Notes** line. | +| Footer | The **Payment Terms**, the **Created By** user, and the **Location**. | + +For an invoice with the status Draft, Cancelled, or Entered in Error, the page marks that status on the document. + +### 4. Print the page + +Use the print command of your browser. Send the page to a printer, or save the page as a PDF file. + +## Expected Outcome + +- Care opens the printable page for the invoice. +- The page shows the invoice details, the items, the totals, the payments, and the credit notes. +- The browser sends the page to the printer, or saves the page as a PDF file. +- The print action does not change the invoice. The status of the invoice stays the same. + +## Related + +Concepts: + +- [Invoice](../../../concepts/billing/invoice.mdx) + +References: + +- [Invoice](../../../references/billing/invoice.mdx) + +Flows: + +- [View invoices](./view-invoices.mdx) +- [Issue an invoice](./issue-invoice.mdx) +- [Record a payment against an invoice](./record-invoice-payment.mdx) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/record-invoice-payment.mdx b/versioned_docs/version-3.1/flows/billing/invoice/record-invoice-payment.mdx new file mode 100644 index 00000000..7fb75ed6 --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/record-invoice-payment.mdx @@ -0,0 +1,114 @@ +--- +sidebar_position: 7 +--- + +# Record a payment against an invoice + +## Overview + +This flow describes how to record the money that the patient or the payer paid against an issued [invoice](../../../concepts/billing/invoice.mdx) in Care. + +## Pre-requisites + +- The invoice status is Issued. Care shows the **Record Payment** action only for an issued invoice. +- If the invoice is locked, you have the permission to manage a locked invoice. +- You know the amount, the payment method and the payment date. +- You have the permissions listed below. + +## Permissions + +| Permission | Access | +| --- | --- | +| Can Read Invoice | Lets you open the invoice. | +| Can Manage Locked Invoice | Needed in addition if the invoice is locked. | + +:::note +Care checks the payment reconciliation permissions when you record the payment. For those permissions, see the [Payment Reconciliation](../../../references/billing/payment-reconciliation.mdx) reference. +::: + +## Steps + +### 1. Open the invoice + +1. Select **Billing** in the facility sidebar. +2. Select **Invoices**. +3. Select **See Invoice** for the invoice to pay. + +### 2. Start the action + +Select **Record Payment**. + +Note: Press `r` to start this action. + +Care opens the **Record Payment** sheet. The sheet shows the subtitle "Recording payment for invoice" and the invoice number. + +### 3. Check the amounts at the top of the sheet + +| Component | What it shows | +| --- | --- | +| Invoice Total | The total amount of the invoice. | +| Amount Due | The amount that is still owed on the invoice. | +| Balance Due | The balance on the account. | + +### 4. Complete the payment fields + +| Field | Required | What to enter | +| --- | --- | --- | +| Payment Method | Yes | Select one of these options: **Cash**, **Direct Deposit**, **Credit Card**, **Debit Card**, **Check**, **Credit Account**. | +| Payment Type | Yes | Select **Payment** or **Advance**. | +| Issuer Type | Yes | Identifies who paid. | +| Location | No | A picker. The placeholder is "Select Location". | +| Amount Paid | Yes | The amount you record. Enter zero or more. The helper text reads "This is the amount you are recording." | +| Amount Received | Yes, for Cash | The money the customer handed over. The helper text reads "Amount given by the customer". | +| Reference Number | No | Marked optional. The helper text reads "Transaction ID, check number, or other reference". | +| Payment Date | Yes | The date of the payment. Care refuses a future date. | +| Notes | No | Marked optional. The placeholder is "Add any notes about this payment...". | + +### 5. Check the change to return + +For the Cash method, Care computes the **Change to return**. The change to return is the amount received minus the amount paid. Care never shows a negative value. + +For every other payment method, Care sets the amount received equal to the amount paid. Care sets the change to return to zero. + +### 6. Record the payment + +Select **Record Payment** to save the payment. Select **Cancel** to close the sheet without a payment. + +While Care saves the payment, the button reads **Processing...**. + +## Validation messages + +Care refuses the payment and shows a message when an entry is not valid. + +| Situation | Message | +| --- | --- | +| A required field is empty. | "This field is required" | +| The payment date is in the future. | "Payment date cannot be in the future" | +| The amount received is less than the amount paid. | "Tender amount cannot be less than payment amount" | + +## Expected Outcome + +- Care shows the message "Payment recorded successfully". If the payment fails, Care shows the message "Error recording payment". +- The invoice shows the payment under the heading "Payments received against this invoice". +- The payments table lists the columns **Date and Time**, **Payment Method**, **Reference** and **Amount**. Each row has a **View** action and a **Print** action. +- The payments table ends with a **Total Received** line. +- The invoice summary shows the **Total Amount**, the **Total Payments Received** and the **Balance Due**. +- Care creates a payment reconciliation record. Only a record that is active and complete counts towards the totals on the invoice. + +## Related + +Concepts: + +- [Invoice](../../../concepts/billing/invoice.mdx) + +Flows: + +- [Issue an invoice](./issue-invoice.mdx) +- [Mark an invoice as balanced](./mark-invoice-as-balanced.mdx) +- [Print an invoice](./print-invoice.mdx) + +References: + +- [Invoice](../../../references/billing/invoice.mdx) +- [Payment Reconciliation](../../../references/billing/payment-reconciliation.mdx) +- [Account](../../../references/billing/account.mdx) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/view-invoices.mdx b/versioned_docs/version-3.1/flows/billing/invoice/view-invoices.mdx new file mode 100644 index 00000000..9ad6dedf --- /dev/null +++ b/versioned_docs/version-3.1/flows/billing/invoice/view-invoices.mdx @@ -0,0 +1,115 @@ +--- +sidebar_position: 1 +--- + +# View invoices + +## Overview + +This flow describes how to find and open an [invoice](../../../concepts/billing/invoice.mdx) for a facility in Care. + +## Pre-requisites + +- The facility has invoices, and you open the invoice list of that facility. +- If the invoice is locked, you have the permission to manage a locked invoice. +- You have the permissions listed below. + +## Permissions + +| Permission | Access | +| --- | --- | +| Can Read Invoice | Lets you list and open the invoices of the facility. | +| Can Manage Locked Invoice | Needed in addition to open a locked invoice. Care refuses to open a locked invoice without it. | + +:::note +The invoice screens do not hide these actions. If you do not have the permission for an action, Care refuses the request. +::: + +## Steps + +### 1. Open the invoice list + +1. In the facility sidebar, select **Billing**. +2. Select **Invoices**. + +Care opens the page **Invoice Management**. The page shows the description "View and manage invoices". + +### 2. Filter the list by patient + +Select the control **Filter by Patient**. Care shows the invoices of that patient. + +### 3. Search for an invoice number + +Enter a part of the invoice number in the box **Search Invoices**. The search ignores the letter case. + +### 4. Filter the list by status or by creator + +Care gives two more filters in one filter control. + +| Filter | What it does | +| --- | --- | +| Status | Shows the invoices with the status that you select. | +| Created by | Shows the invoices that the user you select created. | + +The status filter has these options: **Draft**, **Issued**, **Balanced**, **Cancelled**, and **Entered in Error**. + +### 5. Read the table + +The table has these columns. + +| Column | What it shows | +| --- | --- | +| Invoice Number | The number of the invoice. | +| Invoice Date | The created date, in the format DD/MM/YY, hh:mm A. | +| Account | A link to the billing account. The link opens the account in a new browser tab. | +| Status | The status of the invoice, as a coloured badge. | +| Total | The gross total of the invoice. For a locked invoice, this column shows a **Locked** badge in place of the amount. | +| Actions | The buttons **Print** and **See Invoice**. | + +The list shows the newest invoice first. The list has more than one page when the facility has many invoices. + +For a list with no result, the page shows the title "No invoices" and the description "Try adjusting your filters or search". + +### 6. Open an invoice + +In the Actions column of the row, select **See Invoice**. + +### 7. Scan a printed invoice + +Select **Scan Invoice QR**. Care opens the dialog "Scan QR". Scan the code on the printed invoice. + +A hardware barcode scanner also works on the invoice list. For a hardware scanner, you do not open the dialog. + +For a code that Care does not recognise, Care shows the error "Invalid QR code". + +:::note +The button **Scan Invoice QR** does not appear on a small screen. +::: + +## Expected Outcome + +- Care shows the invoices of the facility, and shows the newest invoice first. +- The filters and the search limit the list. +- **See Invoice** opens the invoice. +- A scan of a valid code opens the invoice of that code. +- This flow does not change an invoice. The status of each invoice stays the same. + +:::info +The same table is the **Invoices** tab of a billing account. In that tab, the Account column does not appear. +::: + +## Related + +Concepts: + +- [Invoice](../../../concepts/billing/invoice.mdx) + +References: + +- [Invoice](../../../references/billing/invoice.mdx) + +Flows: + +- [Create an invoice](./create-invoice.mdx) +- [Issue an invoice](./issue-invoice.mdx) +- [Print an invoice](./print-invoice.mdx) diff --git a/versioned_docs/version-3.1/references/billing/invoice.mdx b/versioned_docs/version-3.1/references/billing/invoice.mdx index 2c5bd1f4..28312a71 100644 --- a/versioned_docs/version-3.1/references/billing/invoice.mdx +++ b/versioned_docs/version-3.1/references/billing/invoice.mdx @@ -42,7 +42,7 @@ On issue, the server computes net and gross totals and snapshots each charge ite | `cancelled_reason` | `TextField` | `str \| None` | Set when the invoice moves to `cancelled` | | `payment_terms` | `TextField` | `str \| None` | Markdown | | `note` | `TextField` | `str \| None` | Free-text comments; markdown | -| `number` | `CharField(1000)` | `str \| None`, default `None` | Auto-generated for return invoices via the facility's `invoice_number_expression` (see [Methods](#methods--save-behaviour)) | +| `number` | `CharField(1000)` | `str \| None`, default `None` | Invoice number. The server generates it on every create when the client does not send one, from the facility's `invoice_number_expression` (see [Methods](#methods--save-behaviour)) | | `issue_date` | `DateTimeField` | `datetime \| None` (tz-aware), default `None` | Set when the invoice is issued | | `is_refund` | `BooleanField` | `bool`, default `False` | Flags a refund/return invoice; required for negative totals (see validation) | @@ -153,10 +153,100 @@ Per-component validation: `base` must carry an `amount` and no `conditions`; `ta - **`sync_invoice_items(invoice)`** (`sync_items.py`) — recomputes `total_net`, `total_gross`, `total_price_components`, and `charge_items_copy` from the linked charge items, then rounds totals using `INVOICE_FINAL_AMOUNT_PRECISION` / `INVOICE_FINAL_AMOUNT_ROUNDING_METHOD`. **Validation:** if `is_refund` is false and either total is negative, raises `ValidationError("A Refund Ivoice is required for negative values")`. - **`calculate_charge_items_summary(charge_items)`** — net = Σ base + Σ surcharge − Σ discount; gross = net + Σ tax; components aggregated per `type + code` (key = `system + code`, else `No-Code`). -- **`evaluate_invoice_identifier_default_expression(facility)`** (`default_expression_evaluator.py`) — generates `number` from the facility's `invoice_number_expression` with context `{ invoice_count, current_year_yyyy, current_year_yy }`; returns `""` if unset. `evaluate_invoice_dummy_expression` previews an expression with sample context. +- **`evaluate_invoice_identifier_default_expression(facility)`** (`default_expression_evaluator.py`) — generates `number` from the facility's `invoice_number_expression` with context `{ invoice_count, current_year_yyyy, current_year_yy }`; returns `""` if unset. `evaluate_invoice_dummy_expression` previews an expression with sample context. `perform_create` calls this function for every new invoice when the client does not send a `number`. - **`generate_return_invoice(delivery_order)`** (`return_items_invoice.py`) — creates a `draft` refund invoice (`is_refund=True`), reverses each completed `SupplyDelivery`'s charge item via `apply_charge_item_definition(reverse=True)`, marks items `billed`, runs `sync_invoice_items`, sets status `issued`, then triggers `rebalance_account_task`. Raises if any delivery is still `in_progress`. - **`cancel_return_invoice(delivery_order)`** — sets the invoice `cancelled`, marks its charge items `entered_in_error` (clears `paid_invoice`/`paid_on`), voids the supply deliveries, rebalances the account, and resyncs inventory. +## API endpoints + +`InvoiceViewSet` (`care/emr/api/viewsets/invoice.py`) is registered on the facility nested router with the prefix `invoice`. Every route is nested under a facility. + +| Method | Path | Purpose | +| --- | --- | --- | +| GET | `/api/v1/facility/{facility_external_id}/invoice/` | List the invoices in the facility | +| POST | `/api/v1/facility/{facility_external_id}/invoice/` | Create an invoice | +| GET | `/api/v1/facility/{facility_external_id}/invoice/{external_id}/` | Retrieve one invoice | +| PUT | `/api/v1/facility/{facility_external_id}/invoice/{external_id}/` | Update an invoice | +| POST | `.../invoice/{external_id}/attach_items_to_invoice/` | Add charge items to a draft invoice. Body: `charge_items`, a list of UUIDs | +| POST | `.../invoice/{external_id}/remove_item_from_invoice/` | Remove one charge item from a draft invoice. Body: `charge_item`, a UUID | +| POST | `.../invoice/{external_id}/attach_account_to_invoice/` | Attach every billable charge item on the account to the draft invoice. No body | +| POST | `.../invoice/{external_id}/cancel_invoice/` | Cancel the invoice. Body: `reason`, either `cancelled` or `entered_in_error` | +| POST | `.../invoice/{external_id}/lock/` | Lock the invoice | +| POST | `.../invoice/{external_id}/unlock/` | Unlock the invoice | + +There is no destroy endpoint. + +### Custom action behaviour + +- `attach_items_to_invoice`, `remove_item_from_invoice`, `attach_account_to_invoice`, and `cancel_invoice` each take an account-level lock. +- The three charge-item actions require the status `draft`. For any other status they raise `ValidationError("Invoice is not in draft")`. +- `attach_items_to_invoice` accepts only the charge items on the same account with the status `billable`. Matched items move to `billed` and link to the invoice. The action ignores unmatched ids without a message. +- `remove_item_from_invoice` returns the item to `billable` and clears `paid_invoice` and `paid_on`. An item that is not on the invoice raises `ValidationError("Charge item not found in invoice")`. +- `cancel_invoice` rejects a `reason` outside the two allowed values with `ValidationError("Invalid reason")`. It rejects an invoice that is already void with `ValidationError("Invoice is already cancelled")`. It returns every charge item on the invoice to `billable`. +- `lock` and `unlock` append an entry to `lock_history` with the user, a timestamp, and the action. They raise `ValidationError` with "Invoice is already locked" and "Invoice is not locked". +- The three charge-item actions and `cancel_invoice` return the full `InvoiceRetrieveSpec` payload. +- Every action that changes the items or the status triggers `rebalance_account_task` for the account. `lock` and `unlock` do not. + +### Filtering and ordering + +The list is scoped to the facility in the path. The filterset is `InvoiceFilters`. + +| Query parameter | Match | +| --- | --- | +| `status` | Case-insensitive exact | +| `title` | Case-insensitive contains | +| `account` | Account external id (UUID) | +| `patient` | Patient external id (UUID) | +| `number` | Case-insensitive contains | +| `locked` | Boolean | +| `is_refund` | Boolean | +| `created_by` | User external id (UUID) | +| `created_date` | Datetime from/to range | +| `payment_reconciliation_present` | Boolean. Keeps or excludes the invoices that have a reconciliation on the given account | + +`payment_reconciliation_present` also needs `account`. Without `account`, the filterset raises `ValidationError("Account is required when payment reconciliation filter is present")`. + +Ordering fields: `created_date` and `modified_date`. + +## Permissions + +The four invoice permissions are facility-scoped. The authorization controller checks each permission against the facility organization memberships of the user. + +| Permission | Human-readable name | Checked by | System roles | +| --- | --- | --- | --- | +| `can_read_invoice` | Can Read Invoice | `can_read_invoice_in_facility` — list and retrieve | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | +| `can_write_invoice` | Can Write Invoice | `can_write_invoice_in_facility` — create, update, the three charge-item actions, and cancel inside the free-cancel period | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist | +| `can_destroy_invoice` | Can Destroy Invoice | `can_destroy_invoice_in_facility` — cancel after the free-cancel period | Facility Admin, Admin | +| `can_manage_locked_invoice` | Can Manage Locked Invoice | `can_manage_locked_invoice_in_facility` — lock, unlock, and retrieve a locked invoice | Facility Admin, Admin | + +The failure messages are "Cannot read invoice", "Cannot write invoice", "Cannot cancel invoice", and "Locked invoice permission denied." + +Create also validates that the account belongs to the facility in the path. For an account of another facility, the viewset raises `ValidationError("Account is not associated with the facility")`. + +### Free-cancel period + +The setting `INVOICE_FREE_CANCEL_PERIOD_MINUTES` comes from the environment, and its default value is `0`. Inside that many minutes of `created_date`, a cancel needs only `can_write_invoice`. After that period, a cancel needs `can_destroy_invoice`. With the default value of `0`, every cancel needs `can_destroy_invoice`. + +## Status transitions + +### Create + +`perform_create` always forces `status` to `draft`. It sets the facility from the path, and resolves only the `billable` charge items on the account. It generates `number` when the client did not send one. It moves the resolved items to `billed` with `paid_invoice` set, runs `sync_invoice_items`, then rebalances the account. `perform_create` takes an account lock and a create lock. A lock conflict raises `ValidationError("Invoice creation failed")`. + +### Update + +`perform_update` holds an invoice lock and enforces the transitions below. It calls `rebalance_account_task` afterwards. + +| From | To | Result | +| --- | --- | --- | +| `draft` | `issued` | Allowed when the invoice has at least one charge item. For an empty invoice, `ValidationError("Invoice must have at least one charge item")` | +| `draft` | `balanced` | `ValidationError("Invoice needs to be issued before balancing")` | +| `issued` | `balanced` | Allowed. Every charge item on the invoice with the status `billed` moves to `paid`, with `paid_invoice` set and `paid_on` stamped | +| `issued` | `draft` | `ValidationError("Invoice is already issued")` | +| `balanced` | any | `ValidationError("Invoice is already balanced")` | +| any | `cancelled` or `entered_in_error` | `ValidationError("Call the cancel invoice API to cancel the invoice")`. Use the `cancel_invoice` action | +| `cancelled` or `entered_in_error` | any | `ValidationError("Invoice is already cancelled")` | + ## API integration notes - `status` is the control surface for the billing lifecycle. Drive transitions through the API rather than editing rows directly; the values are `draft`, `issued`, `balanced`, `cancelled`, `entered_in_error`. @@ -167,6 +257,16 @@ Per-component validation: `base` must carry an `amount` and no `conditions`; `ta ## 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: [Account](../billing/account.mdx) - Reference: [Charge Item](../billing/charge-item.mdx) - Reference: [Charge Item Definition](../definitions/charge-item-definition.mdx) diff --git a/versioned_sidebars/version-3.1-sidebars.json b/versioned_sidebars/version-3.1-sidebars.json index 5f6c5e33..8a8cb300 100644 --- a/versioned_sidebars/version-3.1-sidebars.json +++ b/versioned_sidebars/version-3.1-sidebars.json @@ -78,6 +78,30 @@ ] } ] + }, + { + "type": "category", + "label": "Billing", + "key": "billing-flows", + "items": [ + { + "type": "category", + "label": "Invoice", + "key": "billing-invoice-flows", + "items": [ + "flows/billing/invoice/view-invoices", + "flows/billing/invoice/create-invoice", + "flows/billing/invoice/edit-invoice-details", + "flows/billing/invoice/edit-invoice-items", + "flows/billing/invoice/issue-invoice", + "flows/billing/invoice/print-invoice", + "flows/billing/invoice/record-invoice-payment", + "flows/billing/invoice/mark-invoice-as-balanced", + "flows/billing/invoice/lock-and-unlock-invoice", + "flows/billing/invoice/cancel-invoice" + ] + } + ] } ] }, From b0c9d775f38f453edec550e5660146df1e132007 Mon Sep 17 00:00:00 2001 From: gauritejusa Date: Tue, 11 Aug 2026 17:43:15 +0530 Subject: [PATCH 2/3] docs(invoice): restyle concept page to match encounter.mdx structure Reorders sections to What it represents -> Lifecycle -> Refunds -> Locking -> How it connects -> Permissions -> Related, and simplifies the Lifecycle section by replacing the status-transition table and duplicate cancel-permission paragraph with a single terse prose paragraph, matching the Encounter concept page's style. --- .../version-3.1/concepts/billing/invoice.mdx | 32 ++++++------------- 1 file changed, 10 insertions(+), 22 deletions(-) diff --git a/versioned_docs/version-3.1/concepts/billing/invoice.mdx b/versioned_docs/version-3.1/concepts/billing/invoice.mdx index 6eed31f2..ccc6abe8 100644 --- a/versioned_docs/version-3.1/concepts/billing/invoice.mdx +++ b/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,19 +27,7 @@ draft → issued → balanced - **cancelled** — voided after issue; no longer collectible - **entered_in_error** — recorded by mistake and retracted -Care permits only one path through the ordinary statuses: `draft` to `issued`, then `issued` to `balanced`. - -| Status change | Permitted | -| --- | --- | -| `draft` to `issued` | Yes, if the invoice has at least one charge item | -| `issued` to `balanced` | Yes | -| `draft` to `balanced` | No | -| `issued` to `draft` | No | -| `balanced` to any other status | No | - -`cancelled` and `entered_in_error` are the two terminal void states. Care never sets them with an ordinary status change. Care sets them only with the dedicated cancel action, which also adjusts the linked charge items and the account. - -The permission Care requires for a cancel action depends on the age of the invoice. Inside a configurable free-cancel period, `can_write_invoice` is enough. After that period, `can_destroy_invoice` is necessary. The free-cancel period is a deployment setting, and its default value is zero minutes. With the default configuration, a cancel action always needs `can_destroy_invoice`. +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 @@ -60,6 +39,15 @@ Care can **lock** an invoice at any status. A lock does not change the status of 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: From 32a90166e5d1a675d1fdc5cef46496fa40406957 Mon Sep 17 00:00:00 2001 From: gauritejusa Date: Tue, 11 Aug 2026 17:45:29 +0530 Subject: [PATCH 3/3] docs(invoice): fix create-invoice keyboard shortcut On the account screen (facility:account:show scope), i creates an invoice and c adds credit. The doc incorrectly said c; corrected to i, matching care_fe/src/config/keyboardShortcuts.json. --- .../version-3.1/flows/billing/invoice/create-invoice.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-3.1/flows/billing/invoice/create-invoice.mdx b/versioned_docs/version-3.1/flows/billing/invoice/create-invoice.mdx index 087d600e..552834f8 100644 --- a/versioned_docs/version-3.1/flows/billing/invoice/create-invoice.mdx +++ b/versioned_docs/version-3.1/flows/billing/invoice/create-invoice.mdx @@ -35,7 +35,7 @@ This flow describes how to build a draft [invoice](../../../concepts/billing/inv Select **Create Invoice**. On a small screen the same button reads **Invoice**. -Note: Press `c` on the account screen to start the 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.