# Purchase Orders / Partial Receiving v26

## Purpose

v26 adds the ordered side of Purchasing before supplier invoicing.

Lifecycle:

Draft PO
→ Approved PO
→ Partial Receipt(s)
→ Fully Received PO

## Purchase order

A PO is tenant-scoped and belongs to:
- supplier
- destination warehouse

Statuses:
- draft
- approved
- partially_received
- received
- cancelled
- closed

## Lines

Each PO line stores:
- variant
- optional variant unit
- ordered quantity
- cumulative received quantity
- agreed unit cost
- ordered line amount

`received_quantity` can never exceed `ordered_quantity`.

## Approval

Only draft orders can be edited.

Approval:
- requires at least one line
- freezes the commercial order contents for receiving
- records approving user/time
- emits audit event

## Partial receiving

A receipt may consume only part of a PO line.

Example:

Ordered = 10
First receipt = 4
Remaining = 6
PO status = partially_received

Second receipt = 6
Remaining = 0
PO status = received

## Receipt linkage

Goods receipts can now optionally reference:
- purchase_order_id
- purchase_order_line_id

PO-linked receipt lines inherit the PO line unit cost.

Posting a linked receipt atomically:
1. validates remaining quantity
2. posts purchase_receipt inventory movements
3. updates weighted-average inventory cost
4. increments PO received quantities
5. recalculates PO receive status

## APIs

- POST /api/v1/purchasing/purchase-orders
- GET  /api/v1/purchasing/purchase-orders/{orderId}
- POST /api/v1/purchasing/purchase-orders/{orderId}/lines
- POST /api/v1/purchasing/purchase-orders/{orderId}/approve
- POST /api/v1/purchasing/purchase-orders/{orderId}/receipts

The resulting draft goods receipt is posted through the existing:
- POST /api/v1/purchasing/goods-receipts/{receiptId}/post

## Permissions

- purchasing.po.view
- purchasing.po.manage
- purchasing.po.approve

Existing receipt permissions remain in force.

## Next

v27:
- supplier invoices
- invoice lines
- 3-way match foundation:
  PO ordered
  vs Goods Receipt received
  vs Supplier Invoice billed
- payable creation boundary