API - MES Consumption


Overview

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

A consumption is the use of items in production: raw material, WIP or products (trade items), and standard items such as packaging and ingredients. The consumption is posted on a production lot. Standard items can also be consumed on a Released Production Order.

Working with a consumption 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 consumption in BC.

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

Endpoint name

mes/consumption

Source table

WiFiAPIs MES Transaction Line

Fixed view/defaults

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

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 could for example be one packing station. 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

lot

string

max 10

The production lot to post this consumption on. All lines of a transaction have the same lot.

Mandatory

productionDate

string

date

Date of the consumption. If not given, today.

OPTIONAL

itemNo

string

max 20

Item No. of the consumed item.

Mandatory

quantity

decimal


The consumed quantity, in unitOfMeasure. A negative quantity is a credit (see How it works).

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 consumed trade items, when quantity is the number of trade items. The weight is in the item's weight unit.

OPTIONAL

consumedLot

string

max 20

The lot of the consumed item. Required for lot tracked items: all trade items, and standard items with lot tracking.

Mandatory *

location

string

max 10

The location of the standard item to consume. If not given, the location of the transaction. (Trade items are found on any location.)

OPTIONAL

tradeItemStage

string

max 20

A direct reference to the consumed trade item can be given with tradeItemStage and tradeItemLineNo.

OPTIONAL

tradeItemLineNo

integer


See tradeItemStage.

OPTIONAL

tradeItemBarcode

string

max 22

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

OPTIONAL

documentType

string

enum

Only used for consumption on a Production Order: ProductionOrder.

If skipped, it is found from documentNo (see How it works > Endpoint). The Document Type is shown in the response.

OPTIONAL

documentNo

string

max 20

The number of a Released Production Order, when standard items are consumed on the order. Skip it for consumption on production lots.

If documentType is not given, the endpoint gives an error if no Released Production Order with this number is found.

When adding a line to a current Transaction, the documentNo is not necessary. But if it is given, it must match the document number on the transaction.

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": "034b2491-6442-f111-b032-f77a5b8523f9",
    "transactionId": 368,
    "lineNo": 3,
    "terminal": "INNOVA",
    "externalReference": "27-APR-C2",
    "lot": "COD-01",
    "productionDate": "2026-04-27",
    "itemNo": "100",
    "quantity": 150,
    "unitOfMeasure": "KG",
    "weight": 0,
    "consumedLot": "OR-35456",
    "location": "PROD",
    "tradeItemStage": "",
    "tradeItemLineNo": 0,
    "tradeItemBarcode": "",
    "documentType": "None",
    "documentNo": "",
    "lastModified": "2026-04-27T18:11:53.443Z"
}

Usage

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

Create a consumption transaction for a single item

Using an “External Reference” that does not exist on an existing transaction, will result in the creation of a new Transaction.

In the following example, 150 kg of raw material from lot OR-35456 are consumed on production lot COD-01:

JSON
POST
.../mesConsumption

{
    "terminal": "INNOVA",
    "externalReference": "27-apr-c2",    
    "productionDate": "2026-04-27",    
    "itemNo": "100",
    "lot": "COD-01",
    "quantity": 150,
    "unitOfMeasure": "kg",
    "consumedLot": "OR-35456"
}

The response will show all the properties of the endpoint. See the example object above.

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


Add an item to an existing consumption transaction

As for other endpoints, posting again with the transactionId just created, or with the same externalReference, will add a new line on the same transaction. See examples on API - MES Output


Consume a specific trade item

Without a reference, the consumption is taken from the trade items of the item on the consumed lot, oldest first. To consume from one specific trade item, give its barcode (or tradeItemStage + tradeItemLineNo):

JSON
POST
.../mesConsumption

{
    "terminal": "INNOVA",
    "externalReference": "27-apr-c3",
    "itemNo": "70064",
    "lot": "COD-01",
    "quantity": 1,
    "unitOfMeasure": "BOX",
    "consumedLot": "LOT-03-01",
    "tradeItemBarcode": "5145"
}


Credit a consumption

A consumption is credited by sending the same line with a negative quantity. For trade items, only a whole consumed entry can be credited, so the quantity must be the same as was consumed:

JSON
POST
.../mesConsumption

{
    "terminal": "INNOVA",
    "externalReference": "27-apr-c2-cr",
    "itemNo": "100",
    "lot": "COD-01",
    "quantity": -150,
    "unitOfMeasure": "kg",
    "consumedLot": "OR-35456"
}


Consumption of standard items on a Production Order

Standard items (BC items, not trade items) can be consumed on a Released Production Order. The documentNo is the Production Order No. (documentType can be skipped). In this example 10 PCS of item 2000 are consumed from lot L-2026-11 on Production Order 101003:

JSON
POST
.../mesConsumption

{
    "terminal": "INNOVA",
    "externalReference": "PO-101003-C1",
    "productionDate": "2026-11-03",
    "documentNo": "101003",
    "lot": "2026-11-03",
    "itemNo": "2000",
    "quantity": 10,
    "unitOfMeasure": "PCS",
    "consumedLot": "L-2026-11"
}

The response shows "documentType": "ProductionOrder".


Create a bulk transaction of multiple consumed items for the same production lot

The Transactions endpoint can be used to create a transaction with many lines in one request:

JSON
POST
.../transactions?$expand=transactionLines

{   
    "terminal": "PACKING",
    "externalReference": "27-4-B-C1",
    "type": "Consumption",
    "lot": "15-04-01",
    "transactionLines": [
        {
            "itemNo": "100",
            "quantity": 10,
            "unitOfMeasure": "KG",
            "consumedLot": "LOT-03-01"
        },
        {
            "itemNo": "70064",
            "quantity": 9,
            "unitOfMeasure": "KG",
            "consumedLot": "CREDIT-TEST5"
        }
    ]
}

=> A transaction with 2 lines will be created

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 (no lots or item ledger entries) until the transaction has been processed.

  • Standard items can only be consumed on a production lot that already has output (not needed on Production Orders).

  • For trade items, a consumption can only be credited as a whole consumed entry.

Endpoint

Each POST creates one line in table MES Transaction Line with Transaction Type = Consumption, 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, documentNo and lot must match the transaction.

Default values on a new header:

Field

Value

Type

Consumption

Terminal

terminal, or the default terminal

Activity Date

productionDate, or today

Lot

lot of the first line

Document Type

Only if documentNo is given: documentType, or if not given: Production Order, if a Released Production Order with this number exists, else a Production Agreement

→ Production Agreement (gives an error when processed)”, as on the Output page.

Location

Terminal Production Location, else User Profile

Stock Center

From the Lot, else Terminal Default Stock Center, else User Profile

Stage

Lot Processing Stage, else Terminal Production Stage, else User Profile

Status

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

Credit

Set when a line has a negative quantity

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

From 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 a default nor given)

  • lot is missing

  • documentNo is given without documentType, but no Released Production Order or Production Agreement is found with this number

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: trade items and standard items are consumed on production lots, without a document. Standard items can also be consumed on a Released Production Order; a trade item on a Production Order gives an error. Other documents are not supported. A transaction cannot have both trade items and standard items.

  • Production lot: must exist in BC, unless the Terminal has Production Lot Created in MES (then the lot is created). The lot must be a production lot, on the same Stock Center as the transaction. If the Stock Center has Only Active Lots in Production, the lot must be active. The lot's Allowed Raw Material, Unique Raw Material and Unique Production Day are checked against the consumed item and date. Standard items: the lot must have output. (On Production Orders, a production lot that does not exist in BC is not checked.)

  • Stage: required.

  • Consumed lot: required for lot tracked items. The same item and consumed lot can only be on one line of the transaction.

  • Stock of trade items: enough open trade items of the item on the consumed lot, on the transaction's Stock Center (any location). Reserved trade items are not used. With a reference (tradeItemBarcode, or tradeItemStage + tradeItemLineNo), that trade item must exist, be of the same item and on the consumed lot, not be reserved and have enough quantity. Irregular items: the number of trade items must come with a weight.

  • Stock of standard items: enough inventory of the item on the line's location (and consumed lot).

  • Production Order: must exist and be Released. If the order is for a Sales Order, the Sales Order must exist and be released. A Consumption journal (Item Journal Template of type Consumption) with a batch that has a No. Series is needed.

  • Credit: trade items: a consumed entry with exactly the credited quantity must be found (with a reference, that trade item's entry). The production lot must exist in BC (not on Production Orders).

Result (after posting)

Trade items on a production lot

  • The production lot is created if it does not exist.

  • For each line, the consumption is posted (trade item journal, entry type Consumption) on the production lot: from the referenced trade item, or from the trade items on the consumed lot, oldest first. A trade item can be consumed in part or as a whole.

Standard items on a production lot

  • The consumption is posted through the trade item journal, from the line's location and consumed lot. Wisefish splits the consumption on the products of the lot.

Standard items on a Production Order

  • For each line, consumption is posted on the Production Order (item journal, entry type Consumption), with the quantity and unit of the line, from the line's location and consumed lot. The Document No. comes from the No. Series of the Consumption journal batch.

Credit (negative quantity)

  • Trade items: the consumed entry is reversed, and the trade item is back in stock. Standard items: the credited quantity is back in stock (on Production Orders, the consumption on the order is reduced).

The transaction gets status Processed.

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

Settings

Settings that change what happens in the endpoint or in processing:

Setting

Where

Step

Effect

Production Location, Production Stage, Default Stock Center

MES Terminal

Endpoint

Default values on the transaction header

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

Production Lot Created in MES

MES Terminal

Processing

On: an unknown production lot is created. Off: the lot must exist in BC.

Only Active Lots in Production

Stock Center

Processing

Consumption only on lots that are active in production

Allowed Raw Material, Unique Raw Material, Unique Production Day

Lot

Processing

Limit which item can be consumed on the lot, and on which date

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

Item Journal Templates

Processing

Required for consumption of standard items on Production Orders