Overview
Recording fixed assets ensures all major organizational property is tracked in Agatabo. This creates journal entries, updates bank balances (for cash purchases), and maintains accurate financial records.Before You Begin
Prerequisites:
- You have
assets:writepermission - You have documentation for the asset (receipt, appraisal, or donation letter)
- You know the acquisition value or purchase price
- For cash purchases: You know which bank account paid
- For collateral seizure: The loan has been marked as DEFAULTED with bad debt written off
- For gifts: You have fair market valuation (may require appraisal)
Acquisition Types Supported
Agatabo supports three ways to acquire fixed assets:| Type | When to Use | Bank Impact | Journal Entry |
|---|---|---|---|
| Cash Purchase | Buying asset with organization funds | Decreases bank balance | Dr FIXED_ASSET / Cr CASH |
| Collateral | Seizing pledged property from defaulted loan | No bank impact | Dr FIXED_ASSET / Cr BAD_DEBT_RECOVERY + BORROWER_SURPLUS_LIABILITY |
| Gift | Receiving donated asset | No bank impact | Dr FIXED_ASSET / Cr OTHER_EQUITY |
Recording a Cash Purchase
When to Use
Use Cash Purchase when buying an asset using organization funds from a bank account.Required Information
| Field | Description | Example |
|---|---|---|
| Title | Name/description of asset | ”HP ProBook 450 G8 Laptop - Serial ABC123” |
| Amount | Purchase price (min 0.01) | 850,000 RWF |
| Acquisition Date | Purchase date (ISO format) | 2026-06-10 |
| Bank Account | Which account paid (optional - defaults to organization’s default account) | “BK Current Account” |
Optional Information
| Field | Description | Example |
|---|---|---|
| Description | Additional details (vendor, warranty, location) | “Purchased from Tech Store Kigali, 3-year warranty expires 2029-06-10, assigned to Treasurer” |
| Bank Charge Amount | Wire fees, processing charges (min 0) | 5,000 RWF |
| Documents | Receipts, invoices, photos, warranty cards | PDF receipts, product photos |
| Notify Members | Send email notification to all members | true/false |
What Happens
Journal Entry Created:- Balance decreases by amount + bankChargeAmount
- Transaction appears in bank account history
- Cannot create if insufficient balance (unless skipNegativeBalanceCheck = true)
Step-by-Step
Enter asset details
- Title: “HP ProBook 450 G8 Laptop - Serial ABC123456”
- Amount: 850,000
- Acquisition Date: 2026-06-10
- Description: “Purchased from Tech Store, 3-year warranty expires 2029-06-10”
Add bank charge (optional)
If you paid wire fees or processing charges, enter the amount (e.g., 5,000 RWF)
Recording Collateral Seizure
When to Use
Use Collateral when seizing pledged property from a borrower who defaulted on their loan.Prerequisites
First default the loan, then record the collateral asset. Learn about loan defaulting →Required Information
| Field | Description | Example |
|---|---|---|
| Title | Description of seized property | ”Motorcycle - Yamaha FZ 150” |
| Amount | Appraised collateral value (min 0.01) | 1,200,000 RWF |
| Acquisition Date | Seizure date (ISO format) | 2026-06-10 |
| Loan ID | Which defaulted loan to recover from | ”LA-00123” (John Doe - Business Loan) |
Optional Information
| Field | Description | Example |
|---|---|---|
| Description | Seizure details, appraisal info, legal notes | ”Seized collateral from John Doe’s defaulted business loan. Professional appraisal by ABC Valuers on 2026-06-08.” |
| Documents | Appraisal report, seizure authorization, photos | Appraisal PDF, vehicle photos, loan agreement |
Bank charges NOT allowed: You cannot add bank charges to collateral assets (only cash purchases support this).
What Happens
Bad Debt Recovery Calculation:Examples
Example 1: Collateral equals bad debtStep-by-Step
Default the loan first
Before recording collateral, ensure the loan is marked as DEFAULTED with bad debt written off
Enter asset details
- Title: “Motorcycle - Yamaha FZ 150”
- Amount: 1,200,000 (appraised value)
- Acquisition Date: 2026-06-10 (seizure date)
- Description: “Seized collateral from John Doe’s defaulted business loan LA-00123”
Select defaulted loan
Choose the defaulted loan from dropdown (only shows loans with bad debt written off)
Troubleshooting
“No defaulted loans available”:- Loan must have status DEFAULTED
- Loan must have bad debt written off (badDebtWrittenOff > 0)
- Default the loan first before recording collateral
- System throws BadRequestException if selected loan has badDebtWrittenOff ≤ 0
- Ensure loan defaulting process wrote off uncollectible amount
Recording a Gift (Donation)
When to Use
Use Gift when receiving an asset as a donation from a member, external party, or organization.Required Information
| Field | Description | Example |
|---|---|---|
| Title | Description of donated asset | ”Office Desk and Chairs Set” |
| Amount | Fair market value (min 0.01) | 150,000 RWF |
| Acquisition Date | Receipt date (ISO format) | 2026-06-10 |
Optional Information
| Field | Description | Example |
|---|---|---|
| Description | Donor information, valuation method | ”Donated by former treasurer Marie Uwase - 1 executive desk, 4 office chairs. Fair market value per ABC Furniture price list.” |
| Documents | Donation letter, appraisal, photos | Signed donation letter, asset photos, valuation certificate |
| Notify Members | Send email notification to all members | true/false |
Bank charges NOT allowed: You cannot add bank charges to gift assets (only cash purchases support this).
What Happens
Journal Entry Created:Valuation Guidelines
Fair Market Value is the price the asset would sell for in an open market:Small donations (< 100,000 RWF):
- Use comparable prices from local vendors
- Example: Check current furniture store prices for similar items
- Get quotes from 2-3 vendors for similar items
- Use average as fair market value
- Document valuation method in description
- Require professional appraisal from certified appraiser
- Request written appraisal report
- Upload appraisal as supporting document
Step-by-Step
Enter asset details
- Title: “Office Desk and Chairs Set”
- Amount: 150,000 (fair market value)
- Acquisition Date: 2026-06-10
- Description: “Donated by Marie Uwase - 1 desk, 4 chairs. Valued per ABC Furniture price list.”
Upload documents (optional)
Attach donation letter, asset photos, valuation certificate or appraisal
Best Practices for Donations
Gift recording tips:Documentation:
- Always request written donation letter from donor
- Letter should state: donor name, asset description, estimated value, donation date
- For large donations, get professional appraisal
- Be conservative - don’t overvalue donations
- Use current market prices, not original purchase price
- Document valuation method in description field
- Thank donor in writing
- Provide donation receipt if requested
- Consider special mention at member meeting for significant donations
- Enable member notifications for transparency
- Announce large donations at member assemblies
- Include in annual report
Common Fields (All Types)
Title
Purpose: Name or description of the asset Best practices:- Include asset type, brand, model, and identifier
- Format: “Type - Brand Model - Serial/ID”
- Examples:
- “Laptop - HP ProBook 450 G8 - Serial ABC123456”
- “Vehicle - Toyota Corolla - Plate RAB 123A”
- “Furniture - Executive Desk Set”
- “Equipment - Industrial Printer Canon MX920”
- Required (non-empty string)
- No maximum length specified
Amount
Purpose: Acquisition value, purchase price, or fair market value Rules:- Minimum: 0.01
- Must match organization’s currency decimal places (e.g., 2 decimals for RWF)
- Cannot be negative or zero
- Do not include currency symbols or commas (enter as number)
- Cash purchase: Actual purchase price (850,000)
- Collateral: Professional appraisal value (1,200,000)
- Gift: Fair market value (150,000)
Acquisition Date
Purpose: When the asset was acquired Format: ISO date string (YYYY-MM-DD) Rules:- Required
- Can be historical (past dates allowed)
- Cannot be in closed accounting period
- Cannot exceed current date
- 2026-06-10
- 2026-01-15
Description (Optional)
Purpose: Additional details about the asset What to include:- Vendor/supplier information
- Serial numbers, model details
- Warranty information and expiration
- Physical location or assignment
- Condition notes
- Valuation method (for gifts)
- Legal notes (for collateral)
Documents (Optional)
Purpose: Supporting documentation and evidence File types: PDF, images (JPG, PNG), documents Typical limits: Max 5 files, 5MB each (check your implementation) What to upload by type:| Acquisition Type | Recommended Documents |
|---|---|
| Cash Purchase | Purchase receipt, invoice, warranty card, product photo, bank statement |
| Collateral | Loan agreement, collateral appraisal report, seizure authorization, asset photos, borrower acknowledgment |
| Gift | Donation letter (signed), asset photos, valuation certificate or appraisal, donor identification |
- Scan physical receipts immediately (they fade)
- Take clear photos of physical assets
- Store originals in secure physical location
- Include date in file names (e.g., “2026-06-10-laptop-receipt.pdf”)
Notify Members (Optional)
Purpose: Send email notification to all organization members about the asset When to use:- Significant purchases (> 500,000 RWF)
- Major donations
- Collateral seizures (for transparency)
- Any asset acquisition requiring member awareness
- Email notification titled “New Asset Added”
- Asset name and type
- Asset value
- Acquisition date
- Description
- Acquisition method (purchase, donation, collateral)
Advanced Options
Skip Negative Balance Check
Purpose: Override bank balance validation to allow negative balances When to use:- Opening balance adjustments
- Correcting historical data
- Special circumstances with board approval
- Can create negative bank balance
- May indicate insufficient funds
- Use only when necessary
assets:write
What Happens After Recording
When you record an asset, Agatabo automatically:- Creates journal entry based on acquisition type (ASSET_CASH_PURCHASE, ASSET_COLLATERAL, or ASSET_GIFT)
- Updates bank account (cash purchases only - decreases balance)
- Records bank charge (if specified for cash purchase - creates separate linked entry)
- Links to loan (collateral only - associates with defaulted loan)
- Calculates bad debt recovery (collateral only - automatic calculation)
- Creates borrower surplus liability (if collateral exceeds bad debt)
- Adds to balance sheet under Fixed Assets section
- Sends notifications (if enabled - emails all members)
- Logs in audit trail (records who, when, what, why)
Validation and Constraints
Input Validation
Amount:- ✅ Must be at least 0.01
- ✅ Must match organization’s currency decimal places
- ❌ Cannot be negative or zero
- ✅ Must be non-empty string
- ❌ Cannot be blank
- ✅ Must be valid ISO date
- ✅ Can be historical (past dates)
- ❌ Cannot be in closed accounting period
- ❌ Cannot exceed current date
- ✅ Must be one of: CASH_PURCHASE, COLLATERAL, GIFT
- ❌ Cannot be changed after creation (immutable - delete and recreate if needed)
- ✅ Must be active account
- ✅ Falls back to default if not specified
- ❌ Cannot use inactive accounts
- ✅ Must exist and belong to organization
- ✅ Must be DEFAULTED status
- ✅ Must have badDebtWrittenOff > 0
- ❌ Throws BadRequestException if missing for collateral
- ❌ Cannot use loan without bad debt
- ✅ Only valid for CASH_PURCHASE
- ✅ Must be ≥ 0
- ❌ Cannot be negative
- ❌ Cannot use with COLLATERAL or GIFT
Business Logic Validation
Balance Checks:- Verifies bank account won’t go negative (cash purchases)
- Can skip via
skipNegativeBalanceCheckparameter - Validates total amounts against available cash
- Cannot create asset in closed period
- Cannot backdate to closed period
- Period validation happens before posting
- All operations require idempotency key (header:
x-idempotency-key) - Prevents duplicate assets from retries
- Safe for network failures and refreshes
- Duplicate requests return existing entry
Common Scenarios
Scenario 1: Regular Equipment Purchase
Scenario 2: Seizing Collateral After Default
Scenario 3: Receiving Major Donation
Best Practices
Asset recording tips:Timing:
- Record immediately after acquisition (same day if possible)
- Don’t wait until month-end
- Batch record if multiple purchases, but don’t delay
- Always upload receipts and supporting documents
- Take photos of physical assets for visual identification
- Include vendor contact information in description
- Scan and backup all paper documents
- Use consistent format: “Type - Brand Model - Identifier”
- Include serial numbers, plate numbers, or unique IDs
- Makes asset inventory scannable and searchable
- For purchases over 500,000 RWF, get member approval first
- Document approval in description or minutes
- Consider special meeting for very large assets (> 5,000,000 RWF)
- Assign asset tags or inventory numbers
- Label assets with organization name and asset ID
- Conduct quarterly physical inventory counts
- Reconcile physical count with Agatabo records
- Cash purchases: Use actual purchase price (from receipt)
- Collateral: Get professional appraisal for accuracy
- Gifts: Conservative fair market value (don’t overvalue)
- Large donations (> 1,000,000 RWF): Require professional appraisal
- Always record wire fees, processing fees separately
- Don’t hide true cost of acquisition
- Use bank charge amount field for automatic linking
- Matches bank statement reconciliation
- Only record when collateral physically seized
- Don’t record speculative or pending seizures
- Document legal process in description
- Track borrower surplus liability settlement
- Enable for significant purchases (transparency)
- Enable for all collateral seizures (member awareness)
- Enable for all donations (acknowledge donors)
- Consider disabling for routine small purchases
Troubleshooting
”No defaulted loans available”
Cause: No loans meet collateral requirements Solution:- Verify loan status is DEFAULTED (not just overdue)
- Verify loan has bad debt written off (badDebtWrittenOff > 0)
- Default the loan first before recording collateral
“Cannot find bank account”
Cause: No active bank accounts in organization Solution:- Add a bank account first
- Verify you have
bank_accounts:readpermission - Ensure bank account is active (not closed)
“Amount validation error”
Cause: Amount doesn’t match monetary policy Solution:- Check currency decimal places (RWF has 0 decimals, USD has 2)
- Amount must be ≥ 0.01
- Don’t include currency symbols (₱, RWF, $)
- Don’t include comma separators (use 850000, not 850,000)
“Insufficient balance”
Cause: Bank account doesn’t have enough funds for cash purchase Solution:- Check bank account balance before recording
- Select different bank account with sufficient funds
- Record deposit first, then record asset purchase
- Or use
skipNegativeBalanceCheck(requires special permission)
“Cannot change acquisition kind”
Cause: Trying to edit asset’s acquisition type after creation Solution:- Acquisition kind is immutable after creation
- You cannot change CASH_PURCHASE to GIFT or vice versa
- Delete the asset and recreate with correct type
- Or edit other fields (amount, title, date) without changing type
”Date in closed period”
Cause: Trying to backdate asset to closed accounting period Solution:- Use current period date instead
- Or reopen accounting period (if permitted)
- Contact administrator about period constraints
Permissions Required
| Action | Permission | Scope |
|---|---|---|
| View assets | assets:read | ANY |
| Create asset | assets:write | ANY |
| Upload documents | 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.Related Topics
Fixed Assets Overview
Understand asset types and features
Editing Assets
Update asset information
Asset Disposal
Remove or sell assets (future)
Bank Accounts
Manage organization accounts
Loan Defaulting
Handle defaulted loans
Balance Sheet
View total asset value