List Expenses (v1)

Method & Path

GET /api/v1/client/workspace/:workspaceId/expenses

Description

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

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with financial permissions.

Headers

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

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

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

Response 200 OK

{
  "expenses": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439012",
      "amount": 1500.00,
      "date": "2025-01-15T10:30:00.000Z",
      "time": "10:30",
      "description": "Monthly office rent",
      "category": "rent",
      "receiptImage": {
        "url": "https://storage.googleapis.com/bucket/workspace-expenses/expense-id/receipt-1234567890-abc123.webp",
        "path": "workspace-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": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  }
}

Response Fields

expenses

Array of expense objects with the following fields:

• id (string): Unique expense identifier
• workspaceId (string): Workspace identifier
• amount (number): Expense amount
• date (string): Expense date (ISO 8601 format)
• time (string): Expense time in HH:MM format
• description (string): Expense description
• category (string): Expense category (services, salaries, rent, utilities, marketing, other)
• receiptImage (object | null): Receipt image information
• notes (string | null): Additional notes
• createdBy (string): ID of the user who created the expense
• createdAt (string): Creation timestamp (ISO 8601 format)
• updatedAt (string): Last update timestamp (ISO 8601 format)

pagination

• total (number): Total number of expenses
• page (number): Current page number
• limit (number): Number of items per page
• 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: User does not have permission to view financial data

404 Not Found: Workspace not found

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
• Workspace subscription status is checked before processing the request