List Incomes (v1)

Method & Path

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

Description

Retrieve a paginated list of workspace incomes with optional filtering by source, payment method, 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
source	string	No	Filter by income source (manual, invoice, order, other)
paymentMethod	string	No	Filter by payment method (cash, bank-transfer, card, check, 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

{
  "incomes": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439012",
      "amount": 500.00,
      "date": "2025-01-15T10:30:00.000Z",
      "time": "10:30",
      "description": "Payment for session #123",
      "paymentMethod": "card",
      "source": "invoice",
      "sourceId": "507f1f77bcf86cd799439013",
      "receiptImage": {
        "url": "https://storage.googleapis.com/bucket/workspace-incomes/income-id/receipt-1234567890-abc123.webp",
        "path": "workspace-incomes/income-id/receipt-1234567890-abc123.webp",
        "width": 1000,
        "height": 1000,
        "sizeBytes": 50000,
        "contentType": "image/webp"
      },
      "notes": "Payment received via Stripe",
      "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

incomes

Array of income objects with the following fields:

• id (string): Unique income identifier
• workspaceId (string): Workspace identifier
• amount (number): Income amount
• date (string): Income date (ISO 8601 format)
• time (string): Income time in HH:MM format
• description (string): Income description
• paymentMethod (string): Payment method (cash, bank-transfer, card, check, other)
• source (string | null): Income source (manual, invoice, order, other)
• sourceId (string | null): ID of the source entity (e.g., invoice ID, order ID)
• receiptImage (object | null): Receipt image information
• notes (string | null): Additional notes
• createdBy (string): ID of the user who created the income
• createdAt (string): Creation timestamp (ISO 8601 format)
• updatedAt (string): Last update timestamp (ISO 8601 format)

pagination

• total (number): Total number of incomes
• 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 source or payment method)

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 incomes are sorted by date (descending), then by creation date (descending)
• Date filters use UTC timezone
• Source and payment method filters are case-sensitive and must match valid enum values
• Workspace subscription status is checked before processing the request