# Update Warehouse Transfer `PATCH /inventory/warehouse-transfers/{id}` Group: Inventory › Warehouse Transfers · Operation ID: `updateWarehouseTransfer` Updates the draft warehouse transfer with the given identifier. Only the fields in the request body change. Edits a draft warehouse transfer. A committed transfer has moved the stock, so correct it by canceling rather than editing. Every field is optional, and only the fields you send change. 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 transfer publishes, and a line id from another transfer is refused. A tracking array you send on a line replaces what that line had. transferType cannot be changed. The response has the same shape as GET inventory/warehouse-transfers/:id. [Open in the interactive reference](https://docs.api.lensing.ai/?op=updateWarehouseTransfer) ## 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 to update. | ## Request body Required, `application/json`: updateWarehouseTransferInput. | Field | Type | Required | Description | | --- | --- | --- | --- | | `locationId` | string | no | The warehouse the goods leave, applied to every line. See id on GET inventory/warehouses/:id. | | `targetLocationId` | string | no | The warehouse the goods go to. It must differ from locationId. See id on GET inventory/warehouses/:id. | | `documentDate` | string (date) | no | The date to give the transfer. Use format YYYY-MM-DD. | | `referenceNumber` | string | no | Your own reference on the transfer. | | `notes` | string | no | Free text on the document. | | `contractualCurrency` | string | no | The currency an intercompany transfer is contracted in. Format ISO 4217, for example 'EUR'. Each line's unitTransferValue is stated in it. | | `createLines` | array of object | no | Lines to add. Same shape as on create. | | `createLines[].itemId` | string | yes | The item to move. See id on GET inventory/items/: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. | | `createLines[].unitTransferValue` | string (decimal) | no | The contractual price of one unit, in the transfer's contractual currency. Required on an intercompany transfer. The two entities agree the price, and the API cannot derive it from a cost. | | `createLines[].batches` | array of object | no | The batches that make up the line's quantity. Required for a batch-tracked item, and they must add up to the line's quantity. | | `createLines[].batches[].batchNumberId` | string | no | The unique identifier for an existing batch number. See id on GET inventory/batch-numbers/:id. | | `createLines[].batches[].batchNumber` | string | no | The batch number. Naming one the item does not have yet creates it. | | `createLines[].batches[].quantity` | string (decimal) | yes | How much of the line this batch accounts for. | | `createLines[].serials` | array of object | no | The serialized units that move. Required for a serialized item, one entry per unit. | | `createLines[].serials[].serialNumberId` | string | no | The unique identifier for an existing serial number. See id on GET inventory/serial-numbers/:id. | | `createLines[].serials[].serialNumber` | string | no | The serial number. Naming one the item does not have yet creates it. | | `createLines[].binLocations` | array of object | no | The bins the goods leave and arrive in. Each entry names both ends of the move, and the batch or serial it belongs to where it belongs to one. Leave both names off for a quantity that moves at line level. | | `createLines[].binLocations[].fromBinLocationId` | string | no | The bin the goods leave, in the source warehouse. See id on GET inventory/bins/:id. | | `createLines[].binLocations[].toBinLocationId` | string | no | The bin the goods arrive in, in the target warehouse. See id on GET inventory/bins/:id. | | `createLines[].binLocations[].quantity` | string (decimal) | yes | How much moves between these two bins. | | `createLines[].binLocations[].batchNumber` | string | no | The batch this entry belongs to, when it belongs to one of the line's batches. | | `createLines[].binLocations[].serialNumber` | string | no | The serialized unit this entry belongs to, when it belongs to one of the line's serials. | | `updateLines` | array of object | no | Lines to change, each addressed by its id. Every field but the id is optional, and a tracking array you send replaces what the line had. | | `updateLines[].id` | string | yes | The unique identifier for the line to change. | | `updateLines[].itemId` | string | no | The item to move. See id on GET inventory/items/:id. | | `updateLines[].unitId` | string | no | The unit the quantity is in. Defaults to the item's stocking unit. There is no endpoint for it. | | `updateLines[].quantity` | string (decimal) | no | How much to move, in the line's unit. Must be greater than zero. | | `updateLines[].notes` | string | no | Free text on the line. | | `updateLines[].unitTransferValue` | string (decimal) | no | The contractual price of one unit, in the transfer's contractual currency. Required on an intercompany transfer. The two entities agree the price, and the API cannot derive it from a cost. | | `updateLines[].batches` | array of object | no | The batches that make up the line's quantity. Required for a batch-tracked item, and they must add up to the line's quantity. | | `updateLines[].batches[].batchNumberId` | string | no | The unique identifier for an existing batch number. See id on GET inventory/batch-numbers/:id. | | `updateLines[].batches[].batchNumber` | string | no | The batch number. Naming one the item does not have yet creates it. | | `updateLines[].batches[].quantity` | string (decimal) | yes | How much of the line this batch accounts for. | | `updateLines[].serials` | array of object | no | The serialized units that move. Required for a serialized item, one entry per unit. | | `updateLines[].serials[].serialNumberId` | string | no | The unique identifier for an existing serial number. See id on GET inventory/serial-numbers/:id. | | `updateLines[].serials[].serialNumber` | string | no | The serial number. Naming one the item does not have yet creates it. | | `updateLines[].binLocations` | array of object | no | The bins the goods leave and arrive in. Each entry names both ends of the move, and the batch or serial it belongs to where it belongs to one. Leave both names off for a quantity that moves at line level. | | `updateLines[].binLocations[].fromBinLocationId` | string | no | The bin the goods leave, in the source warehouse. See id on GET inventory/bins/:id. | | `updateLines[].binLocations[].toBinLocationId` | string | no | The bin the goods arrive in, in the target warehouse. See id on GET inventory/bins/:id. | | `updateLines[].binLocations[].quantity` | string (decimal) | yes | How much moves between these two bins. | | `updateLines[].binLocations[].batchNumber` | string | no | The batch this entry belongs to, when it belongs to one of the line's batches. | | `updateLines[].binLocations[].serialNumber` | string | no | The serialized unit this entry belongs to, when it belongs to one of the line's serials. | | `deleteLines` | array of string | no | The ids of lines to remove. They are applied before the updates and the creates. | Example: ```json { "locationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "targetLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "documentDate": "2026-01-15", "referenceNumber": "", "notes": "Consolidated with WTR-2290", "contractualCurrency": "", "createLines": [ { "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "unitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "quantity": "19.99", "notes": "", "unitTransferValue": "19.99", "batches": [ { "batchNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "batchNumber": "", "quantity": "19.99" } ], "serials": [ { "serialNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "serialNumber": "" } ], "binLocations": [ { "fromBinLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "toBinLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "quantity": "19.99", "batchNumber": "", "serialNumber": "" } ] } ], "updateLines": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "unitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "quantity": "19.99", "notes": "", "unitTransferValue": "19.99", "batches": [ { "batchNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "batchNumber": "", "quantity": "19.99" } ], "serials": [ { "serialNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "serialNumber": "" } ], "binLocations": [ { "fromBinLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "toBinLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "quantity": "19.99", "batchNumber": "", "serialNumber": "" } ] } ], "deleteLines": [ "" ] } ``` ## Response `200` Success Under `data` (updateWarehouseTransferOutput): | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | yes | The unique identifier for the transfer. | | `documentNumber` | string | no | The transfer's number, for example 'WTR-2291'. | | `documentStatus` | string | yes | The status of the transfer. Possible values: 'DRAFT', 'COMMITTED', 'CANCELLED'. | | `documentDate` | string (date) | no | The date the transfer is dated. Format YYYY-MM-DD. | | `referenceNumber` | string | no | Your own reference on the transfer. | | `transferType` | string | no | The type of transfer. Possible values: 'NORMAL', 'INTERCOMPANY', 'INTERCOMPANY_RETURN'. An intercompany transfer sells the goods to another legal entity and can be billed. | | `entityId` | string | no | The legal entity the goods leave. See id on GET base/entities. | | `entityName` | string | no | The name of that legal entity. | | `toEntityId` | string | no | The legal entity receiving the goods, on an intercompany transfer. See id on GET base/entities. | | `toEntityName` | string | no | The name of that legal entity. | | `locationId` | string | no | The warehouse the goods leave. 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. | | `billingStatus` | string | no | The billing status of the transfer. Possible values: 'NOT_BILLED', 'BILLED'. Only an intercompany transfer is billed, through POST inventory/warehouse-transfers/:id/bill. | | `intercompanyBillId` | string | no | The identifier of the intercompany bill this transfer created, as the platform's own number. GET accounting/vendor-bills/:id takes a UUID, so this number cannot fetch that bill. | | `contractualCurrency` | string | no | The currency an intercompany transfer is contracted in. Format ISO 4217, for example 'EUR'. Each line's unitTransferValue is stated in it. | | `currency` | string | no | The currency the amounts on the transfer are stated in, the source entity's functional currency. Format ISO 4217, for example 'EUR'. | | `sourceAmount` | string (decimal) | no | What the goods were worth leaving the source entity, in the transfer's currency. Written by the commit. | | `destinationAmount` | string (decimal) | no | What the goods were worth arriving at the destination entity, in the transfer's currency. On an intercompany transfer it differs from sourceAmount, and the difference is the margin. | | `notes` | string | no | Free text on the document. | | `lineCount` | number | no | The number of lines on the transfer. | | `createdDate` | string (date-time) | no | The date and time the transfer was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. | | `lastModifiedDate` | string (date-time) | no | The date and time the transfer record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. | | `lines` | array of object | no | The lines of the transfer. The collection GET inventory/warehouse-transfers returns lineCount in place of these. | | `lines[].id` | string | yes | The unique identifier for the transfer line. updateLines and deleteLines address lines by it. | | `lines[].itemId` | string | no | The item being moved. 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, the document's warehouse applied to every line. See id on GET inventory/warehouses/:id. | | `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 moves, in the line's unit. | | `lines[].inventoryQuantity` | string (decimal) | no | The same amount in the item's stocking unit, which is what the warehouse counts. | | `lines[].transferCost` | string (decimal) | no | What one unit left the source warehouse at, in the transfer's currency. The valuation method sets it at commit. Absent on a draft. | | `lines[].unitTransferValue` | string (decimal) | no | The contractual price of one unit on an intercompany transfer, in the contractual currency. Supplied on create. | | `lines[].totalTransferValue` | string (decimal) | no | The line's total on an intercompany transfer, in the contractual currency: totalTransferValue = unitTransferValue x quantity. Written by the platform. | | `lines[].returnedQuantity` | string (decimal) | no | How much of this line has come back on an intercompany return. | | `lines[].status` | string | no | The status of the line. | | `lines[].notes` | string | no | Free text on the line. | | `lines[].batches` | array of object | no | The batches that make up the line's quantity. | | `lines[].batches[].batchNumberId` | string | no | The unique identifier for the batch number. See id on GET inventory/batch-numbers/:id. | | `lines[].batches[].batchNumber` | string | no | The batch number. | | `lines[].batches[].quantity` | string (decimal) | no | How much of the line this batch accounts for. | | `lines[].batches[].inventoryQuantity` | string (decimal) | no | The same amount in the item's stocking unit. | | `lines[].batches[].unitCost` | string (decimal) | no | What this batch moved at, in the transfer's currency. Set at commit. | | `lines[].serials` | array of object | no | The serialized units that move. | | `lines[].serials[].serialNumberId` | string | no | The unique identifier for the serial number. See id on GET inventory/serial-numbers/:id. | | `lines[].serials[].serialNumber` | string | no | The serial number. | | `lines[].serials[].quantity` | string (decimal) | no | Always one, for a serialized unit. | | `lines[].serials[].unitCost` | string (decimal) | no | What this unit moved at, in the transfer's currency. Set at commit. | | `lines[].binLocations` | array of object | no | The bins the goods leave and arrive in. Each entry names both ends of the move, and the batch or serial it belongs to where it belongs to one. | | `lines[].binLocations[].fromBinLocationId` | string | no | The bin the goods leave, in the source warehouse. See id on GET inventory/bins/:id. | | `lines[].binLocations[].fromBinLocationCode` | string | no | The code of that bin. | | `lines[].binLocations[].toBinLocationId` | string | no | The bin the goods arrive in, in the target warehouse. See id on GET inventory/bins/:id. | | `lines[].binLocations[].toBinLocationCode` | string | no | The code of that bin. | | `lines[].binLocations[].quantity` | string (decimal) | no | How much moves between these two bins. | | `lines[].binLocations[].inventoryQuantity` | string (decimal) | no | The same amount in the item's stocking unit. | | `lines[].binLocations[].batchNumber` | string | no | The batch this entry belongs to, when it belongs to one of the line's batches. | | `lines[].binLocations[].serialNumber` | string | no | The serialized unit this entry belongs to, when it belongs to one of the line's serials. | ## 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 | | `NO_LINES` | 400 | | `INVALID_QUANTITY` | 400 | | `SAME_LOCATION` | 400 | | `INTERCOMPANY_CONFIG_MISSING` | 400 | | `DUPLICATE_TRACKING_NUMBER` | 400 | | `UNKNOWN_TRACKING_REFERENCE` | 400 | | `POSTING_REJECTED` | 400 | | `IDEMPOTENCY_KEY_CONFLICT` | 409 | | `IDEMPOTENCY_PAYLOAD_MISMATCH` | 422 | ## Statuses - `400` — Invalid request or business failure. Codes: NOT_FOUND, WRONG_STATUS, REFERENCE_NOT_FOUND, NO_LINES, INVALID_QUANTITY, SAME_LOCATION, INTERCOMPANY_CONFIG_MISSING, DUPLICATE_TRACKING_NUMBER, UNKNOWN_TRACKING_REFERENCE, POSTING_REJECTED - `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