Create draft purchase order
POST/v1/entities/:entity_id/purchase_orders
Creates a draft purchase order for replenishment or AI-generated recommendations that a merchant reviews before ordering.
Requires the purchase_orders:write scope. The key's shop must also be linked to
{entity_id}, else 403 — see the API key scheme on the Authentication page.
supplier_name resolves via a case-insensitive exact match within the shop's suppliers (422
if none or ambiguous); a supplier can also be omitted, letting the merchant assign one later
in the Bookkeep app. Line items are optional on create.
Pass an Idempotency-Key header to make retries safe: replaying the same key returns the
existing purchase order with HTTP 200 instead of creating a duplicate.
Request
Responses
- 200
- 201
- 400
- 401
- 403
- 409
- 413
- 422
- 504
Idempotency-Key replay — returns the existing purchase order instead of creating a duplicate.
Purchase order created.
changed_by is missing or malformed, the body isn't valid JSON, or it has no purchase_order object at the top level.
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.
The key is missing the purchase_orders:write scope, or the key's shop is not linked to {entity_id} (or is not linked to any Bookkeep entity).
A purchase order matching this one already exists and no Idempotency-Key header was sent, so it could not be replayed. Retry the request with an Idempotency-Key.
Request body exceeds the 1 MB limit.
Validation error — missing/invalid currency or destination_location_id, unresolved supplier_name, or an invalid line item. Two body shapes are possible: request-level validation returns an errors array, while a record-level validation failure (for example quantity_ordered not greater than zero) returns a single error string. Handle both.
The purchase order service did not respond in time. The request may or may not have been processed — retry with the same Idempotency-Key to avoid creating a duplicate.