Create Income (v1)

Method & Path

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

Description

Create a new income 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": 500.00,
  "date": "2025-01-15T10:30:00.000Z",
  "time": "10:30",
  "description": "Payment for session #123",
  "paymentMethod": "card",
  "source": "invoice",
  "sourceId": "507f1f77bcf86cd799439013",
  "notes": "Payment received via Stripe"
}

Request Body Schema

Field	Type	Required	Description
amount	number	Yes	Income amount (min: 0)
date	date	No	Income date (ISO 8601 format). Defaults to current date if not provided
time	string	Yes	Income time in HH:MM format (24-hour format, e.g., "14:30")
description	string	Yes	Income description (min length: 1)
paymentMethod	string	Yes	Payment method (cash, bank-transfer, card, check, other)
source	string	No	Income source (manual, invoice, order, other, pos). Use pos when transferring Point of Sale (نقطة البيع) daily sales to income
sourceId	string	No	ID of the source entity (e.g., invoice ID, order ID). Can be null
notes	string	No	Additional notes about the income

Response 201 Created

{
  "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": null,
  "notes": "Payment received via Stripe",
  "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 income records

404 Not Found: Workspace not found

422 Unprocessable Entity: Validation error (e.g., invalid payment method or source 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 Income Receipt endpoint
• Workspace subscription status is checked before processing the request
• POS transfer: When transferring daily Point of Sale (نقطة البيع) revenue to income, send source: "pos" and set amount to the total daily sales. The client can select a workspace income source named "pos" (نقطة البيع) when using the POS reports transfer feature.