Update POS Invoice Order Status (v1)

Method & Path

PATCH /v1/workspace/:workspaceId/pos/invoices/:invoiceId/order-status

Actual backend path: /v1/workspace/:workspaceId/pos/invoices/:invoiceId/order-status

Description

Set or clear the workspace-defined order status on a POS invoice. This does not change the system status (draft/completed/cancelled); it only sets the optional display/workflow status used in the orders list and filters.

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>
Content-Type	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier
invoiceId	string	Yes	POS invoice ID (MongoDB ObjectId)

Request Body

{
  "orderStatusId": "507f1f77bcf86cd799439099"
}

Or to clear the status:

{
  "orderStatusId": null
}

Parameter	Type	Required	Description
orderStatusId	string | null	Yes	Order status ID from the same workspace, or null to clear

Response 200 OK

Returns the updated invoice (same shape as Get POS Invoice), including orderStatusId and orderStatusLabelAr when set.

{
  "invoice": {
    "id": "507f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "storeId": "507f1f77bcf86cd799439013",
    "clientId": "507f1f77bcf86cd799439011",
    "publicId": "ABC123",
    "status": "completed",
    "orderStatusId": "507f1f77bcf86cd799439099",
    "orderStatusLabelAr": "قيد التحضير",
    "items": [],
    "subtotal": 100,
    "discounts": [],
    "total": 100,
    "notes": null,
    "stockDeductedAt": "2024-01-15T10:05:00.000Z",
    "createdBy": null,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:10:00.000Z"
  }
}

Common Errors

• 400 Bad Request: Invalid invoice or order status identifier
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Insufficient permissions
• 404 Not Found: POS invoice or order status not found (or status does not belong to workspace)
• 500 Internal Server Error: Server error