API - Items

Overview

The API is a light-weight list of Items. No data update allowed. For updating or for viewing details use itemDetails.

Data

Field List

Object Example

{
    "number": "70079",
    "systemId": "473e5d0f-f6a8-f011-b027-fa32451b10aa",
    "description": "Cod fillets (3 kg box)",
    "packageDescriptionType": "Trade Item",
    "packageDescription": "1 x 3kg",
    "tradeItemType": "Product",
    "itemCategoryCode": "",
    "rawMaterialReportingCode": "001",
    "inventoryPostingGroup": "RESALE",
    "blocked": false,
    "status": " ",
    "baseUnitOfMeasure": "KG",
    "tradeItemUnitOfMeasure": "BOX",
    "palletUnitOfMeasure": "PALLET",
    "weightUnitOfMeasure": "KG",
    "unitPrice": 0,
    "priceIncludesTax": false,
    "unitCost": 0,
    "gtin": "",
    "gtinTradeItem": "",
    "gtinOuter": "",
    "systemRowVersion": 2581734,
    "lastModified": "2025-12-17T16:22:57.803Z"
}

Procedures

Procedures are called on a specific item: POST items('<number>')/Microsoft.NAV.<procedureName> with a JSON body of parameters. Each procedure returns a text message in the value property of the response on success. On failure it returns an error with a readable message.

Parameter names are case-sensitive, and the procedure name starts with a capital letter (AddNote).

Notes

Add Note

The procedure AddNote adds a note to the item. The note is a Business Central Note record link with the description “Sent through API”, and it is registered as from the API user (the user making the call).

POST
.../items([record-id])/Microsoft.NAV.AddNote

Body:
{
    "noteText": [the text of the note]
}

Possible errors:

• The item does not exist (standard Business Central error, record not found).

• noteText is longer than 250 characters (standard Business Central error, the text exceeds the parameter length).

Behaviour notes:

• The note text is not validated: an empty noteText is not rejected, an empty note is added.

• The note is a Note type record link with the description “Sent through API”, created with the current date and time.

Notes can be read with the Record Notes API, see API - Record Notes in this space.

Add Note from a User

The procedure AddNoteFromUser works the same way as AddNote, but the note is registered as from the given Business Central user instead of the API user.

POST
.../items([record-id])/Microsoft.NAV.AddNoteFromUser

Body:
{
    "noteText": [the text of the note],
    "fromUser": [the BC user ID the note is registered from]
}

Possible errors:

• The item does not exist (standard Business Central error, record not found).

• A parameter is longer than its maximum length (standard Business Central error, the text exceeds the parameter length).

• User with ID <fromUser> does not exist (when fromUser is not found in User Setup)

Behaviour notes:

• fromUser is a code parameter, so the value is converted to upper case: "john" is registered and returned as JOHN.

• If fromUser is empty, no user check is made and the note is registered as from the API user (same as AddNote), but the response text then ends with an empty user ID: Note successfully added and registered from user .

• The note text is not validated: an empty noteText is not rejected.

Examples

The following are just some examples of usage.

Read items

Read all entries

Reads all items, both standard items and trade items. The response is a list of item objects, as shown in Object Example.

GET
.../items

Read all entries with a filter

This request would return all Items in the Item Category called FISH.

GET
.../items?$filter=itemCategoryCode eq 'FISH'

Read one item

Reads one item by its Record ID (number). The response is one item object.

Request:

GET .../items('70079')

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#items/$entity",
    "@odata.etag": "W/\"JzE5OzEyMjQ1NjE5ODc0NTUxMjM0NTYxOzAwOyc=\"",
    "number": "70079",
    "systemId": "473e5d0f-f6a8-f011-b027-fa32451b10aa",
    "description": "Cod fillets (3 kg box)",
    "packageDescriptionType": "Trade Item",
    "packageDescription": "1 x 3kg",
    "tradeItemType": "Product",
    "itemCategoryCode": "",
    "rawMaterialReportingCode": "001",
    "inventoryPostingGroup": "RESALE",
    "blocked": false,
    "status": " ",
    "baseUnitOfMeasure": "KG",
    "tradeItemUnitOfMeasure": "BOX",
    "palletUnitOfMeasure": "PALLET",
    "weightUnitOfMeasure": "KG",
    "unitPrice": 0,
    "priceIncludesTax": false,
    "unitCost": 0,
    "gtin": "",
    "gtinTradeItem": "",
    "gtinOuter": "",
    "systemRowVersion": 2581734,
    "lastModified": "2025-12-17T16:22:57.803Z"
}

Read selected properties of products

Reads only the number, description and units of non-blocked items of trade item type Product, using $filter and $select (the response is shortened).

Request:

GET .../items?$filter=tradeItemType eq 'Product' and blocked eq false&$select=number,description,packageDescription,baseUnitOfMeasure,tradeItemUnitOfMeasure

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#items(number,description,packageDescription,baseUnitOfMeasure,tradeItemUnitOfMeasure)",
    "value": [
        {
            "@odata.etag": "W/\"JzE5OzEyMjQ1NjE5ODc0NTUxMjM0NTYxOzAwOyc=\"",
            "number": "70079",
            "description": "Cod fillets (3 kg box)",
            "packageDescription": "1 x 3kg",
            "baseUnitOfMeasure": "KG",
            "tradeItemUnitOfMeasure": "BOX"
        }
    ]
}

Add notes

Add a note to an item

Adds the note “Quality check completed” to item 70079 with AddNote; the note is registered as from the API user.

Request:

POST .../items('70079')/Microsoft.NAV.AddNote
{
    "noteText": "Quality check completed"
}

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Note successfully added"
}

Add a note to an item from a specific user

Adds the same note to item 70079 with AddNoteFromUser, registered as from user JOHN.

Request:

POST .../items('70079')/Microsoft.NAV.AddNoteFromUser
{
    "noteText": "Quality check completed",
    "fromUser": "JOHN"
}

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Note successfully added and registered from user JOHN"
}

Add a note from a user that does not exist

Calls AddNoteFromUser with a user ID that is not in User Setup; the call fails and no note is added (the error message is shortened).

Request:

POST .../items('70079')/Microsoft.NAV.AddNoteFromUser
{
    "noteText": "Quality check completed",
    "fromUser": "NOBODY"
}

Response:

{
    "error": {
        "code": "Application_DialogException",
        "message": "User with ID NOBODY does not exist"
    }
}