Updates a Purchase order

put

https://api.factorialhr.com/api/2026-10-01/resources/procurement/purchase_orders/{id}

Update a purchase order with PUT semantics: read the purchase order, modify it, and send the complete resource back. Template fields are addressed by their stable field_key and validated against the template version the purchase order was created with. Line items are addressed by id.
Omission semantics: status, date and deadline omitted or null keep their current value; header_field_values_by_key and line_items_by_key omitted keep the current values, while an empty array [] deletes them all (full replace). Within a sent block, what you send is what remains.
Errors: validation problems are a 422 with {"errors": {<field_key>: [messages]}} (unknown/computed/predefined keys, missing required fields, unresolvable reference values, foreign line-item ids, mixing by_key and legacy addressing). A vendor_id or legal_entity_id that does not exist or is not visible to the credential is rejected by the platform resource check with a 400 ({"errors": [{"error": ...}]}). Lifecycle conflicts are a 409: purchase orders in closed or processing (still being generated — retry later) status cannot be updated. processing is not accepted as a new status (422). Purchase orders without a template only accept data edits while in draft status (409 afterwards).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

string

required

Identifier of the purchase order to update.

Body Params

string

required

Identifier of the purchase order to update.

company_id

string

required

Company identifier, as returned by the credentials endpoint (/resources/api_public/credentials).

formatted_po_number

string

required

Formatted purchase order number with prefix, as returned by the read endpoint — send back the value you read.

description

string

required

Description or notes about the purchase order.

preferred_payment_method

string

enum

Preferred payment method for this purchase order. Send null to clear it.

Allowed:

status

string

enum

Status of the purchase order. Omitted or null keeps the current status; send a new one to transition. Once closed, the purchase order becomes immutable.

Allowed:

legal_entity_id

string

required

Identifier of the legal entity that owns the purchase order. Must belong to the company.

cost

object

required

Total cost of the purchase order, as returned by the read endpoint — send back what you read. The currency is applied as sent; on template-versioned purchase orders the amounts are owned by the line items and recomputed server-side.

vendor_id

string

Identifier of the vendor (Finance contact) by internal Factorial id. Null clears the vendor on template-versioned purchase orders.

date

string

Purchase order date. Omit or send null to keep the current one.

deadline

string

Deadline date for the purchase order delivery or completion. Omitted or null keeps the current deadline (clearing a deadline through this endpoint is not supported).

header_field_values_by_key

array of objects

Header field values of the purchase order's template version, as an array of {field_key, value} pairs — the same shape the read returns. Replaced as sent: send the complete set; an empty array deletes all custom header values, and omitting the field leaves them untouched. Only custom field keys are accepted; predefined fields (vendor, order_date, currency, due_date, payment_method, legal_entity) come from the corresponding top-level parameters. Reference fields take the referenced id as the value. If a field_key appears more than once, the last occurrence wins.

header_field_values_by_key

line_items_by_key

array of objects

Line items of the purchase order, replaced as sent — the same shape the read returns. Rows with an id update the matching line item, rows without an id create new ones, and persisted rows missing from the set are deleted. Send an empty array to remove all line items, or omit the field to leave them untouched. Values travel as {field_key, value} pairs; computed keys (subtotal, tax_amount, total, discount_amount) are derived server-side and rejected as input.

line_items_by_key

Response

200OK