Create Purchase Invoice for a Purchase Order: /purchase-orders/{purchase_order_id}/purchase-invoices

Purpose

This API creates a new purchase invoice associated with an existing purchase order. It enables businesses to generate invoices for goods or services received, define billing dates, and capture key financial details such as currency, totals, and optional custom attributes.  This endpoint ensures that invoices are generated accurately and tied directly to the correct purchase order.

Use Case

This endpoint is used when vendors deliver goods or complete services for a purchase order, and the finance or procurement team needs to create an official purchase invoice linked to that order. It supports workflows such as defining issue and due dates, recording monetary totals, and adding custom attributes like internal notes or vendor-specific metadata. By integrating invoice creation directly with purchase orders, organizations streamline the procurement-to-payment process, ensuring invoices are properly tracked, validated, and aligned with supplier transactions.

Path Parameters

Query Parameters

This endpoint does not have any query parameters.

Request Body

Response

Upon successful creation, the API returns a detailed purchase invoice object containing all relevant metadata and financial information. This includes invoice identifiers, status, currency details, issue and due dates, subtotal, tax, total amount, and the associated purchase order ID. Line items are provided with granular details such as subtotals, totals, tax values, accounting codes, item quantities, and warehouse allocations. KPIs summarize financial tracking metrics including outstanding balances, overdue amounts, and payment application. Metadata such as creator, timestamps, versioning, and custom attributes are also included. The response confirms that the invoice has been successfully generated, linked to the original purchase order, and recorded in the accounting system for further processing and payment tracking.

Response Body

Create Purchase Invoice Note: /purchase-invoices/{purchase_invoice_id}/notes

Purpose

This API is used to create a new note for a specific purchase invoice. Notes can include textual content and optionally one or more attached files (such as documents, images, or receipts). This allows for richer record-keeping, collaboration, and audit tracking against purchase invoices.

Use Case

• Attach internal comments, remarks, or explanations to a purchase invoice.
• Add supporting documents (e.g., scanned receipts, invoices, or approvals).
• Maintain a chronological audit trail of discussions and actions tied to the invoice.
• Enable collaboration between finance, procurement, and auditing teams.

Path Parameters

Query Parameters

No query parameters required for this endpoint.

Request Body

Format: multipart/form-data

Response

On success, the API returns a JSON object containing the purchase-invoice object with a notes property. The notes object provides the UUID of the newly created note, which can later be used to retrieve, update, or delete that note. This ensures each note is uniquely identifiable for tracking and reference.

Response Body

Cancel Purchase Invoice: /purchase-invoices/{purchase_invoice_id}/cancel

Purpose

This API is used to cancel an existing purchase invoice within the system. It allows users to mark an invoice as canceled when it is no longer valid due to a change in transaction, duplicate entry, or correction of billing errors. Once canceled, the purchase invoice will not be processed further for payment or reporting but will remain in the system for audit and record-keeping purposes.

Use Case

A finance or accounts payable officer can use this API to cancel a purchase invoice when a supplier withdraws an issued invoice, an incorrect invoice was generated, or goods or services associated with the invoice have been returned. This helps maintain accurate financial records and prevents payment of invalid or duplicate invoices.

Path Parameters

Query Parameters

This endpoint does not have any query parameters.

Request Body

Response

If the request is successful, the API returns a 202 Accepted response, indicating that the purchase invoice cancellation request has been received and is being processed asynchronously. The response body includes a unique event UUID, which can be used to track the progress or status of the cancellation event. This ensures that users can verify that the invoice cancellation was properly initiated within the system and completed through background processing.

Response Body

Reactivate Purchase Invoice: /purchase-invoices/{purchase_invoice_id}/reactivate

Purpose

This API is used to reactivate a previously canceled or inactive purchase invoice. It allows users to restore an invoice to an active state when the cancellation was made in error or when the invoice becomes valid again due to a change in business circumstances. Reactivating a purchase invoice ensures that it can once again participate in payment processing, reporting, and accounting operations.

Use Case

A finance or accounts payable officer can use this API to reactivate a purchase invoice if a cancellation request was issued incorrectly or if the supplier has revalidated the invoice after dispute resolution. This action restores the invoice’s lifecycle, enabling it to be paid, amended, or used in financial reconciliations.

Path Parameters

Query Parameters

This endpoint does not have any query parameters.

Request Body

Response

If the request is successful, the API returns a 202 Accepted response, confirming that the purchase invoice reactivation request has been received and is being processed asynchronously. The response body includes a unique event UUID, which can be used to track the progress or completion of the reactivation event. This ensures that the invoice’s active status can be verified through subsequent event or status queries in the system.

Response Body

Upload Files to a Purchase Invoice Note: /purchase-invoices/{id}/notes/{uuid}/files

Purpose

Upload one or more files to an existing note on a purchase invoice, with the ability to update the note content simultaneously. This endpoint accepts multipart form-data, allowing consumers to attach multiple files in a single request by repeating the file field. The optional note field can be used to update the text content of the note at the same time as the file upload, eliminating the need for a separate PATCH call. This is particularly useful for workflows where supporting documentation and contextual annotations need to be added together as part of an invoice processing step.

Use Case

This endpoint allows you to attach supporting documents such as invoices, receipts, and contracts to an invoice note. It supports uploading multiple files in a single request to an existing note, and can also update the note content while attaching new files. Common use cases include attaching scanned copies of physical invoices, delivery confirmation documents, or approval sign-off records as part of the accounts payable workflow. Collaboration teams use this endpoint to consolidate evidence and documentation onto a single note, creating a centralized reference point for all stakeholders reviewing the invoice. It also supports automated document collection scenarios where an integration system gathers files from multiple sources and uploads them in bulk to the appropriate invoice note for audit readiness.

Path Parameters

Query Parameters

No query parameters required.

Request Body (form-data)

Request Attributes

Response

Returns the updated note object with the newly attached files and refreshed metadata. The response includes the note's UUID, updated content (reflecting any changes passed in the note field), and the complete files array containing both previously existing and newly uploaded files, each with their UUID, name, and version. The last_updated_by and last_updated_on fields are updated to reflect the user who performed the upload and the timestamp of the operation, while created_by and created_on retain the original note creation details. The version field is incremented to reflect the modification, supporting optimistic concurrency control for subsequent updates to the same note.

Response Body

Create a Purchase Invoice: /purchase-invoices

Purpose

Create a new purchase invoice in the system. A purchase invoice represents a bill received from a supplier for goods or services, and serves as the basis for tracking payables, managing payment schedules, and reconciling supplier accounts. This endpoint accepts the full invoice payload including header-level fields such as dates, currency, and account reference, as well as one or more line items with pricing, quantity, tax, and accounting code details. Upon successful creation, the system returns the complete invoice object with generated identifiers, computed financial totals, and initialized KPI metrics.

Use Case

This endpoint is used to record a new purchase invoice against a supplier account. It is commonly used in accounts payable workflows to capture incoming supplier bills, either manually entered or imported from external systems. Procurement teams use this endpoint after receiving goods or services to create the corresponding invoice that triggers the payment process. It supports integration scenarios where an ERP or document management system extracts invoice data from scanned documents or electronic invoices and submits them programmatically. The endpoint also supports linking the invoice to an existing purchase order via the purchaseOrderId field, enabling three-way matching between the purchase order, item receipt, and invoice. Finance teams rely on the returned KPI fields to immediately assess the outstanding and overdue status of the newly created invoice within the context of the supplier relationship.

Path Parameters

No path parameters required.

Query Parameters

No query parameters required.

Request Body