Add POS Invoice Item (v1)

Method & Path

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

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

Description

Add a product line item to a draft POS invoice. Product must belong to the workspace's storefront store. Price is calculated from the product base price and selected options (if any). Only draft invoices can be modified.

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

Request Body

{
  "productId": "507f1f77bcf86cd799439020",
  "quantity": 2,
  "selectedOptions": [
    { "groupId": "507f1f77bcf86cd799439021", "optionId": "507f1f77bcf86cd799439022" }
  ]
}

Parameter	Type	Required	Description
productId	string	Yes	Storefront product ID
quantity	number	Yes	Integer 1–999
selectedOptions	array	No	Option selections: { groupId, optionId } per option group

Response 201 OK

Returns the updated invoice (same shape as Get POS Invoice), including the new line item and recalculated subtotal and total.

Common Errors

• 400 Bad Request: Invalid body, invalid product/options, or invoice not in draft
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Insufficient permissions (requires store.orders.manage)
• 404 Not Found: Workspace, invoice, or product not found
• 422 Unprocessable Entity: Validation errors (e.g. quantity out of range)
• 500 Internal Server Error: Server error