API - Purchase Agreement Lines

Overview

The list page that contains the Receipt Agreement Lines in Wisefish.

It contains the lines of both Blanket and Receipt purchase agreements. The same lines are also available as the child purchaseAgreementLines of the purchaseAgreements, openPurchaseAgreements and closedPurchaseAgreements endpoints (with $expand=purchaseAgreementLines).

Data

Field List

Object Example

In the following example the system is in KG, but this item is sold in LBS. Therefore:

• User has typed in the number of trade items: 100 LB which can be seen in fields noOfTradeItems and tradeItemUnitOfMeasure

• Fields quantity and unitOfMeasure show that this is roughly 45 KG. When this line is posted, this will go into the Item Ledger as “quantity”.

• Fields quantityBase and baseUnitOfMeasure show that this will be posted in the Item Ledger Entry as “base quantity” 100 LB.

• Fields netWeight and grossWeight will show how much weight this is in the general weight unit of the system which is in this case KG.

{
    "systemId": "b2fece31-c408-f111-b02e-e6f9cc72e785",
    "documentType": "Receipt",
    "documentNo": "PR-048",
    "lineNo": 10000,
    "type": "Item",
    "itemNo": "70080",
    "description": "Some item in LBS",
    "noOfTradeItems": 100,
    "tradeItemUnitOfMeasure": "LB",
    "quantity": 45.35924,
    "unitOfMeasure": "KG",
    "quantityBase": 100.00000,
    "baseUnitOfMeasure": "LB",
    "directUnitCost": 0,
    "unitCost": 0,
    "lineAmount": 0,
    "lineDiscount": 0,
    "lineDiscountAmount": 0,
    "amount": 0,
    "vat": 25,
    "amountIncludingVAT": 0,
    "productionDate": "0001-01-01",
    "originalProducer": "",
    "lot": "",
    "netWeight": 45.359,
    "grossWeight": 45.813,
    "landingDate": "0001-01-01",
    "portOfLanding": "",
    "addComment": "",
    "systemRowVersion": 2587311,
    "lastModified": "2026-02-13T10:18:43.637Z",
    "modifiedByUser": ""
}

Procedures

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

Lots

Assign Lot

To create a new origin lot and assign it to the agreement line, use procedure assignLot. This is an alternative to creating the lot first with the lots endpoint and then setting lot on the line.

POST
.../purchaseAgreementLines([systemId])/Microsoft.NAV.assignLot

Body:
{
    "lotCode": [code of the new lot, or empty],
    "lotDescription": [description of the new lot]
}

Possible errors:

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

• A lot with the code lotCode already exists (standard Business Central error, the record already exists).

• No lot code can be assigned from the number series when lotCode is empty (standard Business Central number series error).

• The line has no stock center (standard Business Central TestField error: Stock Center Code must have a value).

• Any validation error when the stock center is set on the lot, or when the lot is set on the line (lot).

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

Behaviour notes:

• The new lot is an origin lot: production type (blank), default hold status (blank), creation date today. Its stock center is the stock center of the line, and its ending date is the expected receipt date of the line.

• The lot is created before the line is checked. If any step fails, nothing is saved: the lot is not created and the line is not changed.

• The status of the agreement is not checked.

• A lot that already exists cannot be assigned with this procedure. To use an existing lot, set lot with PATCH.

Line Comments

For each Agreement Line there is a table for adding comment. Looks like this in BC:

Instead of handling this with APIs on the comment table itself, there are shortcut methods on this API:

• addCommentLine

• updateCommentLine

Add Comment Line

To add a comment line to the agreement line, use procedure addCommentLine:

POST
.../purchaseAgreementLines([systemId])/Microsoft.NAV.addCommentLine

Body:
{
    "comment": [the comment text]
}

Possible errors:

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

• comment is longer than 80 characters (standard Business Central error).

Behaviour notes:

• The comment lines of an agreement line are numbered 1, 2, 3 … The new comment line gets the next number after the last one.

• The comment line gets today's date, and both Print on Order and Print on Invoice are set.

• The comment text is not validated: an empty comment adds an empty comment line.

• A comment line can also be added together with POST or PATCH on the line, with the property addComment.

Update Comment Line

To change the text of an existing comment line, use procedure updateCommentLine:

POST
.../purchaseAgreementLines([systemId])/Microsoft.NAV.updateCommentLine

Body:
{
    "commentLineNo": [line no. of the comment line],
    "comment": [the new comment text]
}

Possible errors:

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

• comment is longer than 80 characters (standard Business Central error).

Behaviour notes:

• Only the comment text is changed; the date of the comment line is not changed.

Examples

Read agreement lines

Read the lines of one agreement

Reads all lines of purchase agreement PR-048.

GET .../purchaseAgreementLines?$filter=documentNo eq 'PR-048'

Read selected properties of a line

Reads only the item and quantities of one line, by its Record ID (systemId).

Request:

GET .../purchaseAgreementLines(b2fece31-c408-f111-b02e-e6f9cc72e785)?$select=documentNo,lineNo,itemNo,noOfTradeItems,tradeItemUnitOfMeasure,quantity,unitOfMeasure

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/purchaseAgreementLines(documentNo,lineNo,itemNo,noOfTradeItems,tradeItemUnitOfMeasure,quantity,unitOfMeasure)/$entity",
    "@odata.etag": "W/\"JzIwOzEyMzQ1Njc4OTAxMjM0NTY3ODkwMTE7MDA7Jw==\"",
    "documentNo": "PR-048",
    "lineNo": 10000,
    "itemNo": "70080",
    "noOfTradeItems": 100,
    "tradeItemUnitOfMeasure": "LB",
    "quantity": 45.35924,
    "unitOfMeasure": "KG"
}

Read an agreement with its lines

Reads purchase agreement PR-048 with its lines, through the parent endpoint.

GET .../purchaseAgreements?$filter=documentNo eq 'PR-048'&$expand=purchaseAgreementLines

Add, change and delete lines

Add a line to an agreement

Adds a line for 100 LB of item 70080 to agreement PR-048, with a comment line. lineNo is not given, so it is set automatically (last line no. + 100).

Request:

POST .../purchaseAgreementLines

Body:
{
    "documentType": "Receipt",
    "documentNo": "PR-048",
    "itemNo": "70080",
    "noOfTradeItems": 100,
    "tradeItemUnitOfMeasure": "LB",
    "productionDate": "2026-02-12",
    "addComment": "This will be delivered on pallets"
}

Response (shortened):

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/purchaseAgreementLines/$entity",
    "@odata.etag": "W/\"JzIwOzE4MjczNjQ1NTQ2MzcyODE5MjAxOzAwOyc=\"",
    "systemId": "c41a7d52-c408-f111-b02e-e6f9cc72e785",
    "documentType": "Receipt",
    "documentNo": "PR-048",
    "lineNo": 10100,
    "type": "Item",
    "itemNo": "70080",
    "description": "Some item in LBS",
    "noOfTradeItems": 100,
    "tradeItemUnitOfMeasure": "LB",
    "quantity": 45.35924,
    "unitOfMeasure": "KG",
    "productionDate": "2026-02-12",
    "addComment": "",
    "systemRowVersion": 2587402,
    "lastModified": "2026-02-13T11:02:15.210Z"
}

Change a line

Changes the number of trade items on a line. A PATCH request needs the If-Match header with the @odata.etag of the record (or *).

Request:

PATCH .../purchaseAgreementLines(b2fece31-c408-f111-b02e-e6f9cc72e785)
If-Match: *

Body:
{
    "noOfTradeItems": 120
}

Response (shortened):

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/purchaseAgreementLines/$entity",
    "@odata.etag": "W/\"JzIwOzk4NzY1NDMyMTAxMjM0NTY3ODkwOzAwOyc=\"",
    "systemId": "b2fece31-c408-f111-b02e-e6f9cc72e785",
    "documentType": "Receipt",
    "documentNo": "PR-048",
    "lineNo": 10000,
    "itemNo": "70080",
    "noOfTradeItems": 120,
    "tradeItemUnitOfMeasure": "LB",
    "quantity": 54.43109,
    "unitOfMeasure": "KG",
    "systemRowVersion": 2587455,
    "lastModified": "2026-02-13T11:20:41.004Z"
}

Delete a line

Deletes one agreement line. On success the response is empty (HTTP status 204 No Content).

DELETE .../purchaseAgreementLines(b2fece31-c408-f111-b02e-e6f9cc72e785)

Assign a lot

Assign a new lot with a given code

Creates lot LOT-PR048-1 and assigns it to the line with assignLot.

Request:

POST .../purchaseAgreementLines(b2fece31-c408-f111-b02e-e6f9cc72e785)/Microsoft.NAV.assignLot

Body:
{
    "lotCode": "LOT-PR048-1",
    "lotDescription": "Cod, landing 12 February"
}

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Lot LOT-PR048-1 assigned to the purchase line."
}

Assign a lot numbered from the number series

Creates a lot with a code from the number series (lotCode empty) and assigns it to the line.

Request:

POST .../purchaseAgreementLines(b2fece31-c408-f111-b02e-e6f9cc72e785)/Microsoft.NAV.assignLot

Body:
{
    "lotCode": "",
    "lotDescription": ""
}

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Lot LOT000123 assigned to the purchase line."
}

Comment lines

Add a comment to a line

Adds the comment “This will be delivered on pallets” to an agreement line with addCommentLine.

POST
.../purchaseAgreementLines([systemId])/Microsoft.NAV.addCommentLine  

Body:
{
    "comment": "This will be delivered on pallets"
}

Response:
    "value": "Comment line 3 added for the purchase line."

Update a comment on a line

Changes the text of comment line 3 with updateCommentLine.

POST
.../purchaseAgreementLines([systemId])/Microsoft.NAV.updateCommentLine  

Body:
{
    "commentLineNo": 3,
    "comment": "This will be delivered on BARCODED pallets"
}

Response:
    "value": "Comment line 3 updated for the purchase line."

Update a comment line that does not exist

The line has no comment line 7. This is not an error: nothing is changed and the response says so.

Request:

POST .../purchaseAgreementLines(b2fece31-c408-f111-b02e-e6f9cc72e785)/Microsoft.NAV.updateCommentLine

Body:
{
    "commentLineNo": 7,
    "comment": "This will be delivered on BARCODED pallets"
}

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Comment line 7 not found for the purchase line."
}