Create Expense (v1)

Method & Path

POST /api/v1/admin/expenses

Description

Create a new expense record for the platform. Expenses are used to track platform operational costs such as rent, salaries, utilities, marketing, and other services.

Authentication

Required: Admin authentication with dashboard.view permission.

Headers

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

Request Body

{
  "amount": 1500.00,
  "date": "2025-01-15T10:30:00.000Z",
  "description": "Monthly office rent",
  "category": "rent",
  "notes": "Paid via bank transfer",
  "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"
  }
}

Request Body Schema

Field	Type	Required	Description
amount	number	Yes	Expense amount in USD (must be > 0)
date	date	No	Expense date (defaults to current date/time)
description	string	Yes	Expense description (must not be empty)
category	string	Yes	Expense category: services, salaries, rent, utilities, marketing, refs, or other
notes	string	No	Additional notes about the expense
receiptImage	object	No	Receipt image information (see Receipt Image Schema below)

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)

Response 201 Created

{
  "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"
}

Common Errors

400 Bad Request:

• Invalid category value
• Amount must be greater than 0
• Description is required and cannot be empty
• Invalid receipt image format

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Admin does not have dashboard.view permission

500 Internal Server Error: Server error occurred while creating the expense

Notes

• The createdBy field is automatically set to the authenticated admin's ID
• Receipt images should be uploaded using the dedicated upload endpoint (POST /api/v1/admin/expenses/:expenseId/receipt) before creating the expense, or the receipt image metadata can be included in the request body
• All date values use UTC timezone