API - MES Transfer


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):

  1. Endpoint: the MES posts to the endpoint, and the MES transaction is created. Nothing else is changed in BC yet.

  2. 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

mes/transfer older: mesTransfer

Source table

WiFiAPIs MES Transaction Line

Fixed view/defaults

This endpoint will only create/show transactions with Type = Transfer.

Requests allowed

  • POST is used to create transactions

  • PATCH is not allowed.

  • DELETE is not allowed.

  • GET is possible, but not recommended since this endpoint is specifically designed to insert entries. To view transactions, it is better to use API - MES Transactions

Primary key

The primary key of a transaction line is transactionId + lineNo

Record ID

The record ID is systemId

Procedures

None

Data

Field List

Property

Type

Format

Description


systemId

string

uuid

The automatic system ID, which is in GUID format.

record id

non-editable

transactionId

integer


The Transaction this line belongs to.

  • Skip this when creating a new transaction.

  • Can be used to add a line to a transaction that already has been created. If used, the transaction with this ID must already exist. It is not possible to use an ID that does not exist.

PRIMARY KEY

OPTIONAL

lineNo

integer


The sequence number of this line, within the transaction which has ID = transactionId. This is set automatically as the next number.

PRIMARY KEY

non-editable

terminal

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

externalReference

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

date

string

date

Date of the transfer. If not given, today.

OPTIONAL

fromLocation

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 *

fromStockCenter

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

toLocation

string

max 10

The new location of the item / trade item. There is no default.

Mandatory

toStockCenter

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

itemNo

string

max 20

Item No. of the item to be moved.

Mandatory

lot

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 *

quantity

decimal


The quantity to move, in unitOfMeasure. With a reference to a trade item, quantity and unitOfMeasure can both be skipped: then the whole trade item is moved.

Mandatory *

unitOfMeasure

string

max 10

The unit of measure that belongs to the quantity field.

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 *

weight

decimal


Only for irregular items: the weight of the moved trade items, when quantity is the number of trade items. The weight is in the item's weight unit.

OPTIONAL

tradeItemStage

string

max 20

A direct reference to the moved trade item can be given with tradeItemStage and tradeItemLineNo. Given alone, only trade items on this stage are moved.

OPTIONAL

tradeItemLineNo

integer


See tradeItemStage.

OPTIONAL

tradeItemBarcode

string

max 22

A direct reference to the moved trade item can also be given with its barcode.

OPTIONAL

lastModified

date-time utc


The system populates this value automatically.

non-editable


Example Object

Expand to see the example json

An example of one object :

JSON
{
    "systemId": "ac322c0f-5949-f111-b032-ccc8a446a9f5",
    "transactionId": 428,
    "lineNo": 1,
    "terminal": "INNOVA",
    "externalReference": "06-MAY-T6",
    "date": "2026-05-06",
    "fromLocation": "OSLO",
    "fromStockCenter": "OWN",
    "toLocation": "BERGEN",
    "toStockCenter": "OWN",
    "itemNo": "SALMON",
    "lot": "OR-00001",
    "quantity": 6,
    "unitOfMeasure": "KG",
    "weight": 0,
    "tradeItemStage": "",
    "tradeItemLineNo": 0,
    "tradeItemBarcode": "",
    "lastModified": "2026-05-06T14:37:09.073Z"
}

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:

JSON
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:

JSON
{
    "@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: transactionId and lineNo

  • lineNo has 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.

JSON
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:

JSON
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.

  • toLocation has 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 transactionId is given, the line is added to that transaction. It must exist.

  • Else, if a transaction with the same terminal + externalReference exists, 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

terminal, or the default terminal

Activity Date

date, or today

Location

fromLocation of the first line, else User Profile. The header location is checked when processed (it must exist, and use trade items for trade items). Each line is posted from its own fromLocation, so a transaction can have lines with different locations.

Stock Center

fromStockCenter, else Terminal Default Stock Center, else User Profile

Stage

Terminal Default Stage, else User Profile. (Not used to find the trade items, see tradeItemStage.)

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 quantity and unitOfMeasure are skipped, the whole trade item

Item No.

Mapped to the BC item number, if Data Mapping is active

Unit of Measure

If quantity is given without a unit and the Terminal has Populate Unit Automatically: the trade item unit (trade items) or base unit (standard items)

Weight Unit of Measure

The item's weight unit, if weight is given

Errors in the response (nothing is created)

  • itemNo is missing

  • the terminal does not exist

  • externalReference is 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)

  • fromStockCenter is different from the stock center of the existing transaction

  • tradeItemStage + tradeItemLineNo refer 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: toLocation is 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 fromLocation and the transaction's stock center (and tradeItemStage, 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, or tradeItemStage + 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 toStockCenter is another stock center, the moved trade item gets the new stock center.

Standard items

  • For each line, the quantity is moved from fromLocation to toLocation (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 fromLocation is not given)

Disable Ext. Reference Check

MES Terminal

Endpoint

externalReference is not required and not checked for uniqueness

Populate Unit Automatically

MES Terminal

Endpoint

Missing unitOfMeasure is taken from the item

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