List Expenses (v1)

Method & Path

GET /api/v1/admin/expenses

Description

Retrieve a paginated list of all platform expenses with optional filtering by category and date range.

Authentication

Required: Admin authentication with dashboard.view permission.

Headers

Authorization: Bearer <admin_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
category	string	No	Filter by expense category (services, salaries, rent, utilities, marketing, other)
startDate	date	No	Start date for date range filter (ISO 8601 format)
endDate	date	No	End date for date range filter (ISO 8601 format)
page	number	No	Page number (default: 1, min: 1)
limit	number	No	Items per page (default: 20, min: 1, max: 100)

Response 200 OK

{
  "expenses": [
    {
      "id": "507f1f77bcf86cd799439011",
      "amount": 1500.00,
      "date": "2025-01-15T10:30:00.000Z",
      "description": "Monthly office rent",
      "category": "rent",
      "receiptImage": {
        "url": "https://storage.googleapis.com/bucket/admin-expenses/expense-id/receipt-1234567890-abc123.webp",
        "path": "admin-expenses/expense-id/receipt-1234567890-abc123.webp",
        "width": 1000,
        "height": 1000,
        "sizeBytes": 50000,
        "contentType": "image/webp"
      },
      "notes": "Paid via bank transfer",
      "createdBy": "507f1f77bcf86cd799439014",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Response Fields

expenses

Array of expense objects with the following fields:

• id (string): Unique expense identifier
• amount (number): Expense amount in USD
• date (string): Expense date (ISO 8601 format)
• description (string): Expense description
• category (string): Expense category (services, salaries, rent, utilities, marketing, other)
• receiptImage (object | null): Receipt image information (see Receipt Image Schema below)
• notes (string | undefined): Additional notes about the expense
• createdBy (string): ID of the admin who created the expense
• createdAt (string): Creation timestamp (ISO 8601 format)
• updatedAt (string): Last update timestamp (ISO 8601 format)

Receipt Image Schema

Field	Type	Required	Description
url	string	Yes	Public URL to the receipt image
path	string	Yes	Server path to the receipt image
width	number	No	Image width in pixels
height	number	No	Image height in pixels
sizeBytes	number	No	Image file size in bytes
contentType	string	Yes	MIME type of the image (typically image/webp)

pagination

• page (number): Current page number
• limit (number): Number of items per page
• total (number): Total number of expenses
• totalPages (number): Total number of pages

Common Errors

400 Bad Request: Invalid query parameters (e.g., invalid date format, invalid category)

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Admin does not have dashboard.view permission

500 Internal Server Error: Server error occurred while processing the request

Notes

• All expenses are sorted by date (descending), then by creation date (descending)
• Date filters use UTC timezone
• Category filter is case-sensitive and must match one of the valid category values