E117: Add item to purchase order

POST /api/purchase-orders/:id/items

Appends a new line to an existing PO. Triggered from the Purchase Order Detail items section. If the PO has already moved past Planning, the workflow also writes a matching ORDER ledger entry so on-order quantities stay accurate.

Authentication

Standard tenant route. Requires Authorization: Bearer <firebase-id-token> and X-Org-Id: <org-id>. Access: Member.

Request

{
  "materialId": "uuid",
  "skuId": null,
  "quantity": 100,
  "unitCost": 12.34
}

Exactly one of materialId / skuId is required, matching the PO's targetType.

Response — 201 Created

{
  "id": "uuid",
  "poId": "uuid",
  "materialId": "uuid",
  "skuId": null,
  "quantity": 100,
  "unitCost": 12.34
}

Errors

HTTP	code	Condition
404	not_found	PO, material, or SKU does not exist.
409	conflict	A receipt exists against the PO — line items are locked.
422	validation_failed	materialId/skuId does not match targetType, or quantity/cost shape invalid.

Workflow

Calls W117 Add item to purchase order.