Update a purchase request

Operation ID: updatePurchaseRequest

Group: Accounting › Purchase Requests

Open in the interactive reference

PATCH /accounting/purchase-requests/{id}

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Updates a purchase request with the fields you send. A field you leave out keeps its current value.

Use the purchase request's id, not its purchaseRequestNumber.

Lines change through three separate arrays, applied in this order: deleteLines, updateLines, createLines. Lines you don't name stay as they are. On an updateLines item, a field you leave out keeps its current value.

After the update, the purchase request goes through your tenant's approval policy again. An approved or rejected request goes back to 'pendingApproval' first.

entityId and currency can't be changed, and status isn't an input. To approve or reject a request, use POST accounting/purchase-requests/:id/approve or POST accounting/purchase-requests/:id/reject.

updateLines and deleteLines name each line by the id that GET accounting/purchase-requests/:id returns for it.

deleteLines is always refused, even for lines that are not on any purchase order.

The response is empty. To see the updated request, use GET accounting/purchase-requests/:id.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.
id path string yes The unique identifier of the purchase request you want to update. Example: "5f8a2c31-6b07-4d92-a4e8-1c93b0f7d254".

Request body

Required, application/json: updatePurchaseRequestInput.

Field Type Required Description
vendorId string no A new vendor for the request. See id on GET accounting/vendors/:id. Omit to leave unchanged.
departmentId string no A new department for the request. See id on GET people/departments/:id. Omit to leave unchanged.
description string no A new public-facing description. Omit to leave unchanged.
internalDescription string no A new internal description. Omit to leave unchanged.
externalMemo string no A new external memo. Omit to leave unchanged.
paymentTerms string no New payment terms, as a payment-terms key. Omit to leave unchanged.
needByDate date no A new need-by date. Use format YYYY-MM-DD. Omit to leave unchanged. Example: "2026-11-01".
startDate date no A new start date. Use format YYYY-MM-DD. Omit to leave unchanged.
endDate date no A new end date. Use format YYYY-MM-DD. Omit to leave unchanged.
createLines array<object> no Lines to add to this request. Same shape as on create, with no id, because the line does not exist yet. Omit for no additions.
createLines[].isItem boolean no True for an item line, priced by quantity times price. False for an expense line.
createLines[].description string no A description of what is being requested.
createLines[].itemId string no The item being requested. See id on GET inventory/items/:id.
createLines[].unitOfMeasureId string no The unit the quantity is expressed in. See id on GET inventory/unit-of-measures/:id.
createLines[].departmentId string no The department this line is allocated to. See id on GET people/departments/:id.
createLines[].quantity decimal no The requested quantity, as a decimal.
createLines[].price decimal no The unit price, as a decimal.
createLines[].editableAmount decimal no The manually entered line amount, as a decimal.
createLines[].needByDate date no The date this line is needed by. Use format YYYY-MM-DD.
createLines[].deliveryDate date no The expected delivery date. Use format YYYY-MM-DD.
createLines[].priority string no The urgency of this line. Accepted values: 'high', 'medium', 'low'.
updateLines array<object> no Lines to change, each addressed by the id the request publishes. Every field but the id is optional and omitting it leaves that field unchanged. Omit for no changes. Example: [{"id":"8b3c1d02-7e46-4f95-b2a7-6d04e1c9f378","editableAmount":"1950.00"}].
updateLines[].id string yes The unique identifier for the line to change. It must belong to this request.
updateLines[].isItem boolean no A new line kind. Omit to leave unchanged.
updateLines[].description string no A new description. Omit to leave unchanged.
updateLines[].itemId string no A new item. See id on GET inventory/items/:id. Omit to leave unchanged.
updateLines[].unitOfMeasureId string no A new unit of measure. See id on GET inventory/unit-of-measures/:id. Omit to leave unchanged.
updateLines[].departmentId string no A new department. See id on GET people/departments/:id. Omit to leave unchanged.
updateLines[].quantity decimal no A new quantity, as a decimal. Omit to leave unchanged.
updateLines[].price decimal no A new unit price, as a decimal. Omit to leave unchanged.
updateLines[].editableAmount decimal no A new manually entered amount, as a decimal. Omit to leave unchanged.
updateLines[].needByDate date no A new need-by date. Use format YYYY-MM-DD. Omit to leave unchanged.
updateLines[].deliveryDate date no A new expected delivery date. Use format YYYY-MM-DD. Omit to leave unchanged.
updateLines[].priority string no A new urgency. Omit to leave unchanged.
deleteLines array<string> no The ids of lines to remove, applied before the updates and creates. Each must belong to this request, and none may already be ordered on a purchase order. 
{
  "vendorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "departmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "description": "<description>",
  "internalDescription": "<internalDescription>",
  "externalMemo": "<externalMemo>",
  "paymentTerms": "<paymentTerms>",
  "needByDate": "2026-11-01",
  "startDate": "2026-01-15",
  "endDate": "2026-01-15",
  "createLines": [
    {
      "isItem": true,
      "description": "<description>",
      "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "unitOfMeasureId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "departmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": "19.99",
      "price": "19.99",
      "editableAmount": "19.99",
      "needByDate": "2026-01-15",
      "deliveryDate": "2026-01-15",
      "priority": "<priority>"
    }
  ],
  "updateLines": [
    {
      "id": "8b3c1d02-7e46-4f95-b2a7-6d04e1c9f378",
      "editableAmount": "1950.00"
    }
  ],
  "deleteLines": [
    "<deleteLines>"
  ]
}

Response

200 Success

{
  "data": {},
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
NOT_FOUND 400
REFERENCE_NOT_FOUND 400
LINE_NOT_FOUND 400
LINE_LINKED_TO_PURCHASE_ORDER 400
NO_LINES 400
TOO_MANY_LINES 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses