> For the complete documentation index, see [llms.txt](https://tutearnio.gitbook.io/tutearn-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tutearnio.gitbook.io/tutearn-docs/user-manual-invoice.md).
# User Manual Invoice
> Real-world guide for tutoring center admins and finance staff. All examples use **Bright English Academy** demo data.
Invoices are how you bill students (or their parents) for tuition and track what they've paid. This guide covers creating invoices, the three ways they get generated, recording payments, and the automatic status updates that keep everything in sync.
Find them under **Finance → Invoices** (`/invoice`).
***
## Who can use Invoices
Invoice screens are gated by standard permissions (`read`, `create`, `update`, `delete`, `archive`, `restore`, `import`, `export`). Recording a payment needs a separate **`payment: create`** permission, because a payment is its own record.
| To do this… | You need… |
| ------------------------------ | ------------------------------------- |
| See the Invoices menu and list | `invoice: read` |
| Create / edit an invoice | `invoice: create` / `invoice: update` |
| Record a payment on an invoice | `payment: create` |
| Archive / delete / restore | the matching `invoice` permission |
***
## The Big Picture — How Invoices Connect
```
Student "Who is billed" (required)
└─ Invoice "The bill: line items, total, due date, status"
└─ Payment "Money received against the invoice"
▲
└── recording a payment automatically updates the invoice's
Amount Paid + Status, and the linked Enrollment's payment status
```
An invoice always belongs to **one student**. It can optionally link to an **enrollment**, **term**, **billed parent**, **client account**, and a managing **member**. Money comes in as **payments**, and the platform keeps the invoice's balance and status current for you — you rarely set "paid" by hand.
***
## Part 1 — Anatomy of an Invoice
### 1.1 Fields
| Field | Required | Notes |
| ------------------- | -------- | ---------------------------------------------------------- |
| **Invoice number** | ✅ | Unique per organization (e.g. `INV-20260615-4821`) |
| **Issue date** | ✅ | When the invoice is raised |
| **Due date** | ✅ | When payment is expected |
| **Description** | — | Free text shown on the invoice |
| **Line items** | — | A **JSON array** of items (see 1.2) |
| **Subtotal** | ✅ | Amount before tax/discount |
| **Tax amount** | — | Tax added |
| **Discount amount** | — | Discount subtracted |
| **Total amount** | ✅ | The amount owed — **entered directly**, see the note below |
| **Amount paid** | — | Managed automatically as payments come in |
| **Currency** | ✅ | The invoice currency |
| **Status** | ✅ | See 1.3 |
| **Notes** | — | Internal notes |
| **Invoice PDF** | — | Attach one file (e.g. an externally produced PDF) |
| **Student** | ✅ | Who is billed |
| **Enrollment** | — | Links the bill to a class enrollment |
| **Member (user)** | — | The managing staff member |
| **Billed parent** | — | The parent responsible for payment |
| **Term** | — | The academic term billed |
| **Client account** | — | A billing account, if you use them |
> **Total is not auto-calculated in the form.** Subtotal, tax, discount, and total are independent inputs. When entering them by hand, make sure **Total = Subtotal + Tax − Discount** yourself. (The "create from enrollment" path does compute it for you — see Part 2.)
### 1.2 Line items format
The **Line items** field holds a **JSON array**. Each item is an object with a description, quantity, and unit price, e.g.:
```json
[
{ "description": "Tuition fee — IELTS Prep – June 2026", "quantity": 1, "unitPrice": 4500 }
]
```
This is what renders as the itemized table on the invoice document and PDF.
### 1.3 Statuses
| Status | Meaning | Set by |
| ------------------ | -------------------------------- | ------------- |
| **Draft** | Being prepared, not yet sent | You |
| **Sent** | Issued to the student/parent | You |
| **Viewed** | The recipient has opened it | You |
| **Partially paid** | Some, but not all, has been paid | **Automatic** |
| **Paid** | Fully paid | **Automatic** |
| **Overdue** | Past the due date and unpaid | You |
| **Cancelled** | Voided | You |
| **Refunded** | Money returned | You |
> **Partially paid** and **Paid** are driven by payments (Part 4). Don't set them by hand — the next payment recalculation will overwrite your choice.
***
## Part 2 — Three Ways to Create an Invoice
### Way 1 — Manually
**Invoices → New** (`/invoice/new`). Fill the form (Part 1) and save. Use this for ad-hoc bills or anything not tied to an enrollment.
### Way 2 — From an enrollment (Recommended)
When a student has an enrollment with an **agreed fee**, you can generate a ready-to-send invoice in one step (from the enrollment's actions). This:
* Requires the enrollment to have an **agreed fee greater than zero**, and your organization to have a **default currency** set — otherwise it errors with a clear message.
* Sets **subtotal = agreed fee**, applies the enrollment's **discount**, and computes **total = fee − discount**.
* Creates the invoice as **Sent**, **due in 30 days**, with a line item like *"Tuition fee — IELTS Prep – June 2026."*
* Links the invoice to the student, enrollment, and term automatically.
### Way 3 — During enrollment (Scheduling Hub)
The **Schedule a class** wizard and the **Enroll student** popover can create **draft invoices** (due in 14 days), one per enrolled student, when a fee is set and the course has a currency. See the Scheduling Hub manual for details.
***
## Part 3 — The Invoice View Page
Opening an invoice (`/invoice/$id`) shows three regions:
**Left — the invoice document.** A live, formatted preview using your organization's **invoice template**: header, "Bill To," the line-item table, totals, payment history, and payment instructions.
**Right — the money panel:**
* **Payment Progress** — a progress bar plus **Amount Paid**, **Balance Due** (green when settled), and **Total Amount**.
* **Payments** — every payment recorded against this invoice, each linking to its payment record.
* **Student** — quick link to the billed student.
* **Record details** — collapsible audit info (created/updated/archived by & when).
**Top-right actions:**
* **Download PDF** — generates the invoice PDF server-side (bill-to, payment history, payment instructions, balance due).
* **Record Payment** — opens the payment dialog (Part 4). Disabled once the invoice is fully paid.
* The **⋯ menu** — Edit, Audit log, Archive/Restore, Delete.
***
## Part 4 — Recording a Payment (the core workflow)
Click **Record Payment** on the invoice. This is how money gets logged and how the invoice moves toward "paid."
### 4.1 The dialog
| Field | Notes |
| --------------------- | ------------------------------------------------------------------- |
| **Amount** | Defaults to the **balance due**; a **Pay in full** button fills it |
| **Payment date** | Defaults to now |
| **Payment channel** | Required — pick from your **active payment channels** |
| *(More options)* | Expand for the fields below |
| Transaction reference | Auto-generated (`PAY-INV-…`); edit if the payer gave you one |
| Status | Defaults to **Completed** (only completed payments count — see 4.2) |
| Paid by (payer name) | Optional free-text payer |
| Paid by parent | Optionally attribute the payment to a parent |
| Notes | Optional |
| Proof of payment | Upload a receipt/screenshot |
> **You must have at least one active payment channel.** If none are configured, the dialog shows: *"No active payment channels are configured. Add one in Payment Settings first."* Channels are managed under **Payment Settings**; each can carry account details and instructions that appear here and on the PDF.
### 4.2 What happens automatically after you save
Recording (or later editing/archiving/restoring) a payment triggers an automatic recalculation of the invoice:
* **Amount paid** = the sum of all **completed, non-archived** payments. A payment left in a non-completed status does **not** count toward the balance.
* The invoice **status** updates itself:
| Condition | Invoice becomes | Linked enrollment becomes |
| ----------------------------------- | -------------------------------------------- | ------------------------- |
| Amount paid ≥ total | **Paid** | **Paid** |
| 0 < amount paid < total | **Partially paid** | **Partially paid** |
| Amount paid back to 0 (all removed) | reverts to **Sent** (if it was paid/partial) | **Unpaid** |
* **Receiving any payment also activates a still-pending enrollment** — a `pending` enrollment flips to `active`. This is one-way: an already active, completed, withdrawn, or suspended enrollment is never pushed back.
In other words: record the payment, and the invoice's paid amount, the invoice status, and the enrollment's payment/lifecycle status all update for you.
### 4.3 Refunds and reversals
To unwind a payment, **archive** (or change away from *completed*) the payment record. The recalculation runs again: amount paid drops, and a fully/partly paid invoice reverts to **Sent**. For an actual refund to the customer, also set the invoice status to **Refunded** and record the refund through your finance process.
***
## Part 5 — The Invoices List
**Invoices** (`/invoice`) lists every invoice with filtering and export.
You can filter by: invoice number, issue/due date ranges, total and amount-paid ranges, status, currency, student, enrollment, term, billed parent, client account, created/updated ranges, and archived state. Use **Export** to download the filtered set, and the row **⋯ menu** to view, edit, archive, or delete.
***
## Tips, Pitfalls & FAQ
"The Record Payment button is greyed out."
The invoice is already **fully paid** (balance due is zero), or you lack `payment: create`, or the invoice is archived.
"I can't pick a payment channel."
None are active. Add one under **Payment Settings**, then reopen the dialog.
"Create from enrollment failed."
The enrollment has **no agreed fee** (or it's zero), or your organization has **no default currency** set. Fix either and retry.
"I set the invoice to Paid but it flipped back."
Paid / Partially paid are **automatic**. The status follows the payments — record a payment for the full amount instead of editing the status.
"The total looks wrong."
On the manual form, **Total Amount** is its own field — it isn't computed from subtotal/tax/discount. Make sure you enter **Total = Subtotal + Tax − Discount**.
"A payment doesn't show in the balance."
Only **completed** payments count. Check the payment's status.
"Recording a payment changed the enrollment."
That's expected: a first payment moves a **pending** enrollment to **active**, and the enrollment's payment status mirrors the invoice (unpaid → partially paid → paid).
***
## Quick Reference
| Task | Where |
| -------------------------------- | ---------------------------------------------- |
| Create a bill manually | Invoices → New |
| Bill an enrollment automatically | Enrollment → create invoice (needs agreed fee) |
| See balance & history | Invoice view → Payment Progress / Payments |
| Take a payment | Invoice view → **Record Payment** |
| Send the bill as a file | Invoice view → **Download PDF** |
| Undo a payment | Archive the payment (invoice reverts to Sent) |
| Set up payment channels | **Payment Settings** |
| Find/filter invoices | Invoices list → filters + Export |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://tutearnio.gitbook.io/tutearn-docs/user-manual-invoice.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.