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

# Purchase orders

> Create, change, cancel and read purchase orders, their lines, notes, files and KPIs, and the purchase invoices and payments raised from them.

A purchase order records what you are buying from a supplier. These endpoints create, update, change, cancel and reactivate purchase orders, read their lines, KPIs, purchase invoices and payments, and manage their notes and attached files. This area has 23 endpoints, each available in all seven SDKs.

> [!WARNING]
>
> **Deleting a purchase order or a note cannot be undone.** Cancel a purchase order instead if you may need it again.

## At a glance

| Endpoint | Method | Path | What it does |
| - | - | - | - |
| [List purchase orders](https://exsited.mintlify.site/api-reference/purchase-orders/list-purchase-orders.md) | GET | `/purchase_orders` | Returns one page of purchase orders. |
| [Create a purchase order](https://exsited.mintlify.site/api-reference/purchase-orders/create-a-purchase-order.md) | POST | `/purchase_orders` | Creates a purchase order for a supplier and returns it under `purchase_order`. |
| [List notes across purchase orders](https://exsited.mintlify.site/api-reference/purchase-orders/list-notes-across-purchase-orders.md) | GET | `/purchase_orders/notes` | Returns one page of notes from every purchase order. |
| [Delete a purchase order](https://exsited.mintlify.site/api-reference/purchase-orders/delete-a-purchase-order.md) | DELETE | `/purchase_orders/{purchase_order_id}` | Deletes a purchase order. Nothing comes back. |
| [Update a purchase order](https://exsited.mintlify.site/api-reference/purchase-orders/update-a-purchase-order.md) | PATCH | `/purchase_orders/{purchase_order_id}` | Changes header fields of a purchase order and returns it under `purchase_order`. |
| [Retrieve a purchase order](https://exsited.mintlify.site/api-reference/purchase-orders/retrieve-a-purchase-order.md) | GET | `/purchase_orders/{purchase_order_id}` | Returns one purchase order under `purchase_order`. |
| [Cancel a purchase order](https://exsited.mintlify.site/api-reference/purchase-orders/cancel-a-purchase-order.md) | POST | `/purchase_orders/{purchase_order_id}/cancel` | Cancels a purchase order and returns it under `purchase_order`. |
| [Change a purchase order's lines](https://exsited.mintlify.site/api-reference/purchase-orders/change-a-purchase-orders-lines.md) | POST | `/purchase_orders/{purchase_order_id}/change` | Adds or changes lines on a purchase order and returns it under `purchase_order`. |
| [Retrieve a purchase order's information](https://exsited.mintlify.site/api-reference/purchase-orders/retrieve-a-purchase-orders-information.md) | GET | `/purchase_orders/{purchase_order_id}/information` | Returns the header information of one purchase order under `purchase_order`. |
| [List a purchase order's lines](https://exsited.mintlify.site/api-reference/purchase-orders/list-a-purchase-orders-lines.md) | GET | `/purchase_orders/{purchase_order_id}/lines` | Returns one page of the lines of a purchase order. |
| [List a purchase order's notes](https://exsited.mintlify.site/api-reference/purchase-orders/list-a-purchase-orders-notes.md) | GET | `/purchase_orders/{purchase_order_id}/notes` | Returns one page of the notes on a purchase order. |
| [Create a purchase order note](https://exsited.mintlify.site/api-reference/purchase-orders/create-a-purchase-order-note.md) | POST | `/purchase_orders/{purchase_order_id}/notes` | Adds a note, with an optional file, to a purchase order and returns it under `note`. |
| [Create a purchase invoice from a purchase order](https://exsited.mintlify.site/api-reference/purchase-orders/create-a-purchase-invoice-from-a-purchase-order.md) | POST | `/purchase_orders/{purchase_order_id}/purchase_invoices` | Raises a purchase invoice for a purchase order and returns it under `purchase_invoice`. |
| [List a purchase order's purchase invoices](https://exsited.mintlify.site/api-reference/purchase-orders/list-a-purchase-orders-purchase-invoices.md) | GET | `/purchase_orders/{purchase_order_id}/purchase_invoices` | Returns one page of the purchase invoices raised from a purchase order. |
| [List a purchase order's purchase payments](https://exsited.mintlify.site/api-reference/purchase-orders/list-a-purchase-orders-purchase-payments.md) | GET | `/purchase_orders/{purchase_order_id}/purchase_payments` | Returns one page of the purchase payments made against a purchase order's invoices. |
| [Reactivate a purchase order](https://exsited.mintlify.site/api-reference/purchase-orders/reactivate-a-purchase-order.md) | POST | `/purchase_orders/{purchase_order_id}/reactivate` | Reactivates a cancelled purchase order and returns it under `purchase_order`. |
| [Retrieve a purchase order line](https://exsited.mintlify.site/api-reference/purchase-orders/retrieve-a-purchase-order-line.md) | GET | `/purchase_orders/{purchase_order_id}/lines/{purchase_order_line_uuid}` | Returns one line of a purchase order under `purchase_order_line`. |
| [Delete a purchase order note](https://exsited.mintlify.site/api-reference/purchase-orders/delete-a-purchase-order-note.md) | DELETE | `/purchase_orders/{purchase_order_id}/notes/{purchase_order_note_id}` | Deletes a note from a purchase order. Nothing comes back. |
| [Retrieve a purchase order note](https://exsited.mintlify.site/api-reference/purchase-orders/retrieve-a-purchase-order-note.md) | GET | `/purchase_orders/{purchase_order_id}/notes/{purchase_order_note_id}` | Returns one note of a purchase order under `note`. |
| [List a purchase order note's files](https://exsited.mintlify.site/api-reference/purchase-orders/list-a-purchase-order-notes-files.md) | GET | `/purchase_orders/{purchase_order_id}/notes/{purchase_order_note_id}/files` | Returns the files attached to one purchase order note. |
| [Retrieve a purchase order note file](https://exsited.mintlify.site/api-reference/purchase-orders/retrieve-a-purchase-order-note-file.md) | GET | `/purchase_orders/{purchase_order_id}/notes/{purchase_order_note_id}/files/{purchase_order_file_id}` | Returns the details of one file attached to a purchase order note, under `file`. |
| [Retrieve a purchase order's KPIs](https://exsited.mintlify.site/api-reference/purchase-orders/retrieve-a-purchase-orders-kpis.md) | GET | `/purchase_orders/{purchase_order_id}/kpis` | Returns the KPI figures of one purchase order under `purchase_order_kpis`. |
| [Delete a purchase order note file](https://exsited.mintlify.site/api-reference/purchase-orders/delete-a-purchase-order-note-file.md) | DELETE | `/purchase_orders/{purchase_order_id}/notes/{purchase_order_note_id}/files/{purchase_order_file_id}` | Removes one attachment from a purchase order note. Nothing comes back. |

## Before you call

Register your API credentials once when your app starts, as shown in
[Authentication](https://exsited.mintlify.site/authentication.md). Every SDK sample on these pages then gets its client in one line.
With cURL, send the access token in an `Authorization` header: `Authorization: Bearer $ACCESS_TOKEN`.

## Things to know

* **Every JSON write body is wrapped in `purchase_order`.** The exceptions are the purchase invoice create, wrapped in `purchase_invoice`, and the note create, a multipart form; the cancel and reactivate calls take an empty object.
* **The note calls take the purchase order's `code`, not its `id`.** That covers listing, creating, reading and deleting notes and their files.
* **A new purchase order is `active`.** Send `"draft": true` in the create body to save it as a draft instead.
* **Cancelling sets the status to `inactive`.** Reactivating sets it back to `active`.
* **Listings page by cursor.** Records are under `data`; pass `pagination.next_cursor` as `cursor` while `pagination.has_more` is `true`.
* **Notes are created as a multipart form.** The text goes in the `note` field, and a file is optional.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.