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.

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	GET	/purchase_orders	Returns one page of purchase orders.
Create a purchase order	POST	/purchase_orders	Creates a purchase order for a supplier and returns it under purchase_order.
List notes across purchase orders	GET	/purchase_orders/notes	Returns one page of notes from every purchase order.
Delete a purchase order	DELETE	/purchase_orders/{purchase_order_id}	Deletes a purchase order. Nothing comes back.
Update a purchase order	PATCH	/purchase_orders/{purchase_order_id}	Changes header fields of a purchase order and returns it under purchase_order.
Retrieve a purchase order	GET	/purchase_orders/{purchase_order_id}	Returns one purchase order under purchase_order.
Cancel a purchase order	POST	/purchase_orders/{purchase_order_id}/cancel	Cancels a purchase order and returns it under purchase_order.
Change a purchase order’s lines	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	GET	/purchase_orders/{purchase_order_id}/information	Returns the header information of one purchase order under purchase_order.
List a purchase order’s lines	GET	/purchase_orders/{purchase_order_id}/lines	Returns one page of the lines of a purchase order.
List a purchase order’s notes	GET	/purchase_orders/{purchase_order_id}/notes	Returns one page of the notes on a purchase order.
Create a purchase order note	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	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	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	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	POST	/purchase_orders/{purchase_order_id}/reactivate	Reactivates a cancelled purchase order and returns it under purchase_order.
Retrieve a purchase order line	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	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	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	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	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	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	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. 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.