Create draft purchase order

POST 
/v1/entities/:entity_id/purchase_orders

Creates a draft purchase order. The merchant reviews it in Bookkeep and places the order from there.

Requires the purchase_orders:write scope.

supplier_name is matched against the store's suppliers by exact name, ignoring case. If no supplier or more than one supplier matches, the request returns 422. You can also leave the supplier out and let the merchant choose one later in the Bookkeep app. Line items are optional on create.

A line sent with only a sku is matched to the one product in your store with exactly that SKU, and the response fills in its variant_id, inventory_item_id, product_id and title. A SKU that matches no product, or more than one, returns 422 naming the SKU. A product added in Shopify in the last few minutes may not be in Bookkeep yet: retry later, or send its variant_id or inventory_item_id instead. Each client_line_id must be unique within the request.

destination_location_name is the location's name as it appears in Shopify, or null if Bookkeep cannot find the name. subtotal, tax_amount and total are calculated from the lines. Each returned line has an id, which PATCH takes to change that line, and a variant_supplier_cost.

Send an Idempotency-Key header to make retries safe. A repeat with the same key and the same purchase_order body returns the purchase order already created, with HTTP 200, instead of creating a second one. "The same body" means the same JSON values; the order of keys does not matter. The repeat returns the original even if your store's products have changed since, so a SKU that would no longer match does not fail the retry. Reusing a key with a different body (any changed value, including metadata, or the same value sent as a different type, such as "10" instead of 10) returns 422; use a new key for a new purchase order. A key first used before this check was added replays as it always has, whatever the body.

Request

Responses

200

The Idempotency-Key was already used with the same body, so the purchase order it created is returned instead of a duplicate.

201

Purchase order created.

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. Create and manage keys under Settings → API keys in the Bookkeep section of the Bookkeep app.

403

The key does not hold purchase_orders:write, or the key's store is not linked to {entity_id}.

409

The purchase order clashed with one being saved at the same moment, and no Idempotency-Key header was sent. Nothing was created; send the request again. Send an Idempotency-Key so that a retry can never create a duplicate.

413

Request body exceeds the 1 MB limit.

422

Validation error: a missing or invalid currency or destination_location_id, a supplier_name that matches no supplier or several, a sku that matches no product or several, a client_line_id sent on more than one line, an Idempotency-Key reused with a different body, 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.

429

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.

504

The service did not respond in time. The purchase order may or may not have been created. Retry with the same Idempotency-Key so a retry cannot create a duplicate.