Overview
This is an API to create a transfer transaction in the MES transaction queue.
A transfer moves inventory from one location to another (often called reclassification in BC). Trade items can also be moved to another stock center at the same time. Both trade items and standard items can be transferred.
Working with a transfer has two steps (details in How it works):
-
Endpoint: the MES posts to the endpoint, and the MES transaction is created. Nothing else is changed in BC yet.
-
Processing: the MES processor (job queue) error checks the transaction and posts the transfer in BC.
See more information about the workflow: MES Use Case: Production
|
Endpoint name |
|
|
Source table |
|
|
Fixed view/defaults |
This endpoint will only create/show transactions with Type = Transfer. |
|
Requests allowed |
|
|
Primary key |
The primary key of a transaction line is |
|
Record ID |
The record ID is |
|
Procedures |
None |
Data
Field List
|
Property |
Type |
Format |
Description |
|
|---|---|---|---|---|
|
|
string |
uuid |
The automatic system ID, which is in GUID format. |
record id non-editable |
|
|
integer |
|
The Transaction this line belongs to.
|
PRIMARY KEY OPTIONAL |
|
|
integer |
|
The sequence number of this line, within the transaction which has ID = |
PRIMARY KEY non-editable |
|
|
string |
max 10 |
The terminal will indicate from which manufacturing unit or machine this entry comes from. This is mandatory, but if there is only one terminal, this can be set up as a default on page API Base Setup. |
OPTIONAL |
|
|
string |
max 10 |
The sender needs to use their own reference, because every transaction needs to be unique. The same external reference can be used repeatedly in order to add an item line to a transaction already created. |
Mandatory |
|
|
string |
date |
Date of the transfer. If not given, today. |
OPTIONAL |
|
|
string |
max 10 |
The current location of the item / trade item. On a new transaction, it is also the location of the transaction. If not given, the location of the transaction (see How it works > Endpoint). |
Mandatory * |
|
|
string |
max 20 |
Trade items: the current stock center. Set on the transaction, so it is the same for all lines. If not given, the default stock center (see How it works > Endpoint). Not used for standard items. |
OPTIONAL |
|
|
string |
max 10 |
The new location of the item / trade item. There is no default. |
Mandatory |
|
|
string |
max 20 |
Trade items: the new stock center, when it is to be changed. Must be an internal stock center. If not given, the stock center is not changed. Not used for standard items. |
OPTIONAL |
|
|
string |
max 20 |
Item No. of the item to be moved. |
Mandatory |
|
|
string |
max 10 |
The lot of the item to be moved. Required for lot tracked items: all trade items, and standard items with lot tracking. With a reference to a trade item, it can be skipped (taken from the trade item). |
Mandatory * |
|
|
decimal |
|
The quantity to move, in |
Mandatory * |
|
|
string |
max 10 |
The unit of measure that belongs to the This can be skipped if the Terminal has Populate Unit Automatically. Then the unit is the Trade Item Unit for trade items, and the Base Unit of Measure for standard items. |
Mandatory * |
|
|
decimal |
|
Only for irregular items: the weight of the moved trade items, when |
OPTIONAL |
|
|
string |
max 20 |
A direct reference to the moved trade item can be given with |
OPTIONAL |
|
|
integer |
|
See |
OPTIONAL |
|
|
string |
max 22 |
A direct reference to the moved trade item can also be given with its barcode. |
OPTIONAL |
|
|
date-time utc |
|
The system populates this value automatically. |
non-editable |
Example Object
Usage
The requests below are sent to .../api/wisefish/base/v1.0/companies({companyId})/mesTransfer, shortened to .../mesTransfer.
Transfer a Trade Item between locations
In the following example, 6 kg of an item are moved from OSLO to BERGEN, and at the same time from stock center OWN to FRIEND:
POST
.../mesTransfer
{
"externalReference": "06-may-t8",
"itemNo": "SALMON",
"quantity": 6,
"lot": "OR-00001",
"fromLocation": "OSLO",
"fromStockCenter": "OWN",
"toLocation": "BERGEN",
"toStockCenter": "FRIEND"
}
The response will show all the properties of the endpoint:
{
"@odata.etag": "W/\"JzIwOzEwMTIxMTg3NDgwMzgxMjMyMjgwMTswMDsn\"",
"systemId": "46c55af7-5f49-f111-b032-ccc8a446a9f5",
"transactionId": 432,
"lineNo": 1,
"terminal": "INNOVA",
"externalReference": "06-MAY-T8",
"date": "2026-05-06",
"fromLocation": "OSLO",
"fromStockCenter": "OWN",
"toLocation": "BERGEN",
"toStockCenter": "FRIEND",
"itemNo": "SALMON",
"lot": "OR-00001",
"quantity": 6,
"unitOfMeasure": "KG",
"weight": 0,
"tradeItemStage": "",
"tradeItemLineNo": 0,
"tradeItemBarcode": "",
"lastModified": "2026-05-06T15:26:35.587Z"
}
-
The primary key of the created transaction can be seen in property
transactionId -
The primary key of the transaction line is in 2 properties:
transactionIdandlineNo -
lineNohas value 1, which means that this is the first item line for this transaction.
Transfer one specific trade item
With a reference to the trade item (barcode, or tradeItemStage + tradeItemLineNo), quantity, unitOfMeasure and lot can be skipped: then the whole trade item is moved. Reserved trade items can only be transferred this way.
POST
.../mesTransfer
{
"externalReference": "06-may-t10",
"itemNo": "SALMON",
"tradeItemBarcode": "5145",
"fromLocation": "OSLO",
"toLocation": "BERGEN"
}
Transfer standard items between locations
When using standard items, it works in the same way, except stock centers are not used.
In this example the standard item is lot tracked:
POST
.../mesTransfer
{
"externalReference": "06-may-t9",
"itemNo": "80216-T",
"quantity": 1,
"lot": "ETH-LOT-03",
"fromLocation": "BERGEN",
"toLocation": "OSLO"
}
How it works
POST → the transaction is created with status Ready (or On Hold) → the job queue error checks it → and posts it → status Processed.
If anything is wrong, the status is Error and nothing is changed in BC. The error can be fixed and the transaction processed again.
-
Nothing is changed in BC until the transaction has been processed.
-
Reserved trade items can only be transferred whole, with a reference. Trade items on a pallet can only be transferred whole.
-
toLocationhas no default, it must always be given.
Endpoint
Each POST creates one line in table MES Transaction Line with Transaction Type = Transfer, and the response is returned immediately.
Header (MES Transaction)
The line is added to an existing transaction header, or a new header is created:
-
If
transactionIdis given, the line is added to that transaction. It must exist. -
Else, if a transaction with the same
terminal+externalReferenceexists, the line is added to it. -
Else a new transaction header is created.
When a line is added to an existing transaction, the transaction must not be Processed yet, and a given terminal and externalReference must match the transaction. A given fromStockCenter must be the same as the transaction's.
Default values on a new header:
|
Field |
Value |
|---|---|
|
Type |
Transfer |
|
Terminal |
|
|
Activity Date |
|
|
Location |
|
|
Stock Center |
|
|
Stage |
Terminal Default Stage, else User Profile. (Not used to find the trade items, see |
|
Status |
Ready, or On Hold if MES Terminal Control says transfers from this terminal/location are processed manually |
Line (MES Transaction Line)
Default values on the line, if not given in the request:
|
Field |
Value |
|---|---|
|
Line No. |
The next line number of the transaction |
|
From Location |
The location of the header |
|
To Stock Center |
The stock center of the header (= no change of stock center) |
|
Quantity, Unit, Lot |
With a reference to a trade item: the lot of the trade item and, if both |
|
Item No. |
Mapped to the BC item number, if Data Mapping is active |
|
Unit of Measure |
If |
|
Weight Unit of Measure |
The item's weight unit, if |
Errors in the response (nothing is created)
-
itemNois missing -
the terminal does not exist
-
externalReferenceis missing, or has already been used for another transaction from the same terminal (also archived transactions). Not checked if the Terminal has Disable Ext. Reference Check. -
no Location (neither given nor a default)
-
fromStockCenteris different from the stock center of the existing transaction -
tradeItemStage+tradeItemLineNorefer to a trade item that does not exist
Everything else is checked when the transaction is processed.
Processing
The MES processor (job queue) processes Ready transactions: first the error check, then the posting. Everything for one transaction is done in one unit: if anything fails, nothing is changed in BC, and the job queue continues with the next transaction.
Errors on the transaction (status Error, nothing posted)
-
Items: a transaction cannot have both trade items and standard items. The same item and lot can only be on one line, unless each line refers to its own trade item.
-
Locations:
toLocationis required and must exist. For trade items, the new location must allow trade items. -
Lot: required for lot tracked items. For trade items, a given lot must exist in BC. Without a reference, a lot is required.
-
To Stock Center: must exist and be an internal stock center.
-
Stock of trade items: an open trade item of the item and lot on
fromLocationand the transaction's stock center (andtradeItemStage, if given), that is not reserved: one with exactly the quantity, or else one with enough quantity that is not on a pallet. -
With a reference (
tradeItemBarcode, ortradeItemStage+tradeItemLineNo): the trade item must exist, be of the same item, on the same location, stock center and lot, and have enough quantity. A reserved trade item, or a trade item on a pallet, must be transferred whole. -
Irregular items: the number of trade items must come with a weight. Sending all the trade items but only part of the weight gives an error.
-
Stock of standard items: enough inventory of the item on
fromLocation(and lot). -
Standard items: an Item Journal Template of type Transfer with a batch that has a No. Series is needed.
Result (after posting)
Trade items
-
For each line, the trade item is moved to
toLocation(trade item reclassification journal). If a trade item with exactly the quantity exists, it is moved as it is. Otherwise the first trade item with enough quantity is split: the requested quantity is moved, the rest stays where it was, as a new trade item. The split and the transfer happen in the same posting. -
With a reference, that trade item is moved, whole or in part (split in the same way).
-
Irregular items: the number of trade items from MES is kept. Example: from 2 boxes weighing 20 kg, transferring 1 box of 12 kg moves 1 box/12 kg, and 1 box/8 kg stays.
-
If
toStockCenteris another stock center, the moved trade item gets the new stock center.
Standard items
-
For each line, the quantity is moved from
fromLocationtotoLocation(item reclassification journal), with the lot for lot tracked items. The Document No. comes from the No. Series of the Transfer journal batch.
The transaction gets status Processed.
The exact behaviour is described by the unit tests: MES Unit Tests - Transfer
Settings
Settings that change what happens in the endpoint or in processing:
|
Setting |
Where |
Step |
Effect |
|---|---|---|---|
|
Default Stage, Default Stock Center |
MES Terminal |
Endpoint |
Default values on the transaction header |
|
Location, Stock Center, Stage |
User Profile |
Endpoint |
Default values on the transaction header (the location only when |
|
Disable Ext. Reference Check |
MES Terminal |
Endpoint |
|
|
Populate Unit Automatically |
MES Terminal |
Endpoint |
Missing |
|
Process Manually |
MES Terminal Control |
Endpoint |
New transactions get status On Hold and are not processed by the job queue |
|
Item Journal Template of type Transfer, with a No. Series on the batch |
Item Journal Templates |
Processing |
Required for transfer of standard items |