Update draft purchase order line items

PATCH 
/v1/entities/:entity_id/purchase_orders/:uuid

Adds, updates, or removes line items on a draft purchase order, and sets its lifecycle dates.

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. The only keys accepted under purchase_order are line_items_attributes, order_placed_date, order_shipped_date, and order_cancelled_date; any other key — including currency, destination_location_id, supplier_id, supplier_name, metadata, note, and tags — is forbidden on PATCH and returns 422 (merchants change those through the Bookkeep app). Only works while status is draft — once the merchant marks the purchase order ordered, PATCH returns 422.

Include id on a line to update it, omit id to add a new line, and set _destroy: true on a line to remove it. A line sent without id but carrying a client_line_id that already exists on this purchase order updates that existing line rather than adding one, so reuse a client_line_id only when you mean to update. Removing a line whose stock has already been received is refused with 422.

Request

Responses

200

Purchase order updated.

400

changed_by is missing or malformed, the body isn't valid JSON, or it has no purchase_order object at the top level.

401

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.

403

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).

404

Purchase order not found, belongs to another shop, or is soft-deleted. A malformed path segment — an {entity_id} containing anything other than letters and digits, or a {uuid} containing anything other than letters, digits, - or _ — is instead rejected by routing before this endpoint runs, and that 404 carries the Bookkeep app's HTML error page rather than the JSON body below.

413

Request body exceeds the 1 MB limit.

422

Returned when the purchase order isn't in draft status, a forbidden top-level key was sent, or a line item failed validation. The status check returns a single error string; forbidden keys and line item failures return an errors array instead — handle both shapes.

504

The purchase order service did not respond in time. The update may or may not have been applied — re-load the purchase order before retrying.