Create Supplier Payment (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/suppliers/:supplierId/payments

Actual backend path: POST /v1/workspace/:workspaceId/suppliers/:supplierId/payments

Description

Create a new payment for a supplier. Optionally link to an invoice via invoiceId; the backend will update the invoice’s paid/remaining amounts and status.

Authentication

Required: Workspace JWT.

Persona access

• Workspace Owner: Allowed (suppliers section enabled for workspace).
• Staff: Allowed when suppliers access is granted via workspace menu/permissions.
• Admin / Customer: Not applicable for this client workspace API.

Headers

Header	Required	Description
Authorization	Yes	Bearer <workspace_token>
Content-Type	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier
supplierId	string	Yes	Supplier identifier

Request Body

{
  "invoiceId": "507f1f77bcf86cd799439021",
  "amount": 2000,
  "paymentDate": "2024-01-20",
  "paymentMethod": "bank-transfer",
  "description": "دفعة أولى",
  "notes": "ملاحظات",
  "imageUrl": "https://storage.googleapis.com/bucket/path/to/receipt.webp"
}

Field	Type	Required	Description
invoiceId	string or null	No	Link to supplier invoice (optional)
amount	number	Yes	Must be ≥ 0
paymentDate	string (date)	Yes	Date of payment
paymentMethod	string	Yes	One of: cash, check, bank-transfer, card, other
description	string	No	Optional description
notes	string	No	Optional notes
imageUrl	string (URL) or null	No	Optional receipt image; upload via Upload supplier payment image first

note

To attach an image, call POST .../suppliers/:supplierId/payment-image with multipart field file, then include the returned HTTPS URL in imageUrl.

Response 201 Created

{
  "payment": {
    "id": "507f1f77bcf86cd799439031",
    "workspaceId": "507f1f77bcf86cd799439012",
    "supplierId": "507f1f77bcf86cd799439011",
    "invoiceId": "507f1f77bcf86cd799439021",
    "amount": 2000,
    "paymentDate": "2024-01-20T00:00:00.000Z",
    "paymentMethod": "bank-transfer",
    "description": "دفعة أولى",
    "notes": "ملاحظات",
    "imageUrl": null,
    "createdAt": "2024-01-20T10:00:00.000Z",
    "updatedAt": "2024-01-20T10:00:00.000Z"
  }
}

Common Errors

• 400 Bad Request: Validation error
• 401 Unauthorized: Missing or invalid token
• 403 Forbidden: Workspace access denied
• 404 Not Found: Workspace, supplier, or invoice (if provided) not found
• 500 Internal Server Error: Server error