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

# Loan Tracking

> Track who has borrowed items, set return dates, and manage overdue assets

## Overview

Invenicum's loan tracking system helps you monitor items lent to team members, clients, or friends. Track who has what, when it's due back, and automatically update inventory when items are returned.

<CardGroup cols={2}>
  <Card title="Automated Stock Management" icon="arrows-rotate">
    Inventory adjusts automatically when items are loaned or returned
  </Card>

  <Card title="Return Reminders" icon="bell">
    Dashboard highlights loans expiring today or overdue
  </Card>

  <Card title="Borrower Profiles" icon="user">
    Store contact details and loan history
  </Card>

  <Card title="Digital Vouchers" icon="receipt">
    Generate formatted loan receipts
  </Card>
</CardGroup>

## How It Works

### Creating a Loan

When you lend an item, Invenicum creates a **loan record** and decrements the item's quantity.

<Steps>
  <Step title="Select Item to Loan">
    Navigate to the item you want to lend. Check that `quantity` is sufficient.
  </Step>

  <Step title="Click 'Create Loan'">
    Opens the loan creation form.
  </Step>

  <Step title="Enter Borrower Details">
    * **Name** (required)
    * **Email** (optional, for notifications)
    * **Phone** (optional)

    <Tip>Contact info is stored for future loans to the same person.</Tip>
  </Step>

  <Step title="Set Loan Parameters">
    * **Quantity**: How many units to lend
    * **Loan Date**: Defaults to today
    * **Expected Return Date**: When you expect the item back
    * **Notes**: Special instructions or conditions
  </Step>

  <Step title="Save Loan">
    Item quantity is reduced immediately. A voucher ID is generated.
  </Step>
</Steps>

**Technical Details** (lib/data/services/loan\_service.dart:50):

```dart theme={null}
LoanService.createLoan(containerId, loan)
// POST /containers/{containerId}/loans
// Backend automatically:
//   1. Validates sufficient quantity
//   2. Decrements item stock
//   3. Sets status to 'active'
//   4. Associates with authenticated user
```

### Loan States

Each loan has a `status` field:

* **active**: Item is currently loaned out
* **returned**: Item has been returned (sets `actualReturnDate`)

<Note>
  Overdue status is calculated dynamically. A loan is overdue if `status == 'active'` and `expectedReturnDate` is in the past (lib/data/models/loan.dart:135).
</Note>

### Returning Items

When a borrower returns an item:

<Steps>
  <Step title="Navigate to Loan">
    Find the loan in the Loans view (filter by borrower, item, or status).
  </Step>

  <Step title="Click 'Mark as Returned'">
    This action:

    * Sets `status` to "returned"
    * Records `actualReturnDate`
    * **Increments item quantity** by the loaned amount
  </Step>

  <Step title="Verify Inventory">
    Check the item's quantity reflects the return.
  </Step>
</Steps>

**Technical Details** (lib/data/services/loan\_service.dart:69):

```dart theme={null}
LoanService.returnLoan(containerId, loanId)
// PUT /containers/{containerId}/loans/{loanId}/return
// Backend automatically increments stock
```

<Warning>
  Returning a loan increments stock regardless of the item's actual condition. Damaged items should be noted in the loan's notes before returning, then adjusted manually in inventory.
</Warning>

### Deleting Loans

Loans can be deleted if created by mistake (lib/data/services/loan\_service.dart:86):

* Only the user who created the loan can delete it
* Deleting an **active** loan does **not** restore item quantity
* Use this for erroneous entries, not for returns

<Tip>
  If you accidentally loaned the wrong item, delete the loan and manually adjust the item's quantity before creating a corrected loan.
</Tip>

## Dashboard Integration

The main dashboard provides loan insights (lib/data/models/dashboard\_stats.dart:13):

### Loans Expiring Today

Shows all active loans with `expectedReturnDate` matching today's date. Click to view details or mark as returned.

### Top Loaned Items

Highlights your most frequently borrowed assets, helping identify:

* High-demand items that may need additional purchases
* Items to monitor closely for wear and tear

### Container-Specific Stats

Each container shows:

* Total active loans
* Total loaned quantity
* Overdue loan count

## Use Cases

<CardGroup cols={2}>
  <Card title="IT Equipment Loans" icon="laptop">
    Track laptops, monitors, and peripherals lent to remote employees.
  </Card>

  <Card title="Tool Libraries" icon="wrench">
    Manage shared tools in maker spaces or workshops.
  </Card>

  <Card title="Event Rentals" icon="calendar-day">
    Monitor equipment loaned for events with specific return deadlines.
  </Card>

  <Card title="Library Systems" icon="book">
    Simple book lending with due date tracking.
  </Card>
</CardGroup>

## Voucher System

Each loan generates a unique formatted voucher ID (lib/data/models/loan.dart:19):

```dart theme={null}
formattedVoucherId => 'V-000042'
// Format: V-{6-digit zero-padded ID}
```

Use this for:

* Physical receipts when items leave your facility
* Reference numbers in email confirmations
* Quick lookup in the search interface

<Note>
  The voucher ID is derived from the loan's database ID and is generated automatically.
</Note>

## Notifications and Reminders

Invenicum highlights time-sensitive loans:

### Dashboard Alerts

* **Expiring Today**: Shows in dedicated "Loans Expiring Today" widget
* **Overdue**: Calculated client-side based on `expectedReturnDate < now`

### Future Enhancements

Upcoming features (not yet implemented):

* Email reminders to borrowers 24h before due date
* Automatic notifications when loans become overdue
* Recurring loan patterns for regular equipment sharing

## Loan Statistics

Access detailed analytics per container (lib/data/services/loan\_service.dart:101):

```dart theme={null}
LoanService.getLoanStats(containerId)
// GET /containers/{containerId}/loans-stats
```

Returns:

* Active loan count
* Total loaned quantity
* Overdue count
* Average loan duration
* Most frequent borrowers

<Tip>
  Use loan stats to identify trends and optimize inventory levels for high-demand items.
</Tip>

## Best Practices

### Before Loaning

1. **Verify Quantity**: Ensure sufficient stock before creating the loan
2. **Document Condition**: Add notes about any existing damage
3. **Set Realistic Due Dates**: Account for weekends and holidays
4. **Capture Contact Info**: Always get borrower email/phone for follow-ups

### Managing Active Loans

1. **Check Dashboard Daily**: Review expiring and overdue loans each morning
2. **Communicate Proactively**: Contact borrowers 1-2 days before due date
3. **Inspect on Return**: Verify item condition matches loan notes
4. **Update Immediately**: Mark items returned as soon as they arrive

### For High-Value Items

1. **Require Approval**: Implement a workflow where admins approve loans
2. **Shorter Loan Periods**: Reduce risk with 3-5 day maximum loans
3. **Photo Documentation**: Attach images to loan notes showing pre-loan condition
4. **Insurance Notes**: Record relevant insurance details in loan notes

## Limitations

* **No Partial Returns**: If loaning 5 units, you must return all 5 at once (workaround: create separate loans per unit)
* **Single Item Per Loan**: Each loan tracks one inventory item (workaround: create multiple loans)
* **No Late Fees**: System tracks overdue status but doesn't calculate penalties
* **Manual Notifications**: Borrowers aren't automatically emailed; notifications are managed through the Alerts system

## API Reference

See the API documentation for:

* Loan Service - Loan management API
* Loan Model - Complete loan data structure
* Dashboard Stats - Loan insights and statistics