List purchase orders
GET/v1/entities/:entity_id/purchase_orders
Returns purchase orders for the key's store, in any status.
Requires the purchase_orders:read scope.
The response is a plain JSON object with no data/included envelope. The root key is
purchase_orders; pagination lives in meta (page, per_page, total). Results are
returned in the order the purchase orders were created, oldest first.
Supports include=line_items,receipts,supplier, fields[...] to choose which fields come
back (fields[purchase_order], fields[line_item], fields[receipt], fields[supplier]),
and filter[<field>_<predicate>] on the purchase order's own fields, including
bill_status and bills_count. Line item, receipt and supplier fields cannot be filtered:
a filter such as filter[line_items_sku_eq] returns 400 with Unsupported filter: line_items_sku_eq. See Query parameters in the
Inventory API overview.
fields[line_item], fields[receipt] and fields[supplier] only apply together with the
matching include. A fields[...] entry naming a field that does not exist is dropped
without an error, so a misspelled field returns 200 with that field missing. An unknown
include value returns 400.
include=receipts additionally requires the purchase_order_receipts:read scope; without it
the request returns 403. Included receipts are narrowed to committed status only.
Each included line item has an id; send it back on PATCH to change that line. An included
supplier has its uuid, the same one the Suppliers endpoints return.
Request
Responses
- 200
- 400
- 401
- 403
- 429
- 504
A dictionary with a purchase_orders array and a meta object describing pagination.
An unsupported or malformed filter, fields or include parameter. The error names the parameter, for example a filter on a field that cannot be filtered.
The Authorization header is missing, is not HTTP Basic, or does not carry a valid API key. Create and manage keys under Settings → API keys in the Bookkeep section of the Bookkeep app.
The key does not hold purchase_orders:read (or purchase_order_receipts:read when include=receipts is sent), or the key's store is not linked to {entity_id}.
Rate limit reached. The inventory endpoints share one limit of 60 requests per minute per source IP address, counted across Purchase Orders, Suppliers, Receipts and Bills. The count resets at the start of each minute. No Retry-After header is sent. The body is JSON only when the request sends Accept: application/json; otherwise it is an HTML page.
The service did not respond in time. This is a read, so it is safe to retry after a short wait.