Retrieve Purchase Order List: /purchase-orders

Purpose

The purpose of this endpoint is to retrieve purchase orders created within the system, including their supplier linkage, currency details, item information, and financial summaries. It allows procurement and finance teams to monitor supplier transactions, validate order details, and ensure accurate tracking of purchase order lifecycles.

Use Case

This endpoint is used when organizations need to review purchase orders tied to supplier accounts. For example, after creating a supplier account and adding items with defined sales amounts and inventory, users can generate purchase orders. By calling this endpoint, teams can fetch those records to confirm order status, review item quantities and pricing snapshots, and assess financial obligations such as subtotals, taxes, and totals. It is particularly useful for procurement workflows, supplier management, and financial reporting.

Path Parameters

No path parameters required for this endpoint.

Query Parameters

*Here, eq = equal, ne = not equal, gt = greater than, ge = greater or equal, lt = less than, le = less or equal.*

Request Body

The endpoint does not require a request body.

Response

The response returns a structured list of purchase orders with comprehensive details. Each purchase order includes identifiers such as the purchase order ID and UUID, supplier account linkage, currency information, issue and due dates, and financial values like subtotal, tax, and total. Item-level details are provided, including item IDs, names, quantities, pricing rules, and tax configurations. Additionally, KPIs such as total expenses, outstanding amounts, overdue metrics, and invoice history are included to support financial analysis. Pagination metadata is also returned, showing record counts, limits, offsets, and navigation URLs to manage large datasets efficiently.

Response Body

Retrieve Purchase Order Details: /purchase-orders/{purchase_order_id}

Purpose

The purpose of this endpoint is to retrieve detailed information about a specific purchase order by its unique identifier. It allows to review the order’s metadata, supplier linkage, currency details, and financial values, ensuring accurate tracking and management of individual purchase orders.

Use Case

This endpoint is used to fetch comprehensive details of a single purchase order for auditing, supplier management, or financial reporting. By providing the purchase order ID, users can access information such as the supplier account, issue and due dates, subtotal, tax, and total amounts. It is particularly useful for validating supplier transactions, monitoring order lifecycles, and ensuring compliance with procurement processes.

Path Parameters

Response

The response returns a structured object containing the purchase order’s metadata and financial details. It includes the purchase order ID, status, supplier account ID, currency information, issue and due dates, expected completion date, and financial values such as subtotal, tax, and total. Additional metadata such as creation details, versioning, and custom form information are also provided. Unlike the list endpoint, this response does not include line items or KPIs, focusing instead on the high-level details of the specified purchase order.

Response Body

Retrieve Purchase Order Details: /purchase-orders/{purchase_order_id}/information

Purpose

Fetches detailed information about a specific purchase order by its unique ID. This includes metadata, financial details, currency used, and associated custom elements.

Use Case

This endpoint is used by procurement, finance, or integration systems to:

• Retrieve the latest data for a specific purchase order.
• View pricing breakdown and tax inclusion status.
• Display metadata (issue/due dates, creator, version).
• Reference currency and account details.
• Load custom attributes or objects linked to the purchase order.

Path Parameter

Query Parameter

No query parameters required for this endpoint.

Request Body

No request body is required for this endpoint.

Response

The response returns a single purchase order object that includes detailed information such as status, unique ID, currency, supplier invoice reference, and key dates like issue date, due date, and expected completion date. It also contains financial data such as subtotal, tax, total, and a flag indicating whether prices are tax inclusive. Additional metadata includes account ID, creator details, timestamps for creation and last update, a version number, and a system-generated UUID. Custom fields and linked objects are returned as empty arrays unless configured. The currency field includes its own metadata, including UUID, name, and a direct API link.

Response Body

Retrieve All Lines of a Purchase Order: /purchase-orders/{purchase_order_id}/lines

Purpose

The purpose of this endpoint is to retrieve all line items associated with a specific purchase order. Each line item provides detailed product, pricing, and tax-related information, enabling accurate purchase management, financial tracking, and auditing of item-level transactions.

Use Case

This endpoint is used to review or process the individual items included in a purchase order. It is commonly applied in procurement workflows to validate item quantities and costs, in invoicing systems to ensure accurate billing, in inventory management to update stock levels, and in financial reporting to analyze item-level expenses and tax configurations. By accessing this endpoint, teams gain visibility into the granular details of each product or service linked to a purchase order.

Path Parameters

Query Parameters

This endpoint does not accept any query parameters.

Request Body

No request body is required for this endpoint.

Response

The response returns a purchase order object containing a list of line items. Each line includes financial values such as subtotal, total, and tax, along with item-specific details like item ID, name, quantity, and pricing snapshots. Tax configurations are provided, including whether the purchase price is tax-inclusive, applicable tax codes, and exemption flags. Pricing rules capture metadata such as price type, unit price, warehouse, and versioning, ensuring that historical pricing logic is preserved. Accounting codes are also included to support integration with financial systems. This structure allows procurement and finance teams to process complex item-level data with full visibility into pricing and tax logic.

Response Body

Retrieve Specific Line Details of a Purchase Order: /purchase-orders/{purchase_order_id}/lines/{line_uuid}

Purpose

The purpose of this endpoint is to retrieve detailed information about a specific line item within a purchase order. It provides item-level financial values, pricing snapshots, tax configurations, and metadata, enabling precise tracking of procurement and accounting details.

Use Case

This endpoint is used to review or process the details of a single item included in a purchase order, identified by its unique line UUID. It is commonly applied in procurement analysis to validate item costs, in auditing to ensure compliance with tax rules, and in inventory tracking to confirm quantities and warehouse allocations. By accessing this endpoint, teams gain visibility into the granular financial and tax details of a specific purchase order line.

Path Parameters

Response

The response returns a purchase order object containing a single line item with comprehensive details. It includes financial values such as subtotal, total, and tax, along with metadata like item ID, name, and quantity. Pricing information is captured through a snapshot of the applied pricing rule, including the price type, unit price, warehouse, and versioning. Tax configuration details specify whether the purchase price is tax-inclusive, the applicable tax code, and exemption flags. Additional metadata such as purchase order notes, accounting codes, UUID, and versioning are also provided. This structure ensures that procurement and finance teams can accurately process and audit individual line items with full visibility into pricing and tax logic.

Response Body

Retrieve All Purchase Order of an Account: /accounts/{account_id}/purchase-orders

Purpose

The purpose of this endpoint is to retrieve all purchase orders associated with a specific supplier account. It provides detailed information about each order, including supplier linkage, currency details, item breakdowns, and financial metrics, enabling procurement and finance teams to manage account-level purchase activity effectively.

Use Case

This endpoint is used to review or process purchase orders tied to a particular account. It is commonly applied in procurement workflows to validate supplier transactions, in inventory management to track item quantities and pricing, and in financial reporting to analyze expenses, outstanding amounts, and overdue metrics. By accessing this endpoint, teams gain visibility into both order-level and item-level details, supporting efficient account and supplier management.

Path Parameters

Response

The response returns an account object containing a list of purchase orders linked to the specified account. Each purchase order includes metadata such as its ID, status, currency, supplier invoice reference, issue and due dates, expected completion date, and financial values like subtotal, tax, and total. Line items provide granular details including item IDs, names, quantities, pricing snapshots, and tax configurations, along with accounting codes for integration with financial systems. KPIs summarize operational and financial metrics such as total expenses, outstanding balances, overdue amounts, and invoice history. Pagination metadata is also included to support navigation across multiple purchase orders.

Response Body

Retrieve All Notes for a Purchase Order: /purchase-orders/{purchase_order_id}/notes

Purpose

Retrieve all notes linked to a specific purchase order, including their metadata, content, attached files, and audit information.

Use Case

• View all comments, remarks, or instructions logged against a purchase order.
• Access files (example: images, receipts, scanned approvals) attached to notes.
• Support collaboration and auditing for procurement processes.

Path Parameters

Query Parameters

Request Body

No data is required for the request body.

Response

On success, the API returns a purchase_order object containing a list of notes. Each note includes its unique identifier, version, content (HTML-supported), audit metadata (creator and timestamps), and any attached files. Pagination metadata is also provided to navigate through large result sets.

Response Body

Retrieve Specific Purchase Order Note: /purchase-orders/{purchase_order_id}/notes/{note_uuid}

Purpose

Retrieve details of a specific note within a purchase order by its UUID.

Use Case

• Fetch a single note for display or review.
• Access metadata and files associated with one note.

Path Parameters

Query Parameters

No query parameter is required for this endpoint.

Request Body

No request body is required for this endpoint.

Response

On success, the API returns the details of the specified note, including its unique identifier, version, content, files, and audit details.

Response Body

Retrieve Files for a Note: /purchase-orders/{purchase_order_id}/notes/{note_uuid}/files

Purpose

Retrieve all files attached to a specific note of a purchase order.

Use Case

• Fetch supporting documents linked to a note.
• Display file attachments associated with procurement notes.

Path Parameters

Query Parameters

No query parameter is required for the request body.

Request Body

No data is required for the request body.

Response

On success, the API returns a list of files attached to the given note, including their UUIDs, names, and versions.

Response Body

Retrieve a Specific File from a Note: /purchase-orders/{purchase_order_id}/notes/{note_uuid}/files/{file_uuid}

Purpose

Retrieve details of a specific file attached to a purchase order note.

Use Case

• Fetch metadata of a particular file.
• Verify attached file details before downloading or processing.

Path Parameters

Query Parameters

No query parameter is required for this endpoint.

Request Body

No data is required for the request body.

Response

On success, the API returns the file metadata, including its UUID, name, and version, within the note container.

Response Body

Retrieve a Specific Purchase Order Line Item: /purchase-orders/{id}/lines/{uuid}

Purpose

Retrieve the complete details of a specific line item within a purchase order using its UUID. Each line item represents a distinct product or service entry on the purchase order and contains comprehensive data including pricing information, tax configuration, quantity, accounting codes, and any custom attributes assigned to it. This endpoint provides a granular view of a single line item, allowing consumers to inspect the full pricing snapshot with unit price, discount, and unit of measure, as well as the tax rule applied. It is particularly useful when you need to access the detailed breakdown of one item without retrieving the entire purchase order payload.

Use Case

This endpoint is useful when you need to view pricing, quantity, and tax details for a single item on a purchase order. It can also be used to verify individual line item data before creating an invoice or item receipt, ensuring that the unit price, quantity, and tax rate are accurate prior to downstream document generation. Procurement teams commonly use this endpoint during reconciliation workflows to compare the ordered line item against what was actually received or invoiced. Additionally, it supports integration scenarios where an external system needs to pull specific line item details for reporting, cost allocation, or ERP synchronization. Auditors may also rely on this endpoint to inspect accounting codes and tax-exempt flags for compliance verification.

Path Parameters

Query Parameters

No query parameters required.

Response

Returns the details of the specified line item nested under the purchase_order object. The response includes a comprehensive breakdown organized into several key data groups: financial totals (subtotal, tax, and total), item identification (UUID, ID, and name), quantity and serial/batch information, and a full pricing snapshot containing the pricing rule with unit price, price type, and unit of measure. Tax configuration is provided as a separate nested object with the tax code, rate, and reference link. The response also includes the discount amount, accounting code, expected completion date, invoice note, and an array of custom attributes, giving consumers a complete picture of the line item in a single call.

Response Body

Retrieve Purchase Orders by Account: /accounts/{id}/purchase-orders

Purpose

Retrieve all purchase orders associated with a specific account (supplier). This endpoint provides an account-level view of purchasing activity, returning every purchase order linked to the given account ID along with key financial summaries and status information. It supports pagination through limit and offset query parameters, making it suitable for accounts with a large volume of orders. The response also includes KPI metrics such as total expense, estimated total, total outstanding, and total overdue, giving consumers a high-level financial overview of the supplier relationship in a single request.

Use Case

This endpoint allows you to view all purchase orders placed with a particular supplier. It is commonly used to generate account-level purchase order reports or to audit supplier purchasing history and outstanding orders. Supplier relationship managers can use it to assess the volume and value of transactions with a given vendor, identifying trends in spend over time. The built-in KPI fields make it straightforward to build dashboards that track outstanding and overdue amounts per supplier without additional calculations. It also supports account reconciliation workflows where finance teams need to cross-reference all purchase orders against invoices and payments for a specific supplier. Integration systems can paginate through the full set of orders to synchronize supplier data with external ERP or accounting platforms.

Path Parameters

Query Parameters

Response

Returns a list of purchase orders for the specified account with pagination metadata. Each purchase order in the array includes its status, human-readable ID, currency, issue and due dates, subtotal and total amounts, account ID, UUID, and an array of line items. The kpis object on each order provides aggregated financial metrics including total expense, estimated total, total outstanding, and total overdue, enabling quick supplier spend analysis without additional API calls. The pagination object at the root level contains the total record count, the current limit and offset values, and URLs for the previous and next pages, making it straightforward to iterate through large result sets programmatically.

Response Body

Retrieve a Specific Note for a Purchase Order: /purchase-orders/{id}/notes/{uuid}

Purpose

Retrieve the details of a specific note on a purchase order, including attached files and watcher information. This endpoint returns a single note identified by its UUID, providing the full HTML content, a list of all files attached to that note with their UUIDs and version numbers, and the complete watcher list broken down by internal and external participants. It is designed for scenarios where you already know which note you need and want to retrieve its complete details without fetching the entire notes collection. The response also includes creation and update audit fields, the note version for optimistic concurrency control, and any custom attributes assigned to the note.

Use Case

This endpoint lets you view a specific note's content and attached files. It is helpful for checking who is watching a particular note, including both internal and external watchers, and for retrieving file references attached to a note for download. Teams commonly use this when they need to deep-link to a specific note from an external system, such as a ticketing or project management tool, and display its full context. It also supports file download preparation workflows where the consumer first retrieves the note to obtain file UUIDs and names before initiating individual file downloads. For audit and compliance purposes, the watcher list provides a clear record of which internal users and external contacts had visibility into the specific communication thread.

Path Parameters

Query Parameters

No query parameters required.

Response

Returns the details of the specified note as a single object nested under the purchase_order wrapper. The note object includes its UUID, HTML-formatted content, and a files array where each file entry contains a UUID, name, and version number suitable for subsequent file retrieval calls. Audit metadata is provided through created_by, created_on, last_updated_by, and last_updated_on fields, along with a version field for tracking changes. The watcherList object separates watchers into internal_watchers (identified by email) and external_watchers (identified by email and account ID), providing full visibility into notification recipients for the note.

Response Body

Retrieve All Files for a Purchase Order Note: /purchase-orders/{id}/notes/{uuid}/files

Purpose

Retrieve all files attached to a specific note on a purchase order. This endpoint returns the complete list of file attachments for a given note, identified by the purchase order ID and note UUID. Each file in the response includes its UUID, name, and version number, providing the metadata needed to reference or download individual files. It is a focused endpoint that returns only the file-related data from the note, making it efficient for scenarios where the note content and watcher information are not needed.

Use Case

This endpoint is used to list all file attachments on a purchase order note. It helps identify files for bulk download or processing, and can be used to verify that file uploads were successful after adding files to a note. Document management workflows benefit from this endpoint by providing a quick inventory of all attachments without needing to parse the full note content or watcher details. It is also useful in batch processing scenarios where an integration system needs to enumerate all files on a note, collect their UUIDs, and then download or archive them sequentially. Quality assurance teams can use it to confirm that the expected number of supporting documents have been attached before advancing the purchase order through an approval workflow.

Path Parameters

Query Parameters

No query parameters required.

Response

Returns the list of files attached to the specified note as an array nested within the purchase_order.note object. Each file entry in the array contains a uuid for unique identification, a name field with the file's identifier, and a version number that increments when the file is updated. The response also includes the note's watcherList (with empty internal and external watcher arrays when no watchers are configured) and custom_attributes array, though the primary payload is the files collection. This structure allows consumers to iterate over the files array and use each file's UUID to make subsequent calls to the individual file retrieval endpoint.

Response Body

Retrieve a Specific File for a Purchase Order Note: /purchase-orders/{id}/notes/{uuid}/files/{uuid}

Purpose

Retrieve the details of a specific file attached to a purchase order note. This endpoint returns the metadata for a single file identified by its UUID within the context of a specific note and purchase order. The response includes the file's UUID, name, and version number, which together provide the information needed to verify the file's identity and track changes over time. It is a targeted endpoint designed for retrieving one file's metadata without loading the entire files collection or the parent note's content.

Use Case

This endpoint is used to get metadata for a specific file attachment on a purchase order note. It allows you to verify a specific file's version and identity before initiating a download, ensuring that the correct revision of the document is being retrieved. It is commonly used in integration workflows where an external system needs to confirm a file's existence and version before pulling it into a document management system or archival platform. The version tracking capability supports scenarios where files may be updated over time, allowing consumers to detect whether a newer version is available since their last retrieval. Audit workflows also benefit from this endpoint by providing a verifiable record of which specific file version was associated with a purchase order note at any point in time.

Path Parameters

Query Parameters

No query parameters required.

Response

Returns the metadata of the specified file as a single object nested under the purchase_order.note wrapper. The file object contains the file's uuid for unique identification, the name field with the file's identifier, and a version number that tracks revisions. The response also includes the parent note's watcherList and custom_attributes for context, though the primary payload is the individual file object. This structure is consistent with the multi-file listing endpoint, making it straightforward to handle both single and bulk file retrieval responses with the same client logic.

Response Body