Update Transfer Order

PATCH /inventory/warehouse-transfer-orders/{id}

Group: Inventory › Warehouse Transfer Orders · Operation ID: updateTransferOrder

Updates the warehouse transfer order with the given identifier. Only the fields in the request body change. It must be a draft.

Edits a draft warehouse transfer order. Once converted, the order has a transfer behind it and is closed to changes, whatever that transfer has moved so far.

Every header field is optional, and an omitted field is left unchanged. Lines change through three arrays, applied in the order deleteLines, updateLines, createLines, so one call can retire a line and add its replacement. updateLines and deleteLines address lines by the id the order publishes, and a line id belonging to another order is refused.

Setting a line's locationId is how a 'NEEDS_SOURCE' line is resolved, which is the edit that unblocks the conversion.

The whole call is one transaction: a rejected request writes nothing. The response is the updated order in the same shape GET inventory/warehouse-transfer-orders/:id returns.

Open in the interactive reference

Parameters

Name	In	Type	Required	Description
`Api-Version`	header	`"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 for the transfer order to update.

Request body

Required, application/json: updateTransferOrderInput.

Field	Type	Required	Description
`documentDate`	string (date)	no	The date the transfer order is dated. Use format YYYY-MM-DD.
`locationId`	string	no	The warehouse the goods leave, for the transfer order as a whole. See id on GET inventory/warehouses/:id.
`targetLocationId`	string	no	The warehouse the goods go to, for the transfer order as a whole. See id on GET inventory/warehouses/:id.
`referenceNumber`	string	no	Your own reference on the transfer order.
`notes`	string	no	Free text on the document.
`createLines`	array of object	no	The lines to add. The same shape as on create.
`createLines[].itemId`	string	yes	The item to move. See id on GET inventory/items/:id.
`createLines[].locationId`	string	no	The warehouse to draw from. See id on GET inventory/warehouses/:id.
`createLines[].targetLocationId`	string	yes	The warehouse to deliver to. See id on GET inventory/warehouses/:id.
`createLines[].unitId`	string	no	The unit the quantity is in. Defaults to the item’s stocking unit. There is no endpoint for it.
`createLines[].quantity`	string (decimal)	yes	How much to move, in the line’s unit. Must be greater than zero.
`createLines[].notes`	string	no	Free text on the line.
`updateLines`	array of object	no	The lines to change, addressed by the id the transfer order publishes. Everything but the id is optional. Setting locationId is how a 'NEEDS_SOURCE' line is resolved.
`updateLines[].id`	string	yes	The line to change, by the id the transfer order publishes.
`updateLines[].itemId`	string	no	A different item to move. See id on GET inventory/items/:id.
`updateLines[].locationId`	string	no	The warehouse to draw from. See id on GET inventory/warehouses/:id.
`updateLines[].targetLocationId`	string	no	The warehouse to deliver to. See id on GET inventory/warehouses/:id.
`updateLines[].unitId`	string	no	The unit the quantity is in. There is no endpoint for it.
`updateLines[].quantity`	string (decimal)	no	How much to move. Must be greater than zero.
`updateLines[].notes`	string	no	Free text on the line.
`deleteLines`	array of string	no	The lines to remove, by the id the transfer order publishes. Applied before the updates and creates.

Example:

{
  "documentDate": "2026-01-15",
  "locationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "targetLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "referenceNumber": "<referenceNumber>",
  "notes": "<notes>",
  "createLines": [
    {
      "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "locationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "targetLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "unitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": "19.99",
      "notes": "<notes>"
    }
  ],
  "updateLines": [
    {
      "id": "9a4e2c76-1b38-4f05-8d92-6c7a3e15b204",
      "locationId": "b6f0d2a4-77c1-4e39-8a52-0c4e1f9b73d5"
    }
  ],
  "deleteLines": [
    "<deleteLines>"
  ]
}

Response

200 Success

Under data (updateTransferOrderOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the transfer order.
`documentNumber`	string	no	The transfer order's number, for example 'WTO-1043'.
`documentStatus`	string	yes	The status of the transfer order, computed from the lines and set by no endpoint directly. Possible values: 'DRAFT', 'IN_TRANSFER', 'PARTIALLY_PROCESSED', 'PROCESSED'. 'DRAFT' while the order is being written, 'IN_TRANSFER' while a transfer created from it has yet to commit, 'PARTIALLY_PROCESSED' once a transfer has moved part of what was asked for and a remainder is still open, and 'PROCESSED' once nothing is open.
`documentDate`	string (date)	no	The date the transfer order is dated. Format YYYY-MM-DD.
`referenceNumber`	string	no	Your own reference on the transfer order.
`entityId`	string	no	The legal entity the transfer order belongs to. See id on GET base/entities.
`entityName`	string	no	The name of that legal entity.
`locationId`	string	no	The warehouse the goods leave, where the order names one for the whole document. A line may name its own. See id on GET inventory/warehouses/:id.
`locationCode`	string	no	The code of that warehouse.
`locationName`	string	no	The name of that warehouse.
`targetLocationId`	string	no	The warehouse the goods go to. See id on GET inventory/warehouses/:id.
`targetLocationCode`	string	no	The code of that warehouse.
`targetLocationName`	string	no	The name of that warehouse.
`notes`	string	no	Free text on the document.
`lineCount`	number	no	The number of lines on the transfer order.
`openLineCount`	number	no	How many lines still have quantity left to transfer. Zero means everything has been taken.
`createdDate`	string (date-time)	no	The date and time the transfer order was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
`lastModifiedDate`	string (date-time)	no	The date and time the transfer order record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
`lines`	array of object	yes	The lines of the transfer order as it now stands.
`lines[].id`	string	yes	The unique identifier for the line. updateLines and deleteLines address a line by it.
`lines[].itemId`	string	no	The item to move. See id on GET inventory/items/:id.
`lines[].itemCode`	string	no	The code of that item.
`lines[].itemName`	string	no	The name of that item.
`lines[].locationId`	string	no	The warehouse this line draws from. See id on GET inventory/warehouses/:id. Absent while no source warehouse has been resolved, and such a line blocks the conversion.
`lines[].locationCode`	string	no	The code of that warehouse.
`lines[].locationName`	string	no	The name of that warehouse.
`lines[].targetLocationId`	string	no	The warehouse this line delivers to. See id on GET inventory/warehouses/:id.
`lines[].targetLocationCode`	string	no	The code of that warehouse.
`lines[].targetLocationName`	string	no	The name of that warehouse.
`lines[].unitId`	string	no	The unit the quantity is in. There is no endpoint for it.
`lines[].unitCode`	string	no	The code of that unit.
`lines[].quantity`	string (decimal)	no	How much to move, in the line's unit. Always greater than zero.
`lines[].inventoryQuantity`	string (decimal)	no	The same amount in the item's stocking unit, which is what the warehouse counts.
`lines[].openQuantity`	string (decimal)	no	How much of the line is still to be transferred.
`lines[].processedQuantity`	string (decimal)	no	How much of the line a transfer has already taken.
`lines[].status`	string	no	The state of the line. 'NEEDS_SOURCE' means no source warehouse has been resolved, and the transfer order cannot be converted until it is.
`lines[].notes`	string	no	Free text on the line.

Response headers

Idempotency-Replayed — Present and true only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as false.

Errors

Code	Status
`NOT_FOUND`	400
`WRONG_STATUS`	400
`REFERENCE_NOT_FOUND`	400
`INVALID_QUANTITY`	400
`SAME_LOCATION`	400
`IDEMPOTENCY_KEY_CONFLICT`	409
`IDEMPOTENCY_PAYLOAD_MISMATCH`	422

Statuses

400 — Invalid request or business failure. Codes: NOT_FOUND, WRONG_STATUS, REFERENCE_NOT_FOUND, INVALID_QUANTITY, SAME_LOCATION
401 — Missing or invalid access token
403 — Not authorized
404 — Not found
409 — The Idempotency-Key is still being processed by another request.
422 — The Idempotency-Key was already used with a different request payload.
429 — Too many requests
500 — Internal server error