Create POS Invoice (v1)

Method & Path

POST /v1/workspace/:workspaceId/pos/invoices

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

Description

Create a new draft POS invoice for a workspace client. The invoice has no items initially; add items with the Add Invoice Item endpoint.

If the client has an active POS invoice discount (posInvoiceDiscount on the client profile), a matching discount line (source: "client") is added automatically when the invoice is created (totals reflect an empty cart until items are added).

Requires an open POS business session for the workspace store. The new invoice is linked to that session (posBusinessSessionId, businessDate).

Authentication

Required: JWT in Authorization header. Workspace context (workspaceId) must match the authenticated workspace or staff member's workspace.

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

Request Body

{
  "clientId": "507f1f77bcf86cd799439011"
}

Parameter	Type	Required	Description
clientId	string	Yes	Workspace client ID (MongoDB ObjectId)

Response 201 OK

{
  "invoice": {
    "id": "507f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "storeId": "507f1f77bcf86cd799439013",
    "clientId": "507f1f77bcf86cd799439011",
    "posBusinessSessionId": "507f1f77bcf86cd799439014",
    "businessDate": "2025-03-19",
    "publicId": "POS-001",
    "status": "draft",
    "items": [],
    "subtotal": 0,
    "discounts": [],
    "total": 0,
    "stockDeductedAt": null,
    "createdBy": { "type": "staff", "id": "...", "name": "...", "email": "..." },
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

Common Errors

• 400 Bad Request: Invalid request body or missing clientId
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Insufficient permissions (requires store.orders.manage)
• 404 Not Found: Workspace or client not found
• 422 Unprocessable Entity: Validation errors, or no open POS business session (workspace owner must open a day first)
• 500 Internal Server Error: Server error