# Update a warehouse transfer order

Operation ID: `updateTransferOrder`

Group: Inventory › Warehouse Transfer Orders

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/updateTransferOrder)

`PATCH /inventory/warehouse-transfer-orders/{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 draft warehouse transfer order with the fields you send. A field you leave out keeps its current value.

Only an order at 'DRAFT' can be changed. An order at 'IN_TRANSFER' can be changed again only if its draft transfer is deleted before anything on the order has been transferred.

Lines change through three separate arrays, applied in this order: deleteLines, updateLines, createLines. Leave out all three to keep the lines as they are. One request can remove a line and add its replacement. On an updateLines item, always send quantity.

updateLines and deleteLines take the line ids returned by GET inventory/warehouse-transfer-orders/:id, and a line id from another order is refused.

Setting locationId on a 'NEEDS_SOURCE' line does not clear that status. To fix such a line, remove it with deleteLines and add a replacement with a locationId through createLines in the same request.

The response has the same fields as GET inventory/warehouse-transfer-orders/: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 transfer order you want to update. |

## Request body

Required, `application/json`: updateTransferOrderInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `documentDate` | 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<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. See id on GET inventory/unit-of-measures/:id. |
| `createLines[].quantity` | 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<object> | no | The lines to change, addressed by the id the transfer order publishes. Everything but the id is optional. Example: `[{"id":"9a4e2c76-1b38-4f05-8d92-6c7a3e15b204","locationId":"b6f0d2a4-77c1-4e39-8a52-0c4e1f9b73d5"}]`. |
| `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. See id on GET inventory/unit-of-measures/:id. |
| `updateLines[].quantity` | decimal | no | How much to move. Must be greater than zero. |
| `updateLines[].notes` | string | no | Free text on the line. |
| `deleteLines` | array<string> | no | The lines to remove, by the id the transfer order publishes. Applied before the updates and creates. |

```json
{
  "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. Example: `"3f8c0b21-6e57-4d92-a134-8b5e7c2f01a6"`. |
| `documentNumber` | string | no | The transfer order's number, for example 'WTO-1043'. Example: `"WTO-1044"`. |
| `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. Example: `"DRAFT"`. |
| `documentDate` | 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. Example: `1`. |
| `openLineCount` | number | no | How many lines still have quantity left to transfer. Zero means everything has been taken. Example: `1`. |
| `createdDate` | date-time | no | The date and time the transfer order was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `lastModifiedDate` | date-time | no | The date and time the transfer order record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-18T11:20:04.219Z"`. |
| `lines` | array<object> | yes | The lines of the transfer order as it now stands. Example: `[{"id":"9a4e2c76-1b38-4f05-8d92-6c7a3e15b204","itemId":"517a93e4-cbb4-4571-9e3d-2343e56cfd84","itemCode":"WIDGET-01","targetLocationId":"e94a17c3-5b28-4d60-91f7-3a8c2e05b6d1","quantity":"12","inventoryQuantity":"12","openQuantity":"12","status":"NEEDS_SOURCE"}]`. |
| `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. See id on GET inventory/unit-of-measures/:id. |
| `lines[].unitCode` | string | no | The code of that unit. |
| `lines[].quantity` | decimal | no | How much to move, in the line's unit. Always greater than zero. |
| `lines[].inventoryQuantity` | decimal | no | The same amount in the item's stocking unit, which is what the warehouse counts. |
| `lines[].openQuantity` | decimal | no | How much of the line is still to be transferred. |
| `lines[].processedQuantity` | 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. |

```json
{
  "data": {
    "id": "3f8c0b21-6e57-4d92-a134-8b5e7c2f01a6",
    "documentNumber": "WTO-1044",
    "documentStatus": "DRAFT",
    "documentDate": "2026-01-15",
    "referenceNumber": "<referenceNumber>",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityName": "<entityName>",
    "locationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "locationCode": "<locationCode>",
    "locationName": "<locationName>",
    "targetLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "targetLocationCode": "<targetLocationCode>",
    "targetLocationName": "<targetLocationName>",
    "notes": "<notes>",
    "lineCount": 1,
    "openLineCount": 1,
    "createdDate": "2026-01-15T09:30:00.000Z",
    "lastModifiedDate": "2026-08-18T11:20:04.219Z",
    "lines": [
      {
        "id": "9a4e2c76-1b38-4f05-8d92-6c7a3e15b204",
        "itemId": "517a93e4-cbb4-4571-9e3d-2343e56cfd84",
        "itemCode": "WIDGET-01",
        "targetLocationId": "e94a17c3-5b28-4d60-91f7-3a8c2e05b6d1",
        "quantity": "12",
        "inventoryQuantity": "12",
        "openQuantity": "12",
        "status": "NEEDS_SOURCE"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## 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 |
| `HEADER_SAME_LOCATION` | 400 |
| `HEADER_ENTITY_MISMATCH` | 400 |
| `ENTITY_MISMATCH` | 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, HEADER_SAME_LOCATION, HEADER_ENTITY_MISMATCH, ENTITY_MISMATCH
- `401` — The request carries no valid 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 from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error