Create Purchase Order: /purchase-orders
Purpose
This API creates a new purchase order for an organization. A purchase order includes supplier account details, items with pricing and tax configuration, and optional metadata such as custom attributes and notes. It supports creation of the purchase order, order invoice, and purchase invoice, instead of requiring references to existing records by ID.
Use Case
When a user creates a new purchase order from the procurement dashboard, the frontend calls this endpoint with the order details. A supplier account is required, either by providing an existing account_id. At least one item is required, identified by item_id or item_uuid. The purchase order id and invoice id (if creating an invoice alongside) are also required fields. The system validates the payload, provisions the purchase order, and returns the complete order record with calculated totals, tax amounts, and generated UUIDs.
Path Parameters
No path parameters required for this endpoint.
Query Parameters
No query parameters required for this endpoint.
Request Body
{
"purchase_order": {
"id": "PURCHASE_ORDER_ID",
"name": "PURCHASE_ORDER_NAME",
"display_name": "DISPLAY_NAME",
"description": "DESCRIPTION",
"supplier_invoice_id": "SUPPLIER_INVOICE_ID",
"origin": "ORIGIN",
"issue_date": "YYYY-MM-DD",
"due_date": "YYYY-MM-DD",
"expected_completion_date": "YYYY-MM-DD",
"price_tax_inclusive": "true",
"purchase_order_note": "PURCHASE_ORDER_NOTE",
"account_id": "ACCOUNT_ID",
"account": {
"name": "ACCOUNT_NAME",
"type": "SUPPLIER"
},
"currency": "CURRENCY_CODE",
"custom_form": "CUSTOM_FORM",
"custom_attributes": [
{
"key": "ATTRIBUTE_KEY",
"value": "ATTRIBUTE_VALUE"
}
],
"lines": [
{
"item_id": "ITEM_ID",
"item_uuid": "ITEM_UUID",
"item_name": "ITEM_NAME",
"item_invoice_note": "ITEM_INVOICE_NOTE",
"item_description": "ITEM_DESCRIPTION",
"item_quantity": "QUANTITY",
"item_order_quantity": "ORDER_QUANTITY",
"discount_amount": "DISCOUNT_AMOUNT",
"rate_option": "RATE_OPTION",
"isTaxExemptWhenSold": "true",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE",
"warehouse": "WAREHOUSE_NAME",
"uom": "UNIT_OF_MEASURE",
"pricing_level": "PRICING_LEVEL"
}
},
"item_price_tax": {
"uuid": "TAX_UUID",
"code": "TAX_CODE",
"rate": "TAX_RATE"
},
"item_properties": {
"billing_mode": "BILLING_MODE",
"charging_period": "CHARGING_PERIOD",
"charging_start_date": "YYYY-MM-DD",
"charging_start_day_of_month": "DAY_OF_MONTH",
"charging_and_billing_alignment": "ALIGNMENT",
"pro_rata_partial_charging_period": "CHARGING_PERIOD",
"pro_rata_partial_pricing_period": "PRICING_PERIOD",
"pro_rata_partial_unit": "UNIT"
},
"item_custom_attributes": [
{
"key": "ATTRIBUTE_KEY",
"value": "ATTRIBUTE_VALUE"
}
],
"item_dimensions": {
"item_width": "WIDTH",
"item_height": "HEIGHT",
"item_length": "LENGTH",
"item_weight": "WEIGHT",
"item_dimension_unit": "DIMENSION_UNIT",
"item_weight_unit": "WEIGHT_UNIT"
}
}
]
},
"purchase-invoice": {
"id": "PURCHASE_INVOICE_ID",
"note": "INVOICE_NOTE",
"issue_date": "YYYY-MM-DD",
"due_date": "YYYY-MM-DD",
"custom_attributes": [
{
"key": "ATTRIBUTE_KEY",
"value": "ATTRIBUTE_VALUE"
}
]
}
}Response
The response contains a purchase_order object with the full purchase order record including calculated totals, tax amounts, generated UUIDs, line item details, KPIs, and activity logs.
Response Body
{
"purchase_order": {
"status": "ACTIVE",
"id": "PURCHASE_ORDER_ID",
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_CODE",
"link": "CURRENCY_LINK"
},
"supplier_invoice_id": "SUPPLIER_INVOICE_ID",
"origin": "ORIGIN",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"expected_completion_date": "YYYY-MM-DDTHH:MM:SSZ",
"subtotal": "SUBTOTAL_AMOUNT",
"tax": "TAX_AMOUNT",
"total": "TOTAL_AMOUNT",
"price_tax_inclusive": "false",
"purchase_order_note": "PURCHASE_ORDER_NOTE",
"account_id": "ACCOUNT_ID",
"sale_order_id": "SALE_ORDER_ID",
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "YYYY-MM-DDTHH:MM:SSZ",
"uuid": "PURCHASE_ORDER_UUID",
"version": "VERSION",
"custom_form": {
"uuid": "CUSTOM_FORM_UUID",
"name": "CUSTOM_FORM_NAME"
},
"custom_attributes": [],
"custom_objects": [],
"lines": [
{
"subtotal": "LINE_SUBTOTAL",
"total": "LINE_TOTAL",
"tax": "LINE_TAX",
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_quantity": "ITEM_QUANTITY",
"item_serial_or_batch_number": "SERIAL_OR_BATCH",
"item_price_snapshot": {
"pricing_rule": {
"uuid": "PRICING_RULE_UUID",
"version": "PRICING_VERSION",
"price_type": "PRICE_TYPE",
"price": "UNIT_PRICE",
"uom": "UNIT_OF_MEASURE",
"warehouse": "WAREHOUSE_NAME",
"pricing_version": "PRICING_VERSION"
}
},
"item_purchase_tax_configuration": {
"purchase_price_is_tax_inclusive": "false",
"tax_code": {
"uuid": "TAX_UUID",
"code": "TAX_CODE",
"rate": "TAX_RATE",
"link": "TAX_LINK"
}
},
"item_price_tax_exempt": "false",
"item_price_tax": {
"uuid": "TAX_UUID",
"code": "TAX_CODE",
"rate": "TAX_RATE",
"link": "TAX_LINK"
},
"purchase_order_note": "LINE_NOTE",
"item_accounting_code": {
"cost_of_goods_sold": "COGS_CODE"
},
"uuid": "LINE_UUID",
"version": "LINE_VERSION"
}
],
"kpis": {
"total_expense": 0,
"estimated_total": 0,
"total_outstanding": 0,
"total_overdue": 0,
"last_invoice_issue_date": "DATE",
"last_invoice_total": 0,
"total_purchase_invoice": 0,
"last_reactivated_on": "DATE",
"last_calcelled_on": "DATE",
"last_changed_on": "DATE",
"last_deleted_on": "DATE",
"issue_date": "DATE"
},
"activity_logs": []
}
}Create Purchase Order Note: /purchase-orders/{purchase_order_id}/notes
Purpose
This API allows users to add a new note to a purchase order. The note can contain plain or rich-text content and may include an attached file such as a document, image, or PDF. It’s commonly used for annotating purchase orders with explanations, approvals, comments, or supporting documentation.
Use Case
- Attach supplier invoices, receipts, or supporting files to a purchase order.
- Allow procurement officers to add approval notes directly linked to a purchase order.
- Maintain an auditable record of purchase order-related discussions and decisions.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| purchase_order_id | string | Unique identifier of the purchase order to which the note will be attached. |
Query Parameters
No query parameters required for this endpoint.
Request Body
The request body must be sent as multipart/form-data because it contains text and files.
| Attribute | Type | Description |
|---|---|---|
| note | string | Updated content of the note. Supports HTML formatting. |
| file | file | File(s) to attach with the note. Multiple files are allowed. Accepts common document and image formats |
Response
On success, the response confirms that a note has been successfully added to the specified purchase order. The purchase order object contains a notes object, which provides the unique identifier (uuid) of the newly created note.
Response Body
{
"purchase-order": {
"notes": {
"uuid": "NOTE_UUID"
}
}
}
| Attribute | Type | Description |
|---|---|---|
| purchase-order | object | Root object indicating the target purchase order. |
| notes | object | Container for the newly created note details. |
| uuid | string (UUID) | Unique identifier of the newly added note. |
Cancel a Purchase Order : /purchase-orders/{purchase_order_id}/cancel
Purpose
This endpoint is used to cancel an existing purchase order in the system. Once cancelled, the purchase order will no longer be active and cannot be used for further processing (receiving goods, invoicing).
Use Case
A user (such as a procurement officer or finance manager) may need to cancel a purchase order due to changes in supplier availability, pricing, incorrect information, or order duplication. This API provides a programmatic way to transition a purchase order to the Cancelled state.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| purchase_order_id | string | The unique identifier of the purchase order to cancel. |
Query Parameters
No query parameters required for this endpoint.
Request Body
No request body is required for this endpoint.
Response
This endpoint does not return a response body. Upon successful execution, the purchase order is deleted and an HTTP 204 No Content status code is returned.
Reactivate a Purchase Order : /purchase-orders/{purchase_order_id}/reactivate
Purpose
This endpoint is used to reactivate a previously cancelled purchase order. Reactivating a purchase order allows users to resume processing it (receiving goods or generating invoices) without creating a new purchase order from scratch.
Use Case
A procurement or finance team may cancel a purchase order due to a temporary supplier issue, pricing conflict, or internal approval delays. If the conditions change for example, the supplier becomes available again or the error is resolved the same purchase order can be reactivated using this API, thus maintaining order history and continuity.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| purchase_order_id | string | Unique identifier of the purchase order to reactivate. |
Query Parameters
No query parameters required for this endpoint.
Request Body
No request body is required for this endpoint.
Response
This endpoint does not return a response body. Upon successful execution, the purchase order is deleted and an HTTP 204 No Content status code is returned.
Create Purchase Invoice: /purchase-orders/{id}/purchase-invoices
Purpose
This API creates a purchase invoice linked to an existing purchase order. The invoice is generated against the purchase order and includes the order's line items, pricing, and tax configuration.
Scope
Purchase invoice write permission must be granted from the application to create a purchase invoice.
Use Case
When goods are received and an invoice needs to be generated against an existing purchase order, the frontend calls this endpoint with the invoice details. The system creates the invoice, links it to the purchase order, and returns the complete invoice record with calculated totals, tax amounts, KPIs, and activity logs.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | String | Yes | The unique identifier of the purchase order to create the invoice against (e.g., "PO-G9X1B6-0027"). |
Query Parameters
No query parameters required for this endpoint.
Request Body
{
"purchase_invoice": {
"id": "PURCHASE_INVOICE_ID",
"issue_date": "YYYY-MM-DD",
"due_date": "YYYY-MM-DD",
"note": "INVOICE_NOTE",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME",
"value": "ATTRIBUTE_VALUE"
}
]
}
}Response
The response contains a purchase_invoice object with the full invoice record including status, calculated totals, tax amounts, line item details, KPIs, and activity logs.
{
"purchase_invoice": {
"status": "ACTIVE",
"id": "PURCHASE_INVOICE_ID",
"origin": "ORIGIN",
"custom_form": {
"uuid": "CUSTOM_FORM_UUID",
"name": "CUSTOM_FORM_NAME"
},
"currency": {
"id": "CURRENCY_ID",
"name": "CURRENCY_CODE",
"link": {
"rel": "self",
"href": "CURRENCY_LINK"
}
},
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"alternate_issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"alternate_due_date": "YYYY-MM-DDTHH:MM:SSZ",
"subtotal": "SUBTOTAL_AMOUNT",
"tax": "TAX_AMOUNT",
"total": "TOTAL_AMOUNT",
"price_tax_inclusive": "true",
"account_id": "ACCOUNT_ID",
"purchase_order_id": "PURCHASE_ORDER_ID",
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "PURCHASE_INVOICE_UUID",
"version": "VERSION",
"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_PURCHASE_ORDER_QUANTITY",
"item_uom": "UNIT_OF_MEASURE",
"item_warehouse": "WAREHOUSE_NAME",
"uuid": "LINE_UUID",
"version": "LINE_VERSION"
}
],
"kpis": {
"outstanding": 0,
"overdue": 0,
"last_payment_date": "DATE",
"payment_applied": 0,
"credit_applied": 0,
"credit_issued": "AMOUNT",
"last_reactivated_on": "DATE",
"last_cancelled_on": "DATE",
"last_amended_on": "DATE",
"voided_on": "DATE",
"deleted_on": "DATE"
},
"activity_logs": []
}
}Change Purchase Order: purchase-orders/{id}/change
Purpose
This API changes line items on an existing purchase order. It supports modifying the order quantity and pricing of individual line items identified by their UUID.
Scope
Purchase order write permission must be granted from the application to change a purchase order.
Use Case
When quantities or pricing need to be adjusted on an active purchase order, the frontend calls this endpoint with the line item changes. Each line item to be modified is identified by its uuid and must include the op field set to "CHANGE". The system validates the changes, updates the purchase order, recalculates totals, and returns the complete updated order record.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | String | Yes | The unique identifier of the purchase order to change (e.g., "PO-9FOR9X-0028"). |
Query Parameters
No query parameters required for this endpoint.
Request Body
{
"purchase_order": {
"lines": [
{
"op": "CHANGE",
"uuid": "LINE_UUID",
"item_order_quantity": "ORDER_QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "UNIT_PRICE"
}
}
}
]
}
}Response
The response contains a purchase_order object with the full updated purchase order record. The response structure is the same as the Create Purchase Order response, with the addition of the op field on changed line items. See Create Purchase Order response attributes for the full attribute reference.
{
"purchase_order": {
"status": "ACTIVE",
"id": "PURCHASE_ORDER_ID",
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_CODE",
"link": "CURRENCY_LINK"
},
"supplier_invoice_id": "SUPPLIER_INVOICE_ID",
"sale_order_id": "SALE_ORDER_ID",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"expected_completion_date": "YYYY-MM-DDTHH:MM:SSZ",
"subtotal": "SUBTOTAL_AMOUNT",
"tax": "TAX_AMOUNT",
"total": "TOTAL_AMOUNT",
"price_tax_inclusive": "true",
"purchase_order_note": "PURCHASE_ORDER_NOTE",
"account_id": "ACCOUNT_ID",
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "YYYY-MM-DDTHH:MM:SSZ",
"uuid": "PURCHASE_ORDER_UUID",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": [],
"lines": [
{
"subtotal": "LINE_SUBTOTAL",
"total": "LINE_TOTAL",
"tax": "LINE_TAX",
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_quantity": "ITEM_QUANTITY",
"item_order_quantity": "ORDER_QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"uuid": "PRICING_RULE_UUID",
"version": "PRICING_VERSION",
"price_type": "PRICE_TYPE",
"price": "UNIT_PRICE",
"uom": "UNIT_OF_MEASURE",
"warehouse": "WAREHOUSE_NAME",
"pricing_version": "PRICING_VERSION"
}
},
"item_purchase_tax_configuration": {
"purchase_price_is_tax_inclusive": "false",
"tax_code": {
"uuid": "TAX_UUID",
"code": "TAX_CODE",
"rate": "TAX_RATE",
"link": "TAX_LINK"
}
},
"item_price_tax_exempt": "false",
"item_price_tax": {
"uuid": "TAX_UUID",
"code": "TAX_CODE",
"rate": "TAX_RATE",
"link": "TAX_LINK"
},
"purchase_order_note": "LINE_NOTE",
"item_accounting_code": {
"cost_of_goods_sold": "COGS_CODE"
},
"op": "CHANGE",
"uuid": "LINE_UUID",
"version": "LINE_VERSION",
"item_serial_or_batch_number": "SERIAL_OR_BATCH",
"tax_exempt_when_sold": "false"
}
],
"kpis": {
"total_purchase_invoice": 0,
"last_reactivated_on": "DATE",
"last_calcelled_on": "DATE",
"last_changed_on": "DATE",
"last_deleted_on": "DATE",
"issue_date": "DATE"
},
"custom_form": {
"uuid": "CUSTOM_FORM_UUID",
"name": "CUSTOM_FORM_NAME"
},
"origin": "ORIGIN",
"activity_logs": []
}
}