Fines Endpoints
Detailed API reference for fine management — listing user fines and processing payments.
Fines Endpoints
Base path: /api/v1/fines
Authentication: All routes require a valid JWT token.
GET /fines
Returns a list of fines, filtered by user role.
Access Control
- Allowed roles: Any authenticated user
- Data filtering: Students see only their own fines; Admins/Librarians see all fines
Request
GET /api/v1/fines
Authorization: Bearer <token>Role-Based Filtering
const where = req.user.role === 'ROLE_STUDENT'
? { userId: req.user.id }
: {};Response — 200 OK
{
"fines": [
{
"_id": "64e2f...",
"userId": {
"_id": "64b8f...",
"firstName": "John",
"lastName": "Doe",
"email": "john@university.edu"
},
"transactionId": {
"_id": "64d1f...",
"issuedAt": "2026-06-15T10:00:00.000Z",
"dueDate": "2026-06-29T10:00:00.000Z",
"returnedAt": "2026-07-03T14:00:00.000Z"
},
"amount": 12.50,
"status": "UNPAID",
"reason": "Overdue return - 4 days late",
"createdAt": "2026-07-03T14:00:00.000Z"
}
]
}Populated Fields
| Field | Populated From | Data Included |
|---|---|---|
userId | User model | firstName, lastName, email |
transactionId | Transaction model | issuedAt, dueDate, returnedAt |
POST /fines/:id/pay
Marks a fine as PAID, resolving it.
Access Control
- Allowed roles:
ROLE_ADMIN,ROLE_LIBRARIAN
Request
POST /api/v1/fines/64e2f.../pay
Authorization: Bearer <token>No request body required.
What Happens
Fine.findByIdAndUpdate(
req.params.id,
{ status: 'PAID' },
{ new: true }
);The fine's status field is updated from UNPAID to PAID.
Response — 200 OK
{
"fine": {
"_id": "64e2f...",
"userId": "64b8f...",
"transactionId": "64d1f...",
"amount": 12.50,
"status": "PAID",
"reason": "Overdue return - 4 days late"
}
}Fine Status Values
| Status | Description |
|---|---|
UNPAID | Fine is outstanding and requires payment |
PAID | Fine has been collected and resolved |
WAIVED | Fine was forgiven by an administrator |
Fine Lifecycle
Book returned late
│
▼
┌──────────────┐
│ Fine Created │
│ status: UNPAID│
└──────┬───────┘
│
├── Librarian collects payment
│ │
│ ▼
│ ┌──────────┐
│ │ PAID │
│ └──────────┘
│
└── Admin waives fine
│
▼
┌──────────┐
│ WAIVED │
└──────────┘