List purchase orders
GET/v1/entities/:entity_id/purchase_orders
Returns purchase orders for one shop, in any status, as plain nested JSON.
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). Rows are
ordered by internal id.
Requires the purchase_orders:read scope. An API key is locked to the merchant's Shopify
store domain it is bound to — passing source_system/source_system_identifier naming a
different (or unknown) store domain returns 403. The key's shop must also be linked to
{entity_id}, else 403 — see the API key scheme on the Authentication page.
Supports fields[...] to choose which fields come back (fields[purchase_order],
fields[line_item], fields[receipt], fields[supplier]), include=line_items,receipts,supplier,
and filter[<column>_<predicate>] to filter by column on the purchase order's own columns
(association predicates such as filter[line_items_sku_eq] are not supported and return 400).
A fields[...] entry naming a column that does not exist is dropped silently rather than
rejected, so a misspelled column returns 200 with that column simply absent from the
response. An unrecognised include value does return 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.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 504
A dictionary with a purchase_orders array and a meta object describing pagination.
Unsupported or malformed filter, fields, or include param.
The Authorization header is missing, is not HTTP Basic, or does not carry a valid API key. Manage your keys under Shopify admin → Bookkeep app → Settings → Manage API Keys.
Missing required scope, source_system/source_system_identifier naming a Shopify store domain other than the key's own, or the key's shop is not linked to {entity_id}.
The {entity_id} path segment is malformed — anything other than letters and digits is rejected by routing before this endpoint runs, so the body is the Bookkeep app's HTML error page rather than a JSON error object.
The purchase order service did not respond in time. The request may or may not have been processed — retry with backoff.