Skip to main content

Upload Expense Receipt (v1)

Method & Path​

POST /api/v1/admin/expenses/:expenseId/receipt

Description​

Upload a receipt image for an expense. The image will be processed, optimized, and stored in Google Cloud Storage. The endpoint returns the receipt image metadata that can be used when creating or updating an expense.

Authentication​

Required: Admin authentication with dashboard.view permission.

Headers​

Authorization: Bearer <admin_token>
Content-Type: multipart/form-data

Path Parameters​

ParameterTypeRequiredDescription
expenseIdstringYesThe unique identifier of the expense

Request Body​

The request must use multipart/form-data encoding with a file field named file.

FieldTypeRequiredDescription
filefileYesReceipt image file (PNG, JPEG, or WebP, max 5MB)

Response 201 Created​

{
  "receiptImage": {
    "url": "https://storage.googleapis.com/bucket/admin-expenses/507f1f77bcf86cd799439011/receipt-1736936400000-abc123.webp",
    "path": "admin-expenses/507f1f77bcf86cd799439011/receipt-1736936400000-abc123.webp",
    "width": 1920,
    "height": 1080,
    "sizeBytes": 125000,
    "contentType": "image/webp"
  }
}

Response Fields​

receiptImage​

  • url (string): Public URL to the uploaded receipt image
  • path (string): Server storage path to the image
  • width (number | null): Image width in pixels (null if unknown)
  • height (number | null): Image height in pixels (null if unknown)
  • sizeBytes (number | null): Image file size in bytes (null if unknown)
  • contentType (string): MIME type of the image (always image/webp)

Common Errors​

400 Bad Request:

  • Invalid expense ID format
  • Missing file in request
  • File is empty
  • File size exceeds 5MB limit

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Admin does not have dashboard.view permission

404 Not Found: Expense not found

422 Unprocessable Entity:

  • Unsupported image type (only PNG, JPEG, and WebP are supported)
  • Image is too large (maximum 5MB)

500 Internal Server Error: Server error occurred while processing or uploading the image

Notes​

  • Images are automatically converted to WebP format for optimization
  • Maximum file size is 5MB (5,242,880 bytes)
  • Supported image formats: PNG, JPEG, WebP
  • Images are stored in Google Cloud Storage and made publicly accessible
  • The image metadata returned can be used in the receiptImage field when creating or updating an expense
  • The storage path follows the pattern: admin-expenses/{expenseId}/receipt-{timestamp}-{random}.webp