Asset Disposal - Agatabo

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.

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.

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

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)

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.

How Asset Deletion Works

What Happens During Deletion

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

Removes asset record from the AssetMeta table
Reverses original journal entry by creating a REVERSAL entry with opposite debits/credits
Reverses linked bank charges (if the asset had associated bank fees)
Updates Balance Sheet - Total Fixed Assets value decreases by asset amount
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

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.

Step-by-Step: Deleting an Asset

Step 1: Navigate to Asset

Open Fixed Assets section

Click Fixed Assets in the left sidebar

Find the asset

Use search or filters to locate the asset to delete

Click on asset row

Opens asset details view

Step 2: Delete the Asset

Click Delete or Remove Asset

Usually found in asset actions menu (three dots) or at bottom of details page

Confirm deletion

Dialog appears warning that this action is permanent and will reverse the journal entry

Click Confirm or Delete

Asset is removed from records and reversal entry is created

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:

Navigate to asset

Find and open the asset details

Delete asset

Click Delete and confirm

System reverses entry

Original acquisition entry is reversed automatically

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:

Navigate to Bank Accounts

Go to the bank account that received the sale proceeds

Record deposit or manual entry

Add the sale proceeds to the bank account

Note in description

“Proceeds from sale of [asset name] - sold to [buyer] on [date]”

Learn about recording bank deposits →

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 →

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

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

This is acceptable for organizations without formal auditing requirements or complex financial reporting needs.

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

File incident report

Document theft or loss with internal report and police report (if applicable)

Delete asset in Agatabo

Remove from records so inventory is accurate

Document externally

Keep police report, insurance claim, and incident notes

Review insurance

Submit insurance claim if asset was covered

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

Get donation acknowledgement

Request signed letter from recipient acknowledging donation and value

Delete asset

Remove from Agatabo records

Save documentation

Keep donation letter for audit trail

Notify members (optional)

Announce donation at member meeting for transparency

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:

Delete old asset

Remove old equipment from records

Record new asset

Add new equipment at net purchase price (cash paid after trade-in credit)

Note relationship

Description: “Replaced [old asset name], trade-in value [amount]”

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

Verify asset is truly unusable

Cannot be repaired or sold for salvage

Take photo before disposal

Document condition for audit trail

Delete asset

Remove from Agatabo records

Document reason externally

Keep notes: “Disposed - no longer functional, discarded on [date]”

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):

Create disposal list

List all assets to be deleted with reasons

Get approval

For high-value disposals, get committee or member approval

Delete one by one

Remove each asset individually in Agatabo (no bulk delete feature)

Document in meeting minutes

Record bulk disposal decision in organizational records

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

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

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

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 →

“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

Typical roles: Administrators and Accountants have assets:write. Regular members may have assets:read (view only) or no access.

Audit and Compliance

For organizations with formal auditing requirements:

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)

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

Validate request: Check idempotency key, organization ID, permissions
Fetch asset: Retrieve asset record and journal entry
Delete asset record: Remove from AssetMeta table
Reverse acquisition entry: Create REVERSAL journal entry with opposite debits/credits
Reverse bank charges: If asset had linked bank charges, reverse those too
Check balances: Ensure no negative balances (unless skipped)
Log audit trail: Record who, when, what (asset title and details)
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

Fixed Assets Overview

Understand asset types and features

Adding Fixed Assets

Record new assets

Manual Journal Entries

Record gains/losses manually

Balance Sheet

View asset totals after disposal

Period Closing

Understand period constraints

Bank Accounts

Record sale proceeds

​Overview

​When to Remove an Asset

​Before You Begin

​How Asset Deletion Works

​What Happens During Deletion

​Journal Entry Reversal Process

​Bank Charge Reversal

​Step-by-Step: Deleting an Asset

​Step 1: Navigate to Asset

​Step 2: Delete the Asset

​What You Can Do

​Handling Asset Sales

​Step 1: Delete the Asset

​Step 2: Record Cash Receipt (Sale Proceeds)

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

​Complete Example: Selling a Laptop

​Common Scenarios

​Disposing of Stolen or Lost Asset

​Donating Asset to Another Organization

​Trade-In for New Equipment

​Discarding Obsolete or Broken Equipment

​Bulk Asset Disposal

​Validation and Constraints

​What You Cannot Do

​Idempotency

​Best Practices

​Troubleshooting

​”Cannot delete asset - period closed”

​“x-idempotency-key header is required”

​“Insufficient permissions”

​”Asset not found”

​”Cash balance would become negative”

​Permissions Required

​Audit and Compliance

​Technical Details

​API Endpoint

​What Happens Internally

​Journal Entry Kind

​Related Topics

Fixed Assets Overview

Adding Fixed Assets

Manual Journal Entries

Balance Sheet

Period Closing

Bank Accounts

Overview

When to Remove an Asset

Before You Begin

How Asset Deletion Works

What Happens During Deletion

Journal Entry Reversal Process

Bank Charge Reversal

Step-by-Step: Deleting an Asset

Step 1: Navigate to Asset

Step 2: Delete the Asset

What You Can Do

Handling Asset Sales

Step 1: Delete the Asset

Step 2: Record Cash Receipt (Sale Proceeds)

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

Complete Example: Selling a Laptop

Common Scenarios

Disposing of Stolen or Lost Asset

Donating Asset to Another Organization

Trade-In for New Equipment

Discarding Obsolete or Broken Equipment

Bulk Asset Disposal

Validation and Constraints

What You Cannot Do

Idempotency

Best Practices

Troubleshooting

”Cannot delete asset - period closed”

“x-idempotency-key header is required”

“Insufficient permissions”

”Asset not found”

”Cash balance would become negative”

Permissions Required

Audit and Compliance

Technical Details

API Endpoint

What Happens Internally

Journal Entry Kind

Related Topics