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, line-item product, 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. Pass productId to return only invoices that contain that storefront product on at least one line.

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
productId	string	No	Filter invoices that include this storefront product on at least one line item (items.productId)

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