> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitaji360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expenses & Expense Claims

> An expense records a cost your business incurs that isn't billed on vendor terms — typically an out-of-pocket cost or a staff reimbursement claim.

An **expense** records a cost your business incurs that isn't billed on vendor terms — typically an out-of-pocket cost or a staff reimbursement claim. Unlike a [bill](/accounting/user/transactions/purchase-bills), an expense is usually raised by the person who spent the money, can be reviewed and **sanctioned** (the approver may approve less than was claimed), and is then paid out to that person or vendor.

You'll find this at: `/accounting/expenses`

In the navigation this is labelled **Expense Claims** under Finance → Payables. Staff members see their own claims; finance users with the right permission see everyone's.

> 📷 *Screenshot: Expenses list with reference number, claimant, date, amount, status and payment status — to be added.*

***

## When to use an expense claim

* A staff member paid for something out of pocket and wants reimbursing.
* You're recording a cost with multiple itemised lines (travel, meals, supplies) that should be reviewed and approved before payment.
* The cost may be partly covered by a cash **advance** the staff member was given earlier.

For supplier invoices on payment terms use a [Bill](/accounting/user/transactions/purchase-bills); for small immediate cash payouts use [Petty Cash](/accounting/user/transactions/petty-cash).

***

## The expense lifecycle (statuses)

An expense has two parallel status fields: the **workflow state** and the **payment status**.

**Workflow state:**

| Status              | Meaning                                                   |
| ------------------- | --------------------------------------------------------- |
| **Draft**           | Created, editable, not yet submitted.                     |
| **PendingApproval** | Submitted, awaiting finance review/sanction.              |
| **Approved**        | Approved and the accrual posted (the payable now exists). |
| **Paid**            | Settled — money paid out (or fully covered by advances).  |
| **Void**            | Cancelled; any posted entries reversed.                   |

**Payment status:** **UNPAID** or **PAID** — tracks whether the money has actually gone out, independently of the workflow state.

***

## Recording an expense — step by step

1. Go to **Expense Claims** (`/accounting/expenses`) and choose **New Expense**.
2. Fill in the header:
   * **Expense date** — required. The posting date for the claim.
   * **Description / purpose** *(optional)* — header-level note.
   * **Vendor (contact)** *(optional)* — when the cost relates to a specific party.
   * **Currency** *(optional, default UGX)* and **exchange rate** *(optional, default 1.0)* — for foreign-currency claims, the rate converts amounts to your base currency.
   * **Project / Task** *(optional)* — attribute the cost to a project/task (a task must belong to the project when both are given).
   * **Attachments** *(optional)* — receipts.
3. Add one or more **line items** (see below). If you don't add explicit items, the system creates a single item from the header amount.
4. Optionally add **advances** to draw from and **tax lines** (see below).
5. Save as **Draft**, or set the status to submit straight away.

### Line item fields

| Field                | Required?   | Notes                                                                                                   |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| **Expense date**     | Yes         | Date for this specific item.                                                                            |
| **Amount (claimed)** | Yes         | What the claimant is asking for (minimum 0.01).                                                         |
| **Description**      | Optional    | Up to 500 characters.                                                                                   |
| **Claim type**       | Preferred   | A worker-friendly category that maps to a GL account (see [Expense Claim Types](#expense-claim-types)). |
| **Expense account**  | Alternative | Book the line directly to a GL account (legacy; prefer claim type).                                     |
| **Category**         | Optional    | For analysis; can supply a default expense account.                                                     |

Each item needs **either** a claim type **or** an expense account. If you supply neither, the system tries the category's default account, then falls back to the workspace's default operating-expense account; if it still can't resolve one, it asks you to pick one.

### Expense taxes

You can add **tax and charge lines** (VAT, WHT, etc.). Each tax line specifies:

* **GL account** for the tax (e.g. Input VAT, WHT account)
* **Description** (e.g. "VAT 18%")
* **Rate (%)** *(optional, display only)*
* **Tax amount** in the claim currency

Taxes are added to the sanctioned line totals to produce the claim's **grand total**.

### Advances against a claim

If the claimant was given a cash **advance** earlier, list the advances to draw from and the amount to allocate from each. When the claim is approved, the system reconciles each advance and — if the advances **fully cover** the claim — settles it automatically against the advance (see [Behind the scenes](#behind-the-scenes-the-accounting)). A partial advance that doesn't fully cover the claim is left to the normal payment flow.

***

## Submitting, sanctioning and approving

1. **Submit for approval** — from a Draft (requires at least one line item). Moves the claim to **PendingApproval**. Requires `accounting-expenses:update`.
2. **Sanction amounts** *(approver, optional)* — before approving, the approver can set the **sanctioned (approved) amount** per item. The sanctioned amount must be **≤ the claimed amount** — approvers can trim a claim but never inflate it. Requires `accounting-expenses:approve`. Only available while the claim is **PendingApproval**.
3. **Approve** — on approval, any items not explicitly sanctioned are auto-sanctioned at their claimed amount, the grand total (sanctioned + taxes) is computed, and the **accrual** is posted to the ledger.

> The claimed vs sanctioned distinction is the heart of expense review: staff claim, finance approves the amount it agrees to pay.

***

## Paying an expense

Once **Approved**, finance records payment. Choose **Record payment** (requires `accounting-expenses:post`) and enter:

* **Payment account** — must be an **ASSET-type** (cash/bank/mobile-money) account in the same book.
* **Mode of payment** — CASH, BANK\_TRANSFER, CHEQUE or MOBILE\_MONEY.
* **Payment date**.
* **Payment reference** *(optional)*.

The claim moves to **Paid** / payment status **PAID**, and the payment posts to the ledger (clearing the payable). The amount paid equals the accrued grand total, so payment clears exactly what the accrual booked (including taxes).

***

## Editing, deleting and voiding

* **Edit** — allowed until the claim is **Approved**. You can change header fields, items, advances and taxes; totals recompute from the items. Requires `accounting-expenses:update`. (An Approved claim can't be edited — void it and create a new one.)
* **Delete** — only **Draft** claims can be deleted (soft delete). Requires `accounting-expenses:delete`.
* **Void** — only **Submitted (PendingApproval)** or **Approved** claims can be voided. Voiding **reverses both** the payment journal entry (if paid) **and** the accrual journal entry, then marks the claim Void. Requires `accounting-expenses:void`.

***

## Who can see which claims

Listing and viewing are ownership-scoped. A user **without** the `accounting-expenses:read-all` permission only sees and can open **their own** claims; trying to open someone else's returns "not found". Users **with** `read-all` (finance) see every claim. This same scoping applies to the expense summary and unpaid reports.

There's also an **Unpaid report** (`/accounting/expenses/unpaid-report`) that groups approved-but-unpaid claims by submitter, so finance can see who's owed what before a payment run.

***

## Behind the scenes — the accounting

**On approval (accrual entry):**

* **Debit** each expense account (from the line's claim type or account) for its sanctioned amount, plus a debit to each **tax account** for its tax amount. Per-line cost centers carry into the ledger.
* **Credit Accounts Payable** for the grand total (sanctioned + taxes) in base currency.

If the claim was raised by a linked staff member, the payable credit is **sub-ledgered to that employee** (via their per-book employee Contact), so staff payables net by real person. This is best-effort — it never blocks the posting.

**On payment:**

* **Debit Accounts Payable** (clearing the liability) for the grand total.
* **Credit your cash/bank account** (money out).

(For older claims with no accrual entry, payment posts directly: Debit Expense / Credit Cash.)

**When fully covered by advances:** instead of a cash payment, the system posts **Debit Accounts Payable / Credit Staff Advances**, clearing the payable against the advance the staff member already holds. This needs a `staff_advances` control account in the book; if it's missing, the settlement is skipped and surfaced in the logs.

**On void:** the accrual (and any payment) entries are reversed, restoring the trial balance.

***

## Expense Claim Types

**Expense claim types** are reusable, worker-friendly categories that each map to a GL **expense account** (and optionally a default **cost center**). They let staff pick "Travel" or "Meals" instead of hunting through the chart of accounts, while finance keeps control of where each type posts.

You'll find these at: ERP Settings → **Accounting** → **Expense Claim Types** (under `/settings/erp`). The API lives at `/accounting/expense-claim-types`.

### Managing claim types

* **Create** — give the type a **name** (unique within the book) and pick an **expense account** (must be an EXPENSE-type account in the same book). Optionally set a **description**, a **default cost center**, and whether it's **active**.
* **Update** — rename, repoint the account, or toggle active. Renaming to a name already in use is blocked.
* **Deactivate (delete)** — soft-deletes and deactivates the type. Existing claims that already used it are unaffected.

When a claim line uses a claim type, the accrual debits that type's mapped expense account — so changing claim types changes where future claims post without retraining staff.

> 📷 *Screenshot: Expense Claim Types settings panel listing each type, its mapped account and active toggle — to be added.*

***

## Multi-business note

Expenses, their items, taxes, advances and claim types all live inside a single **accounting book** (`workspaceId`) and never cross businesses. Switch to the correct business before recording or approving claims.

***

## Permissions reference

Expense actions are gated by the `accounting-expenses` permission module:

| Action                    | Permission slug                |
| ------------------------- | ------------------------------ |
| Create a claim            | `accounting-expenses:create`   |
| View own claims           | `accounting-expenses:read`     |
| View all claims (finance) | `accounting-expenses:read-all` |
| Edit / submit             | `accounting-expenses:update`   |
| Delete a draft            | `accounting-expenses:delete`   |
| Sanction / approve        | `accounting-expenses:approve`  |
| Record payment            | `accounting-expenses:post`     |
| Void                      | `accounting-expenses:void`     |

(Expense Claim Types are managed in ERP Settings and don't use a separate per-action slug beyond standard accounting settings access.)

***

## Related

* [Purchase Bills (Accounts Payable)](/accounting/user/transactions/purchase-bills) — supplier invoices on terms
* [Petty Cash](/accounting/user/transactions/petty-cash) — small immediate cash payouts
* [Debit Notes](/accounting/user/transactions/debit-notes) — vendor returns