> ## 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.

# Asset Disposal

> Remove fixed assets from records by deleting and reversing acquisition entries

## Overview

**Asset disposal** in Agatabo is the process of removing a fixed asset from your records when it is sold, donated, discarded, or no longer in use. The system uses a **journal reversal approach** - deleting an asset creates a REVERSAL journal entry that undoes the original acquisition entry.

<Warning>
  **Important Limitation**: Agatabo does NOT have a dedicated asset disposal feature. Instead, asset "disposal" is achieved by **deleting** the asset, which reverses the original journal entry. There is no support for:

  * Recording sale proceeds or sale price
  * Calculating gain or loss on disposal
  * Tracking disposal reasons (sold vs. donated vs. scrapped)
  * Specifying buyer or recipient information
  * Recording disposal dates (only deletion timestamp)
  * Partial asset disposal

  For full disposal accounting with gain/loss tracking, you must record additional entries manually.
</Warning>

## When to Remove an Asset

Common scenarios for deleting an asset:

* **Sold**: Asset sold to buyer for cash
* **Donated**: Asset given away to another organization or individual
* **Discarded**: Asset broken, obsolete, or no longer functional and thrown away
* **Stolen/Lost**: Asset stolen or lost
* **Trade-in**: Asset traded for new equipment (delete old, record new)
* **Transferred**: Asset moved to related organization

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `assets:write` permission
  * You have verified the asset is truly no longer in the organization's possession
  * You have documentation of disposal (sales receipt, donation letter, or incident report)
  * Accounting period where asset was acquired is **not closed** (otherwise deletion will be rejected)
</Note>

<Warning>
  **Important**: Asset deletion is **permanent** and reverses the original journal entry. This reduces your Fixed Assets total on the Balance Sheet. Only delete assets that are truly gone - do not delete assets that are still in use or temporarily unavailable.
</Warning>

## How Asset Deletion Works

### What Happens During Deletion

When you delete an asset via `DELETE /assets/:id`, Agatabo:

1. **Removes asset record** from the AssetMeta table
2. **Reverses original journal entry** by creating a REVERSAL entry with opposite debits/credits
3. **Reverses linked bank charges** (if the asset had associated bank fees)
4. **Updates Balance Sheet** - Total Fixed Assets value decreases by asset amount
5. **Logs audit trail** - Records who deleted the asset, when, and the asset details

### Journal Entry Reversal Process

The deletion process creates **REVERSAL journal entries** (not ASSET\_DISPOSAL entries):

**Cash Purchase Asset**:

```
Original Entry (ASSET_CASH_PURCHASE):
Date: 2026-01-15
Status: POSTED
Dr FIXED_ASSET              850,000
   Cr CASH (Bank Account)   850,000

Reversal Entry (REVERSAL):
Date: 2026-06-11 (deletion date)
Status: REVERSAL
Dr CASH (Bank Account)      850,000
   Cr FIXED_ASSET           850,000

Net Effect:
- Fixed Assets: -850,000 (removed from balance sheet)
- Cash: +850,000 (reversal debit, but NO actual cash received!)
```

**Collateral Asset**:

```
Original Entry (ASSET_COLLATERAL):
Dr FIXED_ASSET                      1,200,000
   Cr BAD_DEBT_RECOVERY_INCOME        800,000
   Cr BORROWER_SURPLUS_LIABILITY      400,000

Reversal Entry (REVERSAL):
Dr BAD_DEBT_RECOVERY_INCOME           800,000
Dr BORROWER_SURPLUS_LIABILITY         400,000
   Cr FIXED_ASSET                   1,200,000

Net Effect:
- Fixed Assets: -1,200,000 (removed)
- Bad Debt Recovery: -800,000 (reversed)
- Borrower Surplus Liability: -400,000 (reversed)
```

**Gift Asset**:

```
Original Entry (ASSET_GIFT):
Dr FIXED_ASSET          150,000
   Cr OTHER_EQUITY      150,000

Reversal Entry (REVERSAL):
Dr OTHER_EQUITY         150,000
   Cr FIXED_ASSET       150,000

Net Effect:
- Fixed Assets: -150,000 (removed)
- Other Equity: -150,000 (reversed)
```

### Bank Charge Reversal

If the original asset had linked bank charges, those are also reversed:

```
Original Bank Charge (BANK_CHARGE):
Dr BANK_CHARGE_EXPENSE  5,000
   Cr CASH              5,000

Reversal Entry (REVERSAL):
Dr CASH                 5,000
   Cr BANK_CHARGE_EXPENSE  5,000
```

<Note>
  **Critical Understanding**: The reversal debits to CASH do NOT represent actual cash receipts. They are accounting reversals that undo the original entry. If you actually sold the asset for cash, you must record the cash receipt separately.
</Note>

## Step-by-Step: Deleting an Asset

### Step 1: Navigate to Asset

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

  <Step title="Find the asset">
    Use search or filters to locate the asset to delete
  </Step>

  <Step title="Click on asset row">
    Opens asset details view
  </Step>
</Steps>

### Step 2: Delete the Asset

<Steps>
  <Step title="Click Delete or Remove Asset">
    Usually found in asset actions menu (three dots) or at bottom of details page
  </Step>

  <Step title="Confirm deletion">
    Dialog appears warning that this action is permanent and will reverse the journal entry
  </Step>

  <Step title="Click Confirm or Delete">
    Asset is removed from records and reversal entry is created
  </Step>
</Steps>

### What You Can Do

| Action                        | Supported | How                                   |
| ----------------------------- | --------- | ------------------------------------- |
| **Delete asset**              | ✅ YES     | DELETE /assets/:id endpoint           |
| **Reverse acquisition entry** | ✅ YES     | Automatic on deletion                 |
| **Record sale proceeds**      | ❌ NO      | Must record manually via bank deposit |
| **Calculate gain/loss**       | ❌ NO      | Must calculate and record manually    |
| **Specify disposal reason**   | ❌ NO      | Hardcoded as "Asset deletion"         |
| **Track buyer/recipient**     | ❌ NO      | Document externally                   |
| **Partial disposal**          | ❌ NO      | All or nothing deletion               |

***

## Handling Asset Sales

If you sold an asset for cash, you must record the transaction in multiple steps:

### Step 1: Delete the Asset

Delete the asset from Agatabo to remove it from the Fixed Assets balance:

<Steps>
  <Step title="Navigate to asset">
    Find and open the asset details
  </Step>

  <Step title="Delete asset">
    Click Delete and confirm
  </Step>

  <Step title="System reverses entry">
    Original acquisition entry is reversed automatically
  </Step>
</Steps>

**Result**: Asset removed from Fixed Assets, original entry reversed

***

### Step 2: Record Cash Receipt (Sale Proceeds)

Record the actual cash you received from the sale:

<Steps>
  <Step title="Navigate to Bank Accounts">
    Go to the bank account that received the sale proceeds
  </Step>

  <Step title="Record deposit or manual entry">
    Add the sale proceeds to the bank account
  </Step>

  <Step title="Note in description">
    "Proceeds from sale of \[asset name] - sold to \[buyer] on \[date]"
  </Step>
</Steps>

[Learn about recording bank deposits →](/tontines/bank-accounts/recording-transactions)

***

### Step 3: Calculate and Record Gain or Loss (Optional)

If tracking gain/loss for financial reporting:

**Gain Calculation**:

```
Sale Price - Original Book Value = Gain (or Loss)

Example 1 - Gain:
Laptop book value: 850,000 RWF
Sale price: 300,000 RWF
Loss: 850,000 - 300,000 = 550,000 RWF

Example 2 - Gain:
Desk book value: 150,000 RWF
Sale price: 200,000 RWF
Gain: 200,000 - 150,000 = 50,000 RWF
```

**How to record**:

* Create manual journal entry for the gain or loss
* No dedicated gain/loss accounts exist, so use general income/expense

[Learn about manual journal entries →](/tontines/general-ledger/manual-journal-entries)

<Note>
  **Simplified approach for small organizations**: Many small tontines do not track gains/losses separately. They simply:

  1. Delete the asset (removes from Fixed Assets via reversal)
  2. Record cash received from sale (increases Cash)
  3. Let the net difference affect equity

  This is acceptable for organizations without formal auditing requirements or complex financial reporting needs.
</Note>

***

### Complete Example: Selling a Laptop

**Asset Details**:

* Title: "HP Laptop - Serial ABC123"
* Book Value: 850,000 RWF (original purchase price)
* Sale Price: 300,000 RWF

**Step 1: Delete the asset**

```
System creates reversal:
Dr CASH (Bank Account)      850,000
   Cr FIXED_ASSET           850,000

Note: This is NOT actual cash - just reversal!
```

**Step 2: Record cash receipt**

```
Record bank deposit:
Amount: 300,000 RWF
Description: "Proceeds from sale of HP Laptop to John Doe"

Or via manual journal:
Dr CASH (Bank Account)      300,000
   Cr OTHER_INCOME          300,000
```

**Step 3: Net effect**

```
Fixed Assets: -850,000 (removed)
Cash: +300,000 (actual proceeds received)
Loss on sale: 550,000 (difference, absorbed in equity)
```

If you want to explicitly record the loss:

```
Manual journal entry:
Dr OPERATING_EXPENSE (Asset Loss)  550,000
   Cr OTHER_EQUITY                 550,000
```

***

## Common Scenarios

### Disposing of Stolen or Lost Asset

<Steps>
  <Step title="File incident report">
    Document theft or loss with internal report and police report (if applicable)
  </Step>

  <Step title="Delete asset in Agatabo">
    Remove from records so inventory is accurate
  </Step>

  <Step title="Document externally">
    Keep police report, insurance claim, and incident notes
  </Step>

  <Step title="Review insurance">
    Submit insurance claim if asset was covered
  </Step>
</Steps>

**Accounting treatment**:

* Deletion reverses the asset (reduces Fixed Assets)
* No cash received (theft/loss)
* Loss absorbed in equity unless manually recorded

***

### Donating Asset to Another Organization

<Steps>
  <Step title="Get donation acknowledgement">
    Request signed letter from recipient acknowledging donation and value
  </Step>

  <Step title="Delete asset">
    Remove from Agatabo records
  </Step>

  <Step title="Save documentation">
    Keep donation letter for audit trail
  </Step>

  <Step title="Notify members (optional)">
    Announce donation at member meeting for transparency
  </Step>
</Steps>

**Accounting treatment**:

* Deletion reverses the asset (reduces Fixed Assets)
* No cash received (donation)
* Value reduction absorbed in equity

***

### Trade-In for New Equipment

When trading old asset for new:

<Steps>
  <Step title="Delete old asset">
    Remove old equipment from records
  </Step>

  <Step title="Record new asset">
    Add new equipment at **net purchase price** (cash paid after trade-in credit)
  </Step>

  <Step title="Note relationship">
    Description: "Replaced \[old asset name], trade-in value \[amount]"
  </Step>
</Steps>

**Example**:

```
Trade-in scenario:
Old laptop book value: 850,000 RWF
New laptop price: 1,200,000 RWF
Trade-in credit: 200,000 RWF
Cash paid: 1,000,000 RWF

Step 1: Delete old laptop
Dr CASH                     850,000  (reversal, not real)
   Cr FIXED_ASSET           850,000

Step 2: Record new laptop
Dr FIXED_ASSET            1,000,000  (actual cash paid)
   Cr CASH                1,000,000

Net effect:
- Fixed Assets: +150,000 (1,000,000 new - 850,000 old)
- Cash: -1,000,000 (actual payment)
```

***

### Discarding Obsolete or Broken Equipment

<Steps>
  <Step title="Verify asset is truly unusable">
    Cannot be repaired or sold for salvage
  </Step>

  <Step title="Take photo before disposal">
    Document condition for audit trail
  </Step>

  <Step title="Delete asset">
    Remove from Agatabo records
  </Step>

  <Step title="Document reason externally">
    Keep notes: "Disposed - no longer functional, discarded on \[date]"
  </Step>
</Steps>

**Accounting treatment**:

* Deletion reverses the asset (reduces Fixed Assets)
* No cash received (discarded)
* Loss absorbed in equity

***

## Bulk Asset Disposal

If deleting multiple assets at once (e.g., office renovation, equipment upgrade):

<Steps>
  <Step title="Create disposal list">
    List all assets to be deleted with reasons
  </Step>

  <Step title="Get approval">
    For high-value disposals, get committee or member approval
  </Step>

  <Step title="Delete one by one">
    Remove each asset individually in Agatabo (no bulk delete feature)
  </Step>

  <Step title="Document in meeting minutes">
    Record bulk disposal decision in organizational records
  </Step>
</Steps>

<Note>
  **No bulk deletion**: Agatabo does not have a bulk asset deletion feature. Each asset must be deleted individually via the DELETE endpoint.
</Note>

***

## Validation and Constraints

### What You Cannot Do

**Cannot delete if**:

* ❌ Asset was recorded in a **closed accounting period**
* ❌ You lack `assets:write` permission
* ❌ Asset ID is invalid or doesn't belong to your organization

**Cannot track**:

* ❌ Disposal reason (sold vs. donated vs. scrapped) - hardcoded as "Asset deletion"
* ❌ Sale proceeds or sale price
* ❌ Buyer or recipient information
* ❌ Gain or loss on disposal (must calculate manually)
* ❌ Disposal date separate from deletion timestamp
* ❌ Accumulated depreciation (not tracked in Agatabo)

### Idempotency

Asset deletion requires `x-idempotency-key` header:

* Prevents duplicate deletions from retries
* Safe for network failures and refreshes
* Duplicate requests with same key succeed without error

***

## Best Practices

<Note>
  **Asset disposal tips:**

  **Before Disposal:**

  * Verify asset is truly gone (not just out for repair or temporarily unavailable)
  * Take photos of asset condition before disposal
  * Get committee approval for high-value assets (> 500,000 RWF)
  * Ensure all supporting documentation is ready

  **Documentation:**

  * Keep sales receipts, donation letters, or incident reports
  * Record disposal reason and details in external log (Agatabo doesn't track this)
  * Note disposal date, buyer/recipient, and sale proceeds externally
  * Update insurance policies when high-value assets are disposed

  **Accounting:**

  * For asset sales, always record the cash receipt separately
  * Consider recording gain/loss manually for formal financial reporting
  * Review and reconcile asset list annually
  * Conduct physical inventory count before and after bulk disposals

  **Audit Trail:**

  * Document committee approval for significant disposals
  * Keep external disposal log with reasons and supporting docs
  * Maintain audit trail of who authorized and who executed disposal
  * Keep disposal documentation for tax and audit purposes
</Note>

***

## Troubleshooting

### "Cannot delete asset - period closed"

**Cause**: Asset was recorded in a closed accounting period

**Solution**:

* Accounting periods are locked to prevent changes to past transactions
* Contact your accountant or administrator to re-open the period if deletion is necessary
* Alternatively, wait until current period closes and adjust in next period

[Learn about period closing →](/tontines/advanced/period-closing)

***

### "x-idempotency-key header is required"

**Cause**: Frontend didn't send idempotency key with DELETE request

**Solution**:

* This is a frontend/API client issue
* Ensure the DELETE request includes `x-idempotency-key` header
* Use unique key per deletion attempt (e.g., UUID)

***

### "Insufficient permissions"

**Cause**: You lack `assets:write` permission

**Solution**:

* Contact an administrator to grant `assets:write` permission
* Only users with this permission can delete assets
* Check your role and permission assignments

***

### "Asset not found"

**Cause**: Asset doesn't exist or already deleted

**Solution**:

* Verify asset ID is correct
* Check if asset was already deleted (check audit logs)
* Ensure you're using the correct organization ID

***

### "Cash balance would become negative"

**Cause**: Reversal would create negative cash balance (rare for deletions)

**Solution**:

* This usually indicates accounting inconsistency
* Use `skipNegativeBalanceCheck=true` query parameter (requires special permission)
* Investigate why reversal would cause negative balance

***

## Permissions Required

| Action             | Permission                          | Scope |
| ------------------ | ----------------------------------- | ----- |
| View assets        | `assets:read`                       | ANY   |
| Delete asset       | `assets:write`                      | ANY   |
| Skip balance check | `assets:write` + special permission | ANY   |

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

***

## Audit and Compliance

For organizations with formal auditing requirements:

<Note>
  **Disposal documentation checklist:**

  * ✅ Reason for disposal (sold, donated, discarded, stolen)
  * ✅ Disposal date and authorization (document externally - not in Agatabo)
  * ✅ Sale proceeds with receipt (if applicable)
  * ✅ Donation acknowledgement letter (if donated)
  * ✅ Police report (if stolen)
  * ✅ Photos of asset condition before disposal
  * ✅ Committee or board approval for high-value disposals
  * ✅ Updated insurance policy (removing disposed assets)
  * ✅ Gain/loss calculation (if required for financial reporting)
</Note>

**Agatabo limitations for audits**:

* No disposal reason tracking (hardcoded as "Asset deletion")
* No sale proceeds field (must document externally)
* No gain/loss calculation (must calculate manually)
* No buyer/recipient information (must document externally)
* ASSET\_DISPOSAL journal entry kind exists but is never used (only REVERSAL entries created)

***

## Technical Details

### API Endpoint

```
DELETE /assets/:id

Headers:
  x-organization-id: <organization_id>
  x-idempotency-key: <unique_key>

Query Parameters:
  skipNegativeBalanceCheck: true | false (optional)

Response:
{
  "message": "Asset deleted successfully",
  "data": {
    "id": "<asset_id>"
  }
}
```

### What Happens Internally

1. **Validate request**: Check idempotency key, organization ID, permissions
2. **Fetch asset**: Retrieve asset record and journal entry
3. **Delete asset record**: Remove from AssetMeta table
4. **Reverse acquisition entry**: Create REVERSAL journal entry with opposite debits/credits
5. **Reverse bank charges**: If asset had linked bank charges, reverse those too
6. **Check balances**: Ensure no negative balances (unless skipped)
7. **Log audit trail**: Record who, when, what (asset title and details)
8. **Return success**: Confirm deletion and reversal

### Journal Entry Kind

**ASSET\_DISPOSAL exists but is NOT used**:

* The `journal_entry_kind` enum includes `ASSET_DISPOSAL`
* This kind is mapped to display label "Asset Disposal"
* However, it is **never instantiated** in the codebase
* Asset deletion creates **REVERSAL** entries, not ASSET\_DISPOSAL entries
* This suggests disposal functionality was planned but not fully implemented

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Fixed Assets Overview" icon="building" href="/tontines/fixed-assets/overview">
    Understand asset types and features
  </Card>

  <Card title="Adding Fixed Assets" icon="plus" href="/tontines/fixed-assets/adding-fixed-assets">
    Record new assets
  </Card>

  <Card title="Manual Journal Entries" icon="pen" href="/tontines/general-ledger/manual-journal-entries">
    Record gains/losses manually
  </Card>

  <Card title="Balance Sheet" icon="scale-balanced" href="/tontines/reports/balance-sheet">
    View asset totals after disposal
  </Card>

  <Card title="Period Closing" icon="lock" href="/tontines/advanced/period-closing">
    Understand period constraints
  </Card>

  <Card title="Bank Accounts" icon="building-columns" href="/tontines/bank-accounts/overview">
    Record sale proceeds
  </Card>
</CardGroup>