API - MES Adjustment


Overview

This is an API to create an adjustment transaction in the MES transaction queue.

An adjustment adds stock (positive adjustment) or removes stock (negative adjustment), depending on the sign of quantity. Both trade items and standard items can be adjusted.

Working with an adjustment 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 adjustment in BC.

See more information about the workflow: MES Use Case: Production

Endpoint name

mes/adjustment older: mesAdjustment

Source table

WiFiAPIs MES Transaction Line

Fixed view/defaults

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

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 adjustment. If not given, today.

OPTIONAL

location

string

max 10

The location of the item / trade item to adjust. 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 *

stockCenter

string

max 20

Trade items: the stock center to adjust on. 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

itemNo

string

max 20

Item No. of the item to be adjusted.

Mandatory

lot

string

max 10

The lot of the item to be adjusted. Required for lot tracked items: all trade items, and standard items with lot tracking. For trade items, the lot must exist in BC.

Mandatory *

quantity

decimal


The quantity to adjust, in unitOfMeasure. Positive = positive adjustment, negative = negative adjustment. All lines of a transaction must have the same sign.

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 adjusted trade items, when quantity is the number of trade items. The weight is in the item's weight unit, and has the same sign as quantity.

OPTIONAL

tradeItemStage

string

max 20

Only for negative adjustments: a direct reference to the adjusted trade item can be given with tradeItemStage and tradeItemLineNo. Given alone, only trade items on this stage are adjusted.

OPTIONAL

tradeItemLineNo

integer


See tradeItemStage.

OPTIONAL

tradeItemBarcode

string

max 22

Only for negative adjustments: a direct reference to the adjusted 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": "d5322078-5d49-f111-b032-ccc8a446a9f5",
    "transactionId": 431,
    "lineNo": 1,
    "terminal": "INNOVA",
    "externalReference": "06-MAY-A3",
    "date": "2026-05-06",
    "location": "OSLO",
    "stockCenter": "OWN",
    "itemNo": "SALMON",
    "lot": "OR-00001",
    "quantity": 10,
    "unitOfMeasure": "KG",
    "weight": 0,
    "tradeItemStage": "",
    "tradeItemLineNo": 0,
    "tradeItemBarcode": "",
    "lastModified": "2026-05-06T15:08:43.137Z"
}

Usage

The requests below are sent to .../api/wisefish/base/v1.0/companies({companyId})/mesAdjustment, shortened to .../mesAdjustment.

Positive adjustment of a trade item lot by 20 KG

In this example 20 kg of raw material are added to lot SAL0805 on location BERGEN:

JSON
POST
.../mesAdjustment

{   
    "externalReference": "08-may-a5",
    "itemNo": "SALMON",
    "lot": "SAL0805",
    "location": "BERGEN",
    "quantity": 20,
    "unitOfMeasure": "KG"
}

The response has all properties of the endpoint:

JSON
{
    "@odata.etag": "W/\"JzIwOzE3NDUxOTE5MDgwMjA0MjMwMzMxMTswMDsn\"",
    "systemId": "06dfda4e-c94a-f111-b032-f84273c39f63",
    "transactionId": 469,
    "lineNo": 1,
    "terminal": "INNOVA",
    "externalReference": "08-MAY-A5",
    "date": "2026-05-08",
    "location": "BERGEN",
    "stockCenter": "OWN",
    "itemNo": "SALMON",
    "lot": "SAL0805",
    "quantity": 20,
    "unitOfMeasure": "KG",
    "weight": 0,
    "tradeItemStage": "",
    "tradeItemLineNo": 0,
    "tradeItemBarcode": "",
    "lastModified": "2026-05-08T10:33:10.71Z"
}
  • 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


Negative adjustment of a specific trade item

A negative quantity removes stock. With a reference, the stock is taken from that trade item:

JSON
POST
.../mesAdjustment

{   
    "externalReference": "08-may-a6",
    "itemNo": "SALMON",
    "lot": "SAL0805",
    "location": "BERGEN",
    "quantity": -5,
    "unitOfMeasure": "KG",
    "tradeItemBarcode": "5145"
}


Adjust a standard item stock

When using standard items, it works in the same way, except stock centers and stages are not used, even though they appear on the transaction.

JSON
POST
.../mesAdjustment

{   
    "externalReference": "08-may-std",
    "itemNo": "70074",
    "location": "OSLO",
    "quantity": 5,
    "unitOfMeasure": "STK"
}

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.

  • All lines of a transaction must be either positive or negative.

  • A negative adjustment of trade items with more than one line needs a reference to a trade item on each line.

Endpoint

Each POST creates one line in table MES Transaction Line with Transaction Type = Adjustment, 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, externalReference and lot must match the transaction. A given stockCenter must be the same as the transaction's.

Default values on a new header:

Field

Value

Type

Adjustment

Terminal

terminal, or the default terminal

Activity Date

date, or today

Lot

lot of the first line

Location

location 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 on its own location.

Stock Center

stockCenter, else from the Lot, else Terminal Default Stock Center, else User Profile

Stage

Lot Processing Stage, else Terminal Default Stage, else User Profile. This becomes the stage of new trade items (positive adjustment). It is not used to find trade items (negative adjustment), see tradeItemStage.

Status

Ready, or On Hold if MES Terminal Control says adjustments from this terminal/location are processed manually

Credit

Set when a line has a negative quantity (negative adjustment)

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

Lot

From the header

Location

The location of the header

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)

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

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. All lines must have the same sign (all positive or all negative), and the weight must have the same sign as the quantity.

  • Location: must exist. For trade items, it must use trade items.

  • Stock Center: required for trade items, and must exist.

  • Lot: required for lot tracked items. For trade items, the lot must exist in BC. A production lot is checked like for output (e.g. Only Active Lots in Production). A positive adjustment on a production lot needs Allow Pos. Adjmt to Prod. Lot on the User Profile (Wisefish rule).

  • Stock center of the lot: trade items can only be adjusted on another stock center than the lot's if API Base Setup has Transfer Adj. to Stock Center.

  • Stage: required for a positive adjustment of trade items.

  • Irregular items: the number of trade items must come with a weight.

  • Negative adjustment of trade items: an open trade item of the item and lot on the line's location and the transaction's stock center (and tradeItemStage, if given): one with exactly the quantity, or else one with enough quantity. Reserved trade items are only used if Trade Item Setup has Allow to credit Reserved TIs. With more than one line, each line must refer to its own trade item. The same item and lot can only be on one line without a reference.

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

  • Standard items: negative: enough inventory of the item on the line's location (and lot); the same item and lot only once. An Item Journal Template of type Item with a batch that has a No. Series is needed.

Result (after posting)

Positive adjustment of trade items

  • For each line, a new trade item is created on the lot, with the stage, location and stock center of the transaction (trade item journal, positive adjustment). Several lines with the same item and lot give several trade items.

  • Irregular items: quantity in the base unit = one trade item with that weight; or quantity = number of trade items, with weight.

Negative adjustment of trade items

  • For each line, the quantity is removed from the trade item: the one with exactly the quantity, else the first with enough, or the referenced trade item. A trade item can be adjusted in part or as a whole.

  • Irregular items: the weight decides the quantity that is removed, not the number of trade items.

Other stock center than the lot's (with Transfer Adj. to Stock Center)

  • The trade item is moved between the lot's stock center and the transaction's in the same posting, so the transaction's stock center is where the stock is. No other MES transactions are created. If the lot has no other trade items, the lot moves to the new stock center as well.

Standard items

  • For each line, a positive or negative adjustment is posted on the line's location (item journal), with the lot for lot tracked items. The Document No. comes from the No. Series of the item journal batch.

The transaction gets status Processed.

The exact behaviour is described by the unit tests: MES Unit Tests - Adjustment

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 location 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

Transfer Adj. to Stock Center

API Base Setup

Processing

Trade items can be adjusted on another stock center than the lot's

Allow to credit Reserved TIs

Trade Item Setup

Processing

Negative adjustment: reserved trade items can also be adjusted

Allow Pos. Adjmt to Prod. Lot

User Profile

Processing

Required for a positive adjustment on a production lot (Wisefish rule)

Item Journal Template of type Item, with a No. Series on the batch

Item Journal Templates

Processing

Required for adjustment of standard items