List POS Invoices (v1)

Method & Path

GET /v1/workspace/:workspaceId/pos/invoices

Actual backend path: /v1/workspace/:workspaceId/pos/invoices

Description

List POS invoices for the workspace with optional filters: client, status, order status (workspace-defined), POS business session ID, and/or date range on createdAt. Prefer posBusinessSessionId when scoping to the current operational day; startDate/endDate remain useful for legacy invoices without a session or custom ranges.

Authentication

Required: JWT in Authorization header.

Required permissions: store.orders.manage

Persona: Workspace Owner, Staff (store.orders.manage)

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

Parameter	Type	Required	Description
clientId	string	No	Filter by workspace client ID
status	string	No	One of: draft, completed, cancelled
orderStatusId	string	No	Filter by workspace-defined order status ID (from POS order statuses)
startDate	string	No	ISO 8601 date/time; filter invoices created on or after this time
endDate	string	No	ISO 8601 date/time; filter invoices created on or before this time
posBusinessSessionId	string	No	Filter invoices belonging to this POS business session

Response 200 OK

{
  "invoices": [
    {
      "id": "507f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "storeId": "507f1f77bcf86cd799439013",
      "clientId": "507f1f77bcf86cd799439011",
      "posBusinessSessionId": "507f1f77bcf86cd799439014",
      "businessDate": "2025-03-19",
      "publicId": "POS-001",
      "status": "completed",
      "orderStatusId": "507f1f77bcf86cd799439099",
      "orderStatusLabelAr": "قيد التحضير",
      "items": [],
      "subtotal": 100,
      "discounts": [],
      "total": 100,
      "stockDeductedAt": "2024-01-15T10:05:00.000Z",
      "createdBy": null,
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:05:00.000Z"
    }
  ]
}

Common Errors

• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Insufficient permissions (requires store.orders.manage)
• 404 Not Found: Workspace not found
• 500 Internal Server Error: Server error