Open POS Business Session (v1)

Method & Path

POST /v1/workspace/:workspaceId/pos/business-session/open

Actual backend path: /v1/workspace/:workspaceId/pos/business-session/open

Description

Opens a new POS business session with the given business date (YYYY-MM-DD). If another session is already open for the workspace store, it is closed automatically before creating the new one.

Workspace Owner only

Requests must not include X-Staff-Id. Staff members cannot open a business session.

Authentication

Required: JWT in Authorization header.

Required permissions: store.orders.manage

Persona: Workspace Owner only (no X-Staff-Id header)

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

{
  "businessDate": "2025-03-19"
}

Parameter	Type	Required	Description
businessDate	string	Yes	Operational day in YYYY-MM-DD format

Response 201 Created

{
  "session": {
    "id": "507f1f77bcf86cd799439014",
    "workspaceId": "507f1f77bcf86cd799439010",
    "storeId": "507f1f77bcf86cd799439013",
    "businessDate": "2025-03-19",
    "status": "open",
    "openedAt": "2025-03-19T18:00:00.000Z",
    "closedAt": null,
    "openedBy": { "type": "workspace", "userId": "..." },
    "createdAt": "2025-03-19T18:00:00.000Z",
    "updatedAt": "2025-03-19T18:00:00.000Z"
  }
}

Common Errors

• 400 Bad Request: Invalid businessDate format
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Staff header present (only workspace owner may open), or insufficient permissions
• 422 Unprocessable Entity: Validation errors
• 500 Internal Server Error: Server error