> ## Documentation Index
> Fetch the complete documentation index at: https://docs.printools.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchase orders

> Raising POs, receiving stock, and derived statuses.

Use the operations below to work with purchase orders. Each link opens an interactive reference page generated from the published OpenAPI specification.

## Receiving preconditions

Receiving and undoing receipts require an active purchase order in `Sent`, `PartiallyReceived`, or `Received`. Within this window, the header status is derived from its lines. Pending and other pre-send purchase orders cannot receive stock; a direct line receipt returns a precondition error, while a bulk receipt reports the refused order in its outcomes. An HTTP `201` with `affected: 0` is not a successful receipt.

Sending a purchase order may notify a supplier. Do not send one merely to test receiving against a live shop.

## Operations

| Operation                                                                                                                                                                    | Method and path                                                   | Required scopes                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------- |
| [List purchase orders](/api/reference/get_v1_purchase_orders)                                                                                                                | `GET /v1/purchase-orders`                                         | `purchaseorders.read`                  |
| [Create a purchase order](/api/reference/post_v1_purchase_orders)                                                                                                            | `POST /v1/purchase-orders`                                        | `purchaseorders.write`                 |
| [One purchase order with its lines](/api/reference/get_v1_purchase_orders_purchaseOrderId)                                                                                   | `GET /v1/purchase-orders/{purchaseOrderId}`                       | `purchaseorders.read`                  |
| [Update a purchase order](/api/reference/patch_v1_purchase_orders_purchaseOrderId)                                                                                           | `PATCH /v1/purchase-orders/{purchaseOrderId}`                     | `purchaseorders.write`                 |
| [Archive a purchase order](/api/reference/post_v1_purchase_orders_purchaseOrderId_archive)                                                                                   | `POST /v1/purchase-orders/{purchaseOrderId}/archive`              | `purchaseorders.write`                 |
| [Restore an archived purchase order](/api/reference/post_v1_purchase_orders_purchaseOrderId_unarchive)                                                                       | `POST /v1/purchase-orders/{purchaseOrderId}/unarchive`            | `purchaseorders.write`                 |
| [Add a line to a purchase order](/api/reference/post_v1_purchase_orders_purchaseOrderId_lines)                                                                               | `POST /v1/purchase-orders/{purchaseOrderId}/lines`                | `purchaseorders.write`                 |
| [Update a purchase-order line](/api/reference/patch_v1_purchase_order_lines_lineId)                                                                                          | `PATCH /v1/purchase-order-lines/{lineId}`                         | `purchaseorders.write`                 |
| [Delete a purchase-order line](/api/reference/delete_v1_purchase_order_lines_lineId)                                                                                         | `DELETE /v1/purchase-order-lines/{lineId}`                        | `purchaseorders.write`                 |
| [Record a receipt against a purchase-order line](/api/reference/post_v1_purchase_order_lines_lineId_receive)                                                                 | `POST /v1/purchase-order-lines/{lineId}/receive`                  | `purchaseorders.write`                 |
| [Attach a vendor to a purchase order](/api/reference/post_v1_purchase_orders_purchaseOrderId_vendors_vendorId)                                                               | `POST /v1/purchase-orders/{purchaseOrderId}/vendors/{vendorId}`   | `purchaseorders.write`, `vendors.read` |
| [Detach a vendor from a purchase order](/api/reference/delete_v1_purchase_orders_purchaseOrderId_vendors_vendorId)                                                           | `DELETE /v1/purchase-orders/{purchaseOrderId}/vendors/{vendorId}` | `purchaseorders.write`, `vendors.read` |
| [Receive every purchase-order line matching a target](/api/reference/post_v1_purchase_orders_bulk_receive)                                                                   | `POST /v1/purchase-orders/bulk/receive`                           | `purchaseorders.write`                 |
| [Set the status of every purchase order matching a target. Derived statuses are refused, see GET /v1/reference/statuses](/api/reference/post_v1_purchase_orders_bulk_status) | `POST /v1/purchase-orders/bulk/status`                            | `purchaseorders.write`                 |
| [Archive or restore every purchase order matching a target](/api/reference/post_v1_purchase_orders_bulk_archive)                                                             | `POST /v1/purchase-orders/bulk/archive`                           | `purchaseorders.write`                 |

See [Authentication](/api/authentication) before your first call. For write retries, see [Writing safely](/api/idempotency).