E111: Create purchase order

POST /api/purchase-orders

Opens a new purchase order against a vendor. Triggered from the Purchase Orders page, "New PO" button. The PO header is persisted with its line items and the header-level surcharges (shipping and setup).

Authentication

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

Request

{
  "vendorId": "uuid",
  "targetType": "materials",
  "shipToLocationId": "uuid",
  "orderDate": "2026-05-18",
  "expectedDate": "2026-05-25",
  "shippingCosts": 50.00,
  "setupCosts": 0.00,
  "notes": "..."
}

Field	Type	Required	Notes
vendorId	uuid	yes	Must reference an active vendor.
targetType	"materials" | "finished_goods"	yes	Decides which inventory ledger receipts write to.
shipToLocationId	uuid	yes	Receiving location.
orderDate	date	yes
expectedDate	date	no
shippingCosts	decimal	no	Default 0.
setupCosts	decimal	no	Default 0.
notes	string	no

poNumber is generated server-side (per-tenant numbering, format PO-{year}-{seq}).

Response — 201 Created

{
  "id": "uuid",
  "poNumber": "PO-2026-0042",
  "vendorId": "uuid",
  "targetType": "materials",
  "shipToLocationId": "uuid",
  "status": "Planning",
  "orderDate": "2026-05-18",
  "expectedDate": "2026-05-25",
  "costs": 1234.56,
  "shippingCosts": 50.00,
  "setupCosts": 0.00,
  "notes": "..."
}

Errors

HTTP	code	Condition
422	validation_failed	Field shape or vendor/location reference invalid.
404	not_found	Vendor or location does not exist in this org.

Workflow

Calls W111 Create purchase order.