Items & PurchaseOrders write API

Create / update / delete Items and draft PurchaseOrders via x0 → Xero Accounting API. Read paths remain OData / cache tables.

Scopes

Scope	Use
`xero.items.write`	PUT/POST/DELETE `/v1/items…` and OData Items writes
`xero.purchaseorders.write`	PUT/POST/DELETE `/v1/purchase-orders…` and OData PurchaseOrders writes

Demo customers: writes rejected (CustomerAccessDenied). Successful mutations mark items / purchaseorders (+ purchaseorders_table) cache dirty.

Upstream Xero OAuth still needs accounting.settings (Items) / accounting.transactions (PurchaseOrders) on the connected app.

REST routes (primary)

Items

Method	Path	Behaviour
`POST`	`/v1/items/preflight`	`{action, item_id?, payload?}`
`PUT`	`/v1/items`	Create — require `Code`, `Name`
`POST`	`/v1/items/{item_id}`	Update (field allow-list)
`DELETE`	`/v1/items/{item_id}`	Delete after rules

Optional create/update fields include Description, PurchaseDescription, SalesDetails, PurchaseDetails, inventory flags.

PurchaseOrders (draft-first)

Method	Path	Behaviour
`POST`	`/v1/purchase-orders/preflight`	`{action, purchase_order_id?, payload?}`
`PUT`	`/v1/purchase-orders`	Create — require `Contact`, ≥1 `LineItems`; default `Status=DRAFT`
`POST`	`/v1/purchase-orders/{purchase_order_id}`	Update draft fields
`DELETE`	`/v1/purchase-orders/{purchase_order_id}`	Delete drafts only

Not in v1: bill — see credit-notes-payments-write.md.

x0 REST uses PUT for create (Accounts-style). Upstream Xero: Items use PUT create / POST update; PurchaseOrders use POST for both.

OData aliases

Method	Path	Maps to
`POST`	`/odata/v1/Items`	create
`PATCH` / `PUT`	`/odata/v1/Items/{id}`	update
`DELETE`	`/odata/v1/Items/{id}`	delete
Same for `PurchaseOrders`

Require matching xero.*.write scopes. Line tables (PurchaseOrders_Table) return 405.

Preflight / write rules

evaluate_write_rules seeds cover Items and PurchaseOrders required fields. Call /v1/.../preflight before delete.

Implementation

Piece	Where
Items	`portal/services/items_write.py` · `api/routers/items.py`
PurchaseOrders	`portal/services/purchase_orders_write.py` · `api/routers/purchase_orders.py`
OData	`api/odata/writes.py`
Contacts / Invoices	contacts-invoices-write.md
Accounts	accounts-write.md

Simulator

xerosim accepts PUT/POST/DELETE for Items and PurchaseOrders (upsert SimResource). Other resources stay 403 unless already writeable (Contacts, Invoices).

Follow-ups

Partial PO billing / line-level bill