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

# Recording Expenses

> Step-by-step guide to entering organizational spending, including standard expenses, reserve-funded expenses, and bank charges

## Overview

Recording expenses ensures all organizational spending is tracked in Agatabo. This maintains accurate financial records, enables budgeting, and generates complete financial reports. Expenses can be paid from bank account cash or funded from reserve allocations.

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `expenses:write` permission
  * You have a receipt or documentation for the expense
  * You know which bank account paid the expense (or which reserve funded it)
  * You've decided on a clear, descriptive title for the expense
</Note>

## Recording a Standard Expense

### Step 1: Navigate to Expenses

<Steps>
  <Step title="Open Expenses section">
    Click **Expenses** in the left sidebar
  </Step>

  <Step title="Click Record Expense or Add Expense">
    Opens the expense recording form/dialog
  </Step>
</Steps>

### Step 2: Fill Required Fields

**Required Information:**

| Field      | Description                  | Validation                       |
| ---------- | ---------------------------- | -------------------------------- |
| **Title**  | Short description of expense | Required, non-empty string       |
| **Amount** | How much was spent           | Required, minimum 0.01           |
| **Date**   | When expense occurred        | Required, ISO date (can be past) |

**Example values:**

* Title: "Office Rent - June 2026"
* Amount: 150000 (or 150,000 RWF)
* Date: 2026-06-08

<Note>
  **Title field is NOT "Category"**: The backend uses a free-form `title` field, not a predefined category dropdown. Use clear, consistent titles to organize your expenses.
</Note>

### Step 3: Fill Optional Fields

**Optional Information:**

| Field                  | Description                              | Default                       |
| ---------------------- | ---------------------------------------- | ----------------------------- |
| **Bank Account**       | Which account paid the expense           | Falls back to default account |
| **Description**        | Detailed explanation of the expense      | None                          |
| **Documents**          | Upload receipts, invoices, or references | None                          |
| **Bank Charge Amount** | Additional bank service charge           | 0 (no charge)                 |

**Description tips:**

* Explain what was purchased and why
* Include relevant details (period, vendor, purpose)
* Example: "Monthly office space rental at Kimihurura for June 2026, paid to Landlord ABC"

**Documents:**

* Upload photos or PDFs of receipts
* Store invoice copies
* Keep audit trail of supporting documentation

### Step 4: Add Bank Charge (Optional)

If the expense incurred a bank service charge (transaction fee, wire fee):

<Steps>
  <Step title="Enter Bank Charge Amount field">
    Add the additional bank fee amount
  </Step>

  <Step title="System creates linked entry">
    Agatabo automatically creates separate BANK\_CHARGE journal entry
  </Step>

  <Step title="Total deduction">
    Bank account decreases by expense amount + bank charge
  </Step>
</Steps>

**Example:**

```
Expense Amount: 200,000 RWF
Bank Charge Amount: 3,000 RWF
Total Bank Deduction: 203,000 RWF

Creates 2 journal entries:
1. EXPENSE_PAYMENT: 200,000 RWF
2. BANK_CHARGE: 3,000 RWF (auto-linked to expense)
```

### Step 5: Submit

<Steps>
  <Step title="Review all fields">
    Verify title, amount, date, and bank account are correct
  </Step>

  <Step title="Click Save or Record Expense">
    Creates the expense record with journal entries
  </Step>

  <Step title="Confirm success">
    Expense appears in expense history
  </Step>

  <Step title="Verify bank balance">
    Check bank account balance decreased correctly
  </Step>
</Steps>

## Recording a Reserve-Funded Expense

For expenses paid from designated reserve allocations (emergency fund, specific reserve):

### Step 1: Navigate and Start

<Steps>
  <Step title="Open Expenses section">
    Click Expenses in sidebar
  </Step>

  <Step title="Click Record Expense">
    Opens expense form
  </Step>
</Steps>

### Step 2: Fill Expense Details

Fill the same required fields:

* **Title**: Descriptive expense name
* **Amount**: How much to spend from reserve
* **Date**: When expense occurred

### Step 3: Select Reserve Allocation

<Steps>
  <Step title="Find Reserve Allocation field">
    Dropdown or selector for reserve funds
  </Step>

  <Step title="Select the reserve">
    Choose which reserve fund to draw from (e.g., "Emergency Fund", "Equipment Reserve")
  </Step>

  <Step title="Verify sufficient balance">
    Reserve must have enough balance for the expense
  </Step>
</Steps>

### Step 4: Optional Bank Account

**Reserve-funded expenses behavior**:

* Bank account is optional (can be omitted)
* If provided: System releases reserve TO that account, then pays expense FROM it
* If omitted: Uses default bank account

### Step 5: Submit

<Steps>
  <Step title="Review details">
    Verify reserve allocation and amount
  </Step>

  <Step title="Click Save">
    Creates TWO journal entries automatically
  </Step>

  <Step title="Verify results">
    * Reserve balance decreased
    * Expense recorded
    * Bank balance unchanged (released then spent)
  </Step>
</Steps>

**What happens:**

```
Reserve-funded expense: 100,000 RWF from Emergency Fund

Journal Entry 1 - Reserve Release:
Dr CASH (Bank Account)              100,000
   Cr RESERVE_ALLOCATION (Emergency)  100,000

Journal Entry 2 - Expense Payment:
Dr OPERATING_EXPENSE               100,000
   Cr CASH (Bank Account)          100,000

Result:
- Emergency Fund: -100,000 RWF
- Bank Account: Unchanged (released then spent)
- Expense recorded: +100,000 RWF
```

[Learn more about reserves →](/tontines/reserves/overview)

## Recording with Bank Charge

Complete example of expense with bank charge:

### Scenario: Pay Supplier with Wire Fee

**Details:**

* Supplier payment: 500,000 RWF
* Wire transfer fee: 5,000 RWF
* Total cost: 505,000 RWF

### Steps

<Steps>
  <Step title="Fill expense fields">
    * Title: "Payment to Supplier XYZ"
    * Amount: 500,000
    * Date: 2026-06-11
    * Bank Account: Operations Account
    * Description: "Purchase order #456 - Office furniture"
  </Step>

  <Step title="Add bank charge">
    * Bank Charge Amount: 5,000
  </Step>

  <Step title="Submit">
    System creates 2 linked journal entries
  </Step>
</Steps>

**Result:**

```
Entry 1 - Main Expense:
Dr OPERATING_EXPENSE (Supplies)  500,000
   Cr CASH (Operations)          500,000

Entry 2 - Bank Charge (auto-linked):
Dr BANK_CHARGE_EXPENSE  5,000
   Cr CASH (Operations)  5,000

Total Bank Decrease: 505,000 RWF
Expense shows in history with linked bank charge
```

## What Happens When You Record

When you submit an expense, Agatabo automatically:

1. **Validates inputs**:
   * Amount >= 0.01
   * Title is non-empty
   * Date is valid ISO format
   * Bank account exists and is active
   * Reserve has sufficient balance (if reserve-funded)

2. **Creates journal entries**:
   * Main expense entry (EXPENSE\_PAYMENT or RESERVE\_EXPENSE)
   * Reserve release entry (if reserve-funded)
   * Bank charge entry (if bank charge amount provided)

3. **Updates balances**:
   * Reduces bank account balance (CASH ledger)
   * Reduces reserve balance (if reserve-funded)
   * Records expense in OPERATING\_EXPENSE or BANK\_CHARGE\_EXPENSE

4. **Records metadata**:
   * Creates ExpenseMeta record with all details
   * Links to journal entries
   * Stores documents as JSON

5. **Logs audit trail**:
   * Records who created the expense
   * Timestamp of creation
   * IP address and user agent (if available)

6. **Updates reports**:
   * Appears on Profit & Loss statement
   * Shows in expense history
   * Affects financial metrics

## Editing Expenses

You can edit expenses to correct errors or update information.

### How to Edit

<Steps>
  <Step title="Navigate to expense history">
    Expenses → View History or List Expenses
  </Step>

  <Step title="Find the expense">
    Search or browse for the expense to edit
  </Step>

  <Step title="Click Edit">
    Opens edit form with current values
  </Step>

  <Step title="Update fields">
    Change any field (title, amount, description, date, etc.)
  </Step>

  <Step title="Submit changes">
    System uses reverse-and-repost pattern
  </Step>
</Steps>

### What You Can Change

**All fields are editable**:

* Title
* Amount
* Date
* Description
* Bank account
* Reserve allocation
* Bank charge amount
* Documents

### How Editing Works (Reverse-and-Repost)

**Important**: Agatabo doesn't modify existing entries. Instead:

1. **Reverses old entries**:
   * Creates reversal of main expense
   * Reverses linked bank charge (if exists)
   * Reverses reserve release (if reserve-funded)

2. **Creates new entries**:
   * Posts new expense with updated values
   * Creates new bank charge (if amount provided)
   * Creates new reserve release (if reserve-funded)

3. **Maintains audit trail**:
   * Old entries remain visible as REVERSED
   * New entries show as POSTED
   * Complete history preserved

**Example:**

```
Original Expense:
- Title: "Office Supplies"
- Amount: 50,000 RWF
- Date: 2026-06-01

Edit to:
- Title: "Office Supplies - Printer Ink"
- Amount: 55,000 RWF
- Date: 2026-06-01

Result:
- Old entry: REVERSED (Dr CASH 50,000 / Cr OPERATING_EXPENSE 50,000)
- New entry: POSTED (Dr OPERATING_EXPENSE 55,000 / Cr CASH 55,000)
- Net effect: Additional 5,000 RWF expense
```

### Constraints on Editing

**Cannot edit if**:

* ❌ Expense is in closed accounting period
* ❌ Expense has already been reversed
* ❌ You don't have `expenses:write` permission

**Can edit**:

* ✅ Any POSTED expense in open period
* ✅ All fields including amount and date
* ✅ Can change from standard to reserve-funded (or vice versa)

## Deleting Expenses

You can delete expenses if they were recorded in error.

### How to Delete

<Steps>
  <Step title="Navigate to expense history">
    Expenses → View History
  </Step>

  <Step title="Find the expense">
    Locate the expense to delete
  </Step>

  <Step title="Click Delete">
    Opens confirmation dialog
  </Step>

  <Step title="Confirm deletion">
    System reverses all entries
  </Step>

  <Step title="Verify results">
    * Expense removed from history (or marked as reversed)
    * Bank balance restored
    * Reserve balance restored (if applicable)
  </Step>
</Steps>

### What Happens During Deletion

**Reversal process**:

1. **Reverses main expense**:
   * Creates reversal entry: Dr CASH / Cr OPERATING\_EXPENSE
   * Restores bank account balance

2. **Reverses bank charge** (if exists):
   * Reverses linked bank charge entry
   * Restores additional bank fees

3. **Reverses reserve release** (if reserve-funded):
   * Reverses reserve release entry: Dr RESERVE\_ALLOCATION / Cr CASH
   * Restores reserve balance

4. **Updates metadata**:
   * Marks expense as deleted
   * All journal entries show status: REVERSED
   * Audit trail maintained

**Example:**

```
Delete expense: 100,000 RWF from Emergency Reserve

Original Entries (reversed):
1. Reserve Release: Dr CASH 100,000 / Cr RESERVE 100,000
2. Expense: Dr EXPENSE 100,000 / Cr CASH 100,000

Reversal Entries (created):
1. Reverse Expense: Dr CASH 100,000 / Cr EXPENSE 100,000
2. Reverse Reserve: Dr RESERVE 100,000 / Cr CASH 100,000

Net Effect:
- Reserve balance: Restored (+100,000)
- Bank balance: Unchanged
- Expense removed from reports
```

### Constraints on Deletion

**Cannot delete if**:

* ❌ Expense is in closed accounting period
* ❌ Already reversed/deleted
* ❌ Don't have `expenses:write` permission

**Warning**:

* Deletion may create negative balance if bank account doesn't have sufficient funds
* Use `skipNegativeBalanceCheck` parameter if intentional

## Common Scenarios

### Scenario 1: Monthly Recurring Expenses

For expenses that happen every month (rent, salaries, utilities):

**Best practice:**

<Steps>
  <Step title="Create a checklist">
    List all recurring expenses with amounts and due dates
  </Step>

  <Step title="Record at consistent time">
    E.g., first business day after payment
  </Step>

  <Step title="Use consistent titles">
    Format: "Expense Type - Month Year"
    Examples: "Office Rent - June 2026", "Treasurer Stipend - June 2026"
  </Step>

  <Step title="Set reminders">
    Calendar alerts to record on time
  </Step>
</Steps>

**Example recurring expenses:**

```
Title: "Office Rent - June 2026"
Amount: 150,000 RWF
Date: 2026-06-01
Bank Account: Operations Account
Description: "Monthly office rental at Kimihurura"

Title: "Treasurer Stipend - June 2026"
Amount: 50,000 RWF
Date: 2026-06-30
Bank Account: Operations Account
Description: "Monthly treasurer compensation"
```

### Scenario 2: Recording Reimbursements

If reimbursing a member who paid on behalf of the organization:

<Steps>
  <Step title="Record the actual expense">
    Use the real expense title and date when member paid
  </Step>

  <Step title="Note reimbursement in description">
    Example: "Taxi fare for bank trip (reimbursing Jane Uwase)"
  </Step>

  <Step title="Pay the member separately">
    Via bank transfer, cash, or credit to savings
  </Step>
</Steps>

**Example:**

```
Title: "Transportation - Bank Trip"
Amount: 15,000 RWF
Date: 2026-06-05 (when member paid)
Description: "Taxi fare to BK Bank for deposit (reimbursing Jane Uwase)"
Bank Account: Operations Account

Then separately:
- Transfer 15,000 RWF to Jane's savings OR
- Give Jane 15,000 RWF cash
```

### Scenario 3: Emergency Expense from Reserve

Using emergency fund for urgent, unplanned expense:

<Steps>
  <Step title="Record expense">
    Fill title, amount, date as normal
  </Step>

  <Step title="Select Emergency Reserve">
    Choose "Emergency Fund" in Reserve Allocation field
  </Step>

  <Step title="Add detailed description">
    Explain why emergency fund was used
  </Step>

  <Step title="Submit">
    System releases from reserve and records expense
  </Step>
</Steps>

**Example:**

```
Title: "Office Generator Repair - Emergency"
Amount: 300,000 RWF
Date: 2026-06-10
Reserve Allocation: Emergency Fund
Description: "Generator broke down during meeting, required immediate repair to restore power. Invoice #GEN-456 from Repair Co."
Documents: [Upload invoice photo]

Result:
- Emergency Fund: -300,000 RWF
- Expense recorded: 300,000 RWF
- Bank balance: Unchanged
```

### Scenario 4: Large Payment with Bank Charge

Significant payment with wire transfer fee:

```
Title: "Annual Audit Fee Payment"
Amount: 2,000,000 RWF
Date: 2026-06-15
Bank Account: Operations Account
Bank Charge Amount: 25,000 RWF
Description: "Annual audit services from ABC Auditors, fiscal year 2025-2026"
Documents: [Upload invoice]

Result:
- Main expense: 2,000,000 RWF (EXPENSE_PAYMENT)
- Bank charge: 25,000 RWF (BANK_CHARGE, linked)
- Total bank deduction: 2,025,000 RWF
- Both entries appear in expense history
```

### Scenario 5: Correcting an Error

Recorded wrong amount, need to fix:

<Steps>
  <Step title="Find the expense">
    Locate in expense history
  </Step>

  <Step title="Click Edit">
    Opens edit form
  </Step>

  <Step title="Update amount">
    Change from wrong amount to correct amount
  </Step>

  <Step title="Submit">
    System reverses old entry and creates new one
  </Step>
</Steps>

**Example:**

```
Original (wrong):
- Amount: 50,000 RWF (typo, should be 500,000)

Edit to:
- Amount: 500,000 RWF

Result:
- Old entry reversed: Dr CASH 50,000 / Cr EXPENSE 50,000
- New entry posted: Dr EXPENSE 500,000 / Cr CASH 500,000
- Net bank change: Additional -450,000 RWF
- Audit trail shows correction
```

## Validation and Error Messages

### Common Errors

| Error Message                  | Cause                         | Solution                                  |
| ------------------------------ | ----------------------------- | ----------------------------------------- |
| "Amount must be at least 0.01" | Amount is 0 or negative       | Enter positive amount                     |
| "Title cannot be empty"        | No title provided             | Add descriptive title                     |
| "Invalid date format"          | Date not in ISO format        | Use YYYY-MM-DD format                     |
| "Bank account not found"       | Invalid bank account ID       | Select valid active account               |
| "Insufficient reserve balance" | Reserve doesn't have enough   | Choose different reserve or reduce amount |
| "Cannot modify closed period"  | Expense date in closed period | Change date or open period                |
| "Idempotency key required"     | Missing header                | System should auto-generate               |

### Validation Rules

**Amount**:

* ✅ Must be >= 0.01
* ✅ Must match currency decimal places
* ❌ Cannot be 0 or negative

**Title**:

* ✅ Must be non-empty string
* ❌ Cannot be blank spaces

**Date**:

* ✅ Must be valid ISO date (YYYY-MM-DD)
* ✅ Can be in the past
* ❌ Cannot be in closed period
* ❌ Cannot be future date (some implementations)

**Bank Account** (if provided):

* ✅ Must exist in organization
* ✅ Must be active
* Falls back to default if omitted

**Reserve Allocation** (if provided):

* ✅ Must exist and be active
* ✅ Must have sufficient balance
* ✅ Balance >= (expense amount + bank charge amount)

## Best Practices

<Note>
  **Expense recording tips:**

  * Record expenses within 1 week of occurrence (fresher memory)
  * Keep physical receipts in organized file or envelope
  * Take photos of receipts for digital backup (upload as documents)
  * Use clear, consistent title format: "Category - Description - Period"
  * Include detailed descriptions for amounts over 100,000 RWF
  * Require approval workflow for large expenses (implement externally)
  * Review expense trends monthly to catch unusual spending patterns
  * Separate personal expenses from organizational expenses (never mix)
  * Use reserve-funded expenses for emergency or planned reserve spending
  * Always include bank charges when applicable (don't hide fees)
  * Reconcile bank statements monthly to catch missing expenses
  * Close accounting periods regularly to lock historical data
</Note>

## Permissions Required

| Action         | Permission       | Scope |
| -------------- | ---------------- | ----- |
| Record expense | `expenses:write` | ANY   |
| Edit expense   | `expenses:write` | ANY   |
| Delete expense | `expenses:write` | ANY   |
| View expenses  | `expenses:read`  | ANY   |

<Note>
  **Typical access**: Accountants and Administrators have `expenses:write`. Regular members may have `expenses:read` (view only) or no access.
</Note>

## Related Topics

<CardGroup cols={2}>
  <Card title="Expenses Overview" icon="receipt" href="/tontines/expenses/overview">
    Understand expense types and integration
  </Card>

  <Card title="Expense Categories" icon="tags" href="/tontines/expenses/expense-categories">
    Organize spending by category
  </Card>

  <Card title="View Expense History" icon="list" href="/tontines/expenses/viewing-expense-history">
    Browse and analyze past spending
  </Card>

  <Card title="Bank Accounts" icon="building-columns" href="/tontines/bank-accounts/overview">
    Learn about bank account tracking
  </Card>

  <Card title="Reserves" icon="piggy-bank" href="/tontines/reserves/overview">
    Understand reserve allocations
  </Card>

  <Card title="Profit & Loss Report" icon="chart-line" href="/tontines/reports/profit-and-loss">
    See expense impact on profitability
  </Card>
</CardGroup>