Create Expense (v1)

Method & Path

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

Description

Create a new expense record for the workspace.

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

Request Body

{
  "amount": 1500.00,
  "date": "2025-01-15T10:30:00.000Z",
  "time": "10:30",
  "description": "Monthly office rent",
  "category": "rent",
  "notes": "Paid via bank transfer"
}

Request Body Schema

Field	Type	Required	Description
amount	number	Yes	Expense amount (min: 0)
date	date	No	Expense date (ISO 8601 format). Defaults to current date if not provided
time	string	Yes	Expense time in HH:MM format (24-hour format, e.g., "14:30")
description	string	Yes	Expense description (min length: 1)
category	string	Yes	Expense category (services, salaries, rent, utilities, marketing, other)
notes	string	No	Additional notes about the expense

Response 201 Created

{
  "id": "507f1f77bcf86cd799439011",
  "workspaceId": "507f1f77bcf86cd799439012",
  "amount": 1500.00,
  "date": "2025-01-15T10:30:00.000Z",
  "time": "10:30",
  "description": "Monthly office rent",
  "category": "rent",
  "receiptImage": null,
  "notes": "Paid via bank transfer",
  "createdBy": "507f1f77bcf86cd799439014",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Common Errors

400 Bad Request: Invalid request body (e.g., invalid amount, invalid time format, missing required fields)

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have permission to create expense records

404 Not Found: Workspace not found

422 Unprocessable Entity: Validation error (e.g., invalid category enum value)

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

Notes

• The createdBy field is automatically set to the authenticated user's ID (staff ID if available, otherwise workspace ID)
• Receipt image can be uploaded separately using the Upload Expense Receipt endpoint
• Workspace subscription status is checked before processing the request