GET /api/agent/purchase-orders

Returns the caller's org Xero purchase orders. Filterable by raw Xero status (comma-separated string match: DRAFT/SUBMITTED/AUTHORISED/BILLED/DELETED), contactId (supplier), and issue-date range. Same pagination/totals/redaction semantics as /api/agent/invoices (cursor + nextCursor, ?autoPaginate=true 5,000-row cap with truncated, ?totals=true aggregate block grouped by raw status, totalCount, sensitive-contact drop with redactedItemCount). Each PO row carries suppressedReason (nullable): when non-null the PO has been matched to a supplier bill and is excluded from the forecast to avoid double-counting the outflow. Read-only; requires the dedicated READ_PURCHASE_ORDERS scope (NOT implied by bill/invoice access).

Auth

• Required scope: READ_PURCHASE_ORDERS
• Header: Authorization: Bearer cr_live_<prefix>_<secret>

Query parameters

Name	Type	Required	Notes
status	string	no	Comma-separated raw Xero PO statuses (e.g. AUTHORISED,BILLED). Direct string match.
contactId	string	no
dateFrom	string	no	Inclusive issue-date lower bound (YYYY-MM-DD).
dateTo	string	no	Inclusive issue-date upper bound (YYYY-MM-DD).
cursor	string	no
limit	integer	no
autoPaginate	boolean	no
totals	boolean	no

Responses

200 — Matching purchase orders.

Body: PurchaseOrdersResponse

Field	Type	Required	Notes
purchaseOrders	array of PurchaseOrder	yes
nextCursor	string	yes
totalCount	integer	yes
redactedItemCount	integer	yes
truncated	boolean	no
totals	InvoiceBillTotals	no
totalsTruncated	boolean	no
billingAlert	BillingAlert	no
xeroAlert	XeroAlert	no

401 — Unauthorized

Body: ErrorResponse

Field	Type	Required	Notes
error	string	yes

Response headers

Every successful response carries X-CashRunway-Subscription, X-CashRunway-Plan, X-CashRunway-Quota-Remaining, and X-CashRunway-Quota-Reset. Trialing subscriptions also include X-CashRunway-Trial-Days-Remaining. See the overview for details.