Warehouse Transfers
Move stock between warehouses with dispatch, receive, and line-receive routes.
Warehouse Transfers API
A warehouse transfer moves stock between two warehouses. It carries an ST- reference sequence, an origin and a destination warehouse, and per-line requested/sent/received quantities. Stock moves exclusively through the existing transaction ledger (TransferOut at dispatch, TransferIn at receive); barcoded assets also have their warehouse_id updated. Transfers use either-warehouse visibility — a user who can access either the origin or the destination can see the transfer — while dispatch is gated to origin access and receive to destination access.
Status is emitted as an compatibility integer code code with a status_label.
Endpoints
| Method | URL | Description |
|---|---|---|
| GET | /api/v1/warehouse_transfers |
List warehouse transfers |
| POST | /api/v1/warehouse_transfers |
Create a draft transfer |
| GET | /api/v1/warehouse_transfers/{warehouse_transfer} |
Show a transfer |
| PUT/PATCH | /api/v1/warehouse_transfers/{warehouse_transfer} |
Update a draft transfer |
| DELETE | /api/v1/warehouse_transfers/{warehouse_transfer} |
Cancel a transfer |
| GET|POST | /api/v1/warehouse_transfers/{warehouse_transfer}/dispatch |
Dispatch from origin (moves stock into transit) |
| GET|POST | /api/v1/warehouse_transfers/{warehouse_transfer}/receive |
Receive at destination |
| GET | /api/v1/warehouse_transfers/{warehouse_transfer}/lines |
List transfer lines |
| POST | /api/v1/warehouse_transfers/{warehouse_transfer}/lines/receive |
Record a line-level partial receive |
Authentication
Requires warehouse_transfers:read (GET) or the matching write ability — warehouse_transfers:write (CRUD), warehouse_transfers:dispatch, warehouse_transfers:receive, or warehouse_transfers:cancel — with warehouse_transfers.view, warehouse_transfers.create, warehouse_transfers.update, warehouse_transfers.dispatch, warehouse_transfers.receive, and warehouse_transfers.delete permissions as applicable.
Lifecycle
| Phase | Loose | Barcoded |
|---|---|---|
| Dispatch | TransferOut at origin |
TransferOut at origin |
| Receive | TransferIn at destination (creates the destination level if missing) |
warehouse_id moved to destination + compensating TransferIn |
| Cancel (in-transit) | Compensating TransferIn at origin for unsent/unreceived quantity |
Same pattern |
A transfer stays in transit until every line is fully received, then its header status becomes received. Cancel is allowed for draft and in-transit transfers; received or already-cancelled transfers are rejected.
Partial receive
POST /api/v1/warehouse_transfers/{warehouse_transfer}/lines/receive
Records a line-level receipt (receive_source: manual|scan) — the same seam the transfer scan context uses at the destination.
Status codes
| Code | Label |
|---|---|
0 |
Draft |
1 |
In transit |
2 |
Received |
3 |
Cancelled |
Response shape
Money and decimal quantities serialise as decimal strings. Collection key: warehouse_transfers; singular: warehouse_transfer.
Webhooks
Warehouse transfer lifecycle events are dispatched on the warehouse_transfers webhook surface — see Webhooks.