Apply POS Invoice Discount (v1)

Method & Path

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

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

Description

Adds a discount line to a draft POS invoice. Discounts are applied in order; each line’s applied monetary amount is capped by the remaining subtotal after previous lines. After any change to line items or discounts, percentage and fixed (kind + value) lines are recomputed from the current subtotal; legacy rows without kind use their stored amount as a fixed cap.

Only draft invoices can be modified. Multiple discounts can be applied (each call appends an entry).

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

Option A — Fixed or percentage (recommended)

{
  "kind": "percentage",
  "value": 10,
  "reason": "عرض",
  "source": "manual"
}

Parameter	Type	Required	Description
kind	string	Yes	fixed or percentage
value	number	Yes	Fixed currency amount, or percentage 0–100 when kind is percentage
reason	string	Yes	Reason or note (1–2000 characters)
source	string	No	manual (default) or client (system may set for client default discount)

Option B — Legacy fixed amount

{
  "amount": 10,
  "reason": "Promotion"
}

Treated as kind: "fixed" with value equal to amount.

Response 200 OK

Returns the updated invoice. Each element of discounts may include kind, value, amount (applied), reason, and optional source. subtotal is the sum of line items before invoice discounts; total is after all discount lines.

Common Errors

• 400 Bad Request: Invalid invoice ID
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Insufficient permissions (requires store.orders.manage)
• 404 Not Found: Workspace or invoice not found
• 422 Unprocessable Entity: Invoice not in draft, session closed, percentage > 100, or validation errors
• 500 Internal Server Error: Server error