---
title: "Update an existing purchase order"
method: PATCH
path: "/purchase-orders/{id}"
tags: ["purchaseOrders"]
---

# Update an existing purchase order

`PATCH /purchase-orders/{id}`

Updates a purchase order. Note: `status`, `po_number`, `external_id`, `erp_vendor_id`, and `ottimate_location_id` cannot be changed. If `status` is included in the request, the request is rejected with a 400 error. If `po_number`, `external_id`, `erp_vendor_id`, or `ottimate_location_id` is included with a different value, the request succeeds but that field is silently ignored (no error, no change).

## Path parameters

- `id` string, required

## Headers

- `Authorization` string, required
- `X-Api-Key` string, required
- `X-API-Version` string

## Request body

- object
  - `erp_vendor_name` string — Vendor name from ERP system
  - `date` string, date
  - `total_amount` number, double
  - `tax` number, double
  - `freight` number, double
  - `miscellaneous_charges` number, double
  - `invoice_number_ref` string
  - `is_2_way` boolean
  - `items` PurchaseOrdersIdPatchRequestBodyContentApplicationJsonSchemaItemsItems[] — Items with `id` update the existing item. Items without `id` create a new item. When creating, `name`, `quantity`, and `price` are required.
    - `id` string — Existing item ID. If provided, updates that item; if omitted, creates a new item.
    - `external_id` string
    - `name` string — Required when creating a new item (no id).
    - `sku` string
    - `quantity` number, double — Required when creating a new item (no id).
    - `price` number, double — Required when creating a new item (no id).
    - `uom` string
    - `dimensions` PurchaseOrdersIdPatchRequestBodyContentApplicationJsonSchemaItemsItemsDimensions — Dimension values keyed by dimension type. Each value must be a string — the ERP dimension code or ID (e.g. "DEPT-001"). Example: {"DEPARTMENT": "DEPT-001", "CLASS": "CLASS-001"}. Important: the GET response returns dimensions as rich objects (with id, name, code); passing an object here instead of a string will return a PO4000 validation error. When provided, REPLACES all existing dimensions on the item — include every dimension you want to keep. Omit the field or pass null to leave dimensions unchanged. Passing {} returns 400.
  - `custom_fields` PurchaseOrdersIdPatchRequestBodyContentApplicationJsonSchemaCustomFields — Optional custom fields configured for this company's purchase orders. Provide field values, pass null, or omit the field entirely — passing {} (empty object) returns 400.

## Response `200`

Successfully updated

- PurchaseOrderUpdateResponse
  - `version` string
  - `id` string, required
  - `external_id` string
  - `po_number` string
  - `status` 'pending' | 'open' | 'received' | 'closed' | 'flagged' | 'archived' | 'deleted', required
  - `ottimate_location_id` integer
  - `ottimate_company_id` integer
  - `date` string, date
  - `erp_vendor_id` string
  - `erp_vendor_name` string
  - `total_amount` number, double
  - `items_count` integer
  - `last_modified_date` string, date-time — Last modification timestamp. UTC ISO 8601, e.g. "2024-01-15T10:30:00Z".

## Other responses

- `400` — Bad request - Invalid parameters or request format
- `403` — Forbidden - Access denied or insufficient permissions
- `404` — Not found - Resource does not exist

---

[API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)