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
| Parameter | Type | Description |
|---|---|---|
| purchase_order_id | String | Unique identifier of the purchase order for which the purchase invoice is being created. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
{
"purchase_invoice": {
"issue_date": "invoice_issue_date",
"due_date": "invoice_due_date",
"purchase_order_note": "optional_note",
"custom_attributes": [
{
"name": "attribute_name",
"value": "attribute_value"
}
]
}
}
| Attribute | Type | Description |
|---|---|---|
| purchase_invoice | Object | Root object containing details of the new purchase invoice. |
| issue_date | String | Date the invoice is issued (format: YYYY-MM-DD). |
| due_date | String | Date the invoice is due for payment (format: YYYY-MM-DD). |
| purchase_order_note | String | Optional note or remark associated with the purchase order invoice. |
| custom_attributes | Array | Optional list of custom attributes for additional metadata. |
| name | String | Name of the custom attribute. |
| value | String | Value of the custom attribute. |
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
{
"purchase_invoice": {
"status": "status",
"id": "invoice_id",
"origin": "",
"custom_form": {
"uuid": "form_uuid",
"name": "form_name"
},
"currency": {
"id": "currency_id",
"name": "currency_name",
"link": {
"rel": "self",
"href": "currency_api_link"
}
},
"issue_date": "issue_date",
"alternate_issue_date": "alternate_issue_date",
"due_date": "due_date",
"alternate_due_date": "alternate_due_date",
"subtotal": "subtotal_amount",
"tax": "tax_amount",
"total": "total_amount",
"price_tax_inclusive": "true_or_false",
"account_id": "account_id",
"purchase_order_id": "purchase_order_id",
"created_by": "creator_name",
"created_on": "creation_timestamp",
"last_updated_by": "last_updated_by",
"last_updated_on": "last_updated_on",
"uuid": "invoice_uuid",
"version": "version_number",
"custom_attributes": [],
"custom_objects": [],
"lines": [
{
"subtotal": "line_subtotal",
"total": "line_total",
"tax": "line_tax",
"accounting_code": "accounting_code",
"item_uuid": "item_uuid",
"item_purchase_order_quantity": "item_quantity",
"item_uom": "unit_of_measure",
"item_warehouse": "warehouse_name",
"uuid": "line_uuid",
"version": "line_version"
}
],
"kpis": {
"outstanding": "outstanding_amount",
"overdue": "overdue_amount",
"last_payment_date": "last_payment_date",
"payment_applied": "applied_payment_amount",
"credit_applied": "applied_credit_amount",
"credit_issued": "issued_credit_amount",
"last_reactivated_on": "last_reactivated_timestamp",
"last_cancelled_on": "last_cancelled_timestamp",
"last_amended_on": "last_amended_timestamp",
"voided_on": "voided_timestamp",
"deleted_on": "deleted_timestamp"
}
}
}
| Attribute | Type | Description |
|---|---|---|
| purchase_invoice | Object | Root object containing full details of the created purchase invoice. |
| status | String | Current status of the purchase invoice (example: ACTIVE). |
| id | String | Unique system-generated purchase invoice ID. |
| origin | String | Indicates the source or origin of the purchase invoice, if applicable. |
| custom_form | Object | Contains metadata about the custom form used for this invoice. |
| uuid | String | UUID of the form associated with the purchase invoice. |
| name | String | Name of the associated custom form. |
| currency | Object | Information about the currency used in the invoice. |
| id | String | Unique ID of the currency. |
| name | String | Name of the currency (example: AUD). |
| link | Object | API link to currency details. |
| issue_date | String | Date when the invoice was issued. |
| alternate_issue_date | String | Alternate issue date for billing alignment. |
| due_date | String | Date when payment for the invoice is due. |
| alternate_due_date | String | Alternate due date, if applicable. |
| subtotal | String | Subtotal amount before taxes. |
| tax | String | Tax amount applied to the invoice. |
| total | String | Total invoice amount after taxes. |
| price_tax_inclusive | Boolean | Indicates whether prices include tax (true or false). |
| account_id | String | Identifier of the account associated with this invoice. |
| purchase_order_id | String | Identifier of the linked purchase order. |
| created_by | String | User who created the purchase invoice. |
| created_on | String | Timestamp when the invoice was created. |
| last_updated_by | String | Name of the user who last updated the invoice. |
| last_updated_on | String | Timestamp of the last invoice update. |
| uuid | String | Unique system UUID for the purchase invoice. |
| version | String | Version number of the purchase invoice record. |
| lines | Array | List of line items associated with the purchase invoice. |
| subtotal | String | Subtotal for the line item. |
| total | String | Total for the line item after taxes. |
| tax | String | Tax amount for the line item. |
| accounting_code | String | Accounting code used for the item. |
| item_uuid | String | UUID of the purchased item. |
| item_purchase_order_quantity | String | Quantity of the item in the purchase order. |
| item_uom | String | Unit of measurement for the item. |
| item_warehouse | String | Name of the warehouse associated with the item. |
| uuid | String | Unique identifier for the line record. |
| version | String | Version of the line record. |
| kpis | Object | Key performance indicators related to the purchase invoice. |
| outstanding | Number | Outstanding payment amount. |
| overdue | Number | Amount overdue for payment. |
| last_payment_date | String | Date of the last payment. |
| payment_applied | Number | Amount of payment applied to this invoice. |
| credit_applied | Number | Credit amount applied to this invoice. |
| credit_issued | String | Total credit issued. |
| last_reactivated_on | String | Timestamp when the invoice was last reactivated. |
| last_cancelled_on | String | Timestamp when the invoice was last cancelled. |
| last_amended_on | String | Timestamp when the invoice was last amended. |
| voided_on | String | Timestamp when the invoice was voided. |
| deleted_on | String | Timestamp when the invoice was deleted. |
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
| Parameter | Type | Description |
|---|---|---|
| purchase_invoice_id | string | Unique identifier of the purchase invoice to which the note will be added. |
Query Parameters
No query parameters required for this endpoint.
Request Body
Format: multipart/form-data
| Attribute | Type | Description |
|---|---|---|
| note | string | Content of the note. |
| file | file | File to attach with the note. Accepts common document and image formats. Optional if only text is required |
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
{
"purchase-invoice": {
"notes": {
"uuid": "NOTE_UUID"
}
}
}
| Attribute | Type | Description |
|---|---|---|
| purchase-invoice | object | Root object representing the purchase invoice. |
| notes | object | Container for the note metadata. |
| uuid | string (UUID) | Unique identifier of the newly created note. |
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
| Parameter | Type | Description |
|---|---|---|
| purchase_invoice_id | String | Unique identifier of the purchase invoice to be canceled. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
{
"purchase-invoice": {
"effective_date": "effective_date"
}
}
| Attribute | Type | Description |
|---|---|---|
| purchase-invoice | Object | Root object containing cancellation details of the purchase invoice. |
| effective_date | String | The effective date on which the purchase invoice cancellation should take place (format: YYYY-MM-DD). |
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
{
"event_uuid": "event_uuid"
}
| Attribute | Type | Description |
|---|---|---|
| event_uuid | String | Unique identifier of the event triggered for the purchase invoice cancellation process. |
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
| Parameter | Type | Description |
|---|---|---|
| purchase_invoice_id | String | Unique identifier of the purchase invoice to be canceled. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
{
"purchase-invoice": {
"effective_date": "effective_date"
}
}
| Attribute | Type | Description |
|---|---|---|
| purchase-invoice | Object | Root object containing details required to reactivate the purchase invoice. |
| effective_date | String | The effective date on which the reactivation of the purchase invoice takes place (format: YYYY-MM-DD). |
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
{
"event_uuid": "event_uuid"
}
| Attribute | Type | Description |
|---|---|---|
| event_uuid | String | Unique identifier of the event triggered for the purchase invoice reactivation process. |