API - Purchase Agreements

Overview

The table behind this API page is the one that contains the purchase agreements in Wisefish, which are mainly used as Receipt Agreements, but the endpoint also contains Blanket Purchase Agreements.

There are 3 endpoints with same properties, but a different fixed filter on Status and can give access to different procedures:

1. Endpoint purchaseAgreements shows both open and posted agreements.

2. Agreements which are open for changes, because the posting document has not been created: openPurchaseAgreements

3. Closed agreements. these are non-editable, because the posting document has been created: closedPurchaseAgreements

The three endpoints do not have exactly the same property list: on openPurchaseAgreements and closedPurchaseAgreements the property status comes after vendorOrderNo, stockCenterCode comes before locationCode, and instead of transportMethodCode they have shipmentMethodCode and shippingReferenceNo. See the Field List below.

The agreement lines are documented on their own page: API - Purchase Agreement Lines

Data

Field List

The tags show which properties can be given in POST and PATCH requests on purchaseAgreements and openPurchaseAgreements. On closedPurchaseAgreements (GET only) all properties are read-only.

Object Example

The response with only the properties from the “Purchase Agreement Header” (not the lines) looks like this:

{
    "systemId": "b443a749-239a-f011-b41a-000d3adf9fc2",
    "documentType": "Receipt",
    "documentNo": "RA2000004",
    "status": "Released",
    "orderDate": "2025-09-25",
    "vendorOrderNo": "",
    "buyFromVendorNo": "4203690429",
    "buyFromVendorName": "Þorbjörn hf.",
    "buyFromVendorName2": "",
    "buyFromAddress": "",
    "buyFromAddress2": "",
    "buyFromPostCode": "240",
    "buyFromCity": "GRINDAVÍK",
    "buyFromCounty": "",
    "buyFromCountry": "IS",
    "languageCode": "ISL",
    "locationCode": "",
    "stockCenterCode": "",
    "externalProducer": "",
    "vesselCode": "1234",
    "vesselName": "Sæfari GK 123",
    "landingDate": "2025-09-25",
    "fishingArea": "HALI",
    "placeofLoading": "",
    "placeofDischarge": "",
    "placeofDelivery": "",
    "transporter": "",
    "transportMethodCode": "",
    "expectedReceiptDate": "2025-09-25",
    "amount": 10000,
    "currencyCode": "",
    "postingDate": "2025-09-25",
    "vendorInvoiceNo": "",
    "getBCTIInvoice": false,
    "noOfLines": 1,
    "noOfTradeItems": 100,
    "noOfTradeItemsAllocated": 0,
    "noOfTradeItemsReceived": 0,
    "systemRowVersion": 2614087,
    "lastModified": "2025-09-30T17:14:22.093Z",
    "modifiedByUser": ""
}

On openPurchaseAgreements and closedPurchaseAgreements the object has the same properties, except that transportMethodCode is replaced by shipmentMethodCode and shippingReferenceNo, and the order of some properties differs (see Overview).

Procedures

In general, if the request is successful, the response is 200 OK and could also possibly contain a message in the value property. For example:

{
    "@odata.context": "https://api.businesscentral.dynamics.com/v2.0/b33a6a3b-244c-4295-84b3-0ad90823c736/AB_Test_191125/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Success"
}

Procedures on purchaseAgreements

Release

This will release the agreement, same as clicking on the Release button within BC.

POST
[server]/api/wisefish/base/v1.0/companies([CompanyGUID])/purchaseAgreements([record-id])/Microsoft.NAV.release

(no parameters)

Possible errors:

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

• <Table Caption> <No.> is already released! (when the Status is already Released). The table caption is “Purchase Agreement Header” in English, e.g. Purchase Agreement Header RA2000004 is already released!

• Errors from the Wisefish release of the agreement, the same checks as when the agreement is released in Business Central.

Behaviour notes:

• The API only checks for the status Released; for any other status the agreement is passed on to the Wisefish release function.

Reopen

The procedure name is reOpen (with a capital O).

If an already released agreement needs to be reopened, in order to do some changes.

POST
[server]/api/wisefish/base/v1.0/companies([CompanyGUID])/purchaseAgreements([record-id])/Microsoft.NAV.reOpen

(no parameters)

Possible errors:

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

• <Table Caption> <No.> is already open! (when the Status is already Open), e.g. Purchase Agreement Header RA2000004 is already open!

• Errors from the Wisefish reopen of the agreement, the same checks as when the agreement is reopened in Business Central.

Create Posting Document

When all lines have been registered on the purchase agreement, the posting document can be created, i.e. either a Purchase Order or a Purchase Invoice.
Before this is run, the agreement must be released.

POST
[server]/api/wisefish/base/v1.0/companies([CompanyGUID])/purchaseAgreements([record-id])/Microsoft.NAV.createPostingDocument

(no parameters)

Possible errors:

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

• The Status is not Released (standard Business Central TestField error, e.g. “Status must be equal to 'Released' in Purchase Agreement Header: Document Type=Receipt, No.=RA2000004. Current value is 'Open'.”).

• Purchase Document Type should be Order or Invoice (when the Posting Document Type of the agreement is Fishing Trip or Repacking).

• Errors from the Wisefish creation of the purchase document.

Behaviour notes:

• The type of the created document follows the Posting Document Type of the agreement: Order creates a Purchase Order, Invoice creates a Purchase Invoice.

• If any line on the agreement has a negative quantity, the document is created with the Wisefish option “and Credit” (Order and Credit / Invoice and Credit).

Receive Items

This method can be used if the API user is allowed to both create the posting document and then immediately post the items into inventory.

POST
[server]/api/wisefish/base/v1.0/companies([CompanyGUID])/purchaseAgreements([record-id])/Microsoft.NAV.receiveItems

(no parameters)

Possible errors:

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

• Purchase Order for agreement <Agreement No.> is missing! (when the agreement already has a posting document, but no Purchase Order, e.g. a Purchase Invoice).

• Purchase Document Type should be Order or Invoice (when no posting document exists and the Posting Document Type is Fishing Trip or Repacking).

• Errors from the Wisefish creation of the purchase document.

• Posting receipt only supports Purchase Orders! (when the created posting document is a Purchase Invoice, i.e. the Posting Document Type is Invoice).

• Standard Business Central posting errors from the receipt posting (Purch.-Post).

Behaviour notes:

• Unlike createPostingDocument, the API code does not check that the agreement is Released before the document is created.

• The order is posted with Receive = true and Invoice = false; the quantities to receive are not synchronised with item tracking first.

Add Note

The procedure AddNote adds a note to the purchase agreement. 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
.../purchaseAgreements([record-id])/Microsoft.NAV.AddNote

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

Possible errors:

• The purchase agreement 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
.../purchaseAgreements([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 purchase agreement 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.

Procedures on openPurchaseAgreements

The endpoint openPurchaseAgreements has the procedures release, reOpen, createPostingDocument and receiveItems. They run exactly the same code as on purchaseAgreements, see Release, Reopen, Create Posting Document and Receive Items above. Only the endpoint in the URL differs:

POST
[server]/api/wisefish/base/v1.0/companies([CompanyGUID])/openPurchaseAgreements([record-id])/Microsoft.NAV.[procedureName]

Because of the fixed filter on Status, the procedures can only be called on agreements with the status Open, Released, Partly Received or Fully Received; other agreements are not found. AddNote and AddNoteFromUser are not available on this endpoint.

Procedures on closedPurchaseAgreements

The endpoint closedPurchaseAgreements is read-only and has no procedures.

Examples

Read purchase agreements

Read all open agreements

Reads the agreements that are still open for changes (Status Open, Released, Partly Received or Fully Received), with only a few properties.

Request:

GET .../openPurchaseAgreements?$select=documentNo,status,buyFromVendorNo,buyFromVendorName,expectedReceiptDate

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#openPurchaseAgreements(documentNo,status,buyFromVendorNo,buyFromVendorName,expectedReceiptDate)",
    "value": [
        {
            "@odata.etag": "W/\"JzIwOzExMTg5ODcyMDAwMzUyNTUzMzI0MTswMDsn\"",
            "documentNo": "RA2000004",
            "status": "Released",
            "buyFromVendorNo": "4203690429",
            "buyFromVendorName": "Þorbjörn hf.",
            "expectedReceiptDate": "2025-09-25"
        },
        {
            "@odata.etag": "W/\"JzIwOzE0NTU2NzI4MzEwNjc0MjM5ODIxOzAwOyc=\"",
            "documentNo": "RA2000003",
            "status": "Open",
            "buyFromVendorNo": "5501692829",
            "buyFromVendorName": "Fiskmarkaður Suðurnesja hf.",
            "expectedReceiptDate": "2025-09-26"
        }
    ]
}

Read released agreements of a vendor

Reads the released agreements of vendor 4203690429 from purchaseAgreements.

GET .../purchaseAgreements?$filter=buyFromVendorNo eq '4203690429' and status eq 'Released'

Read closed agreements posted in a period

Reads the closed agreements with a posting date in September 2025.

GET .../closedPurchaseAgreements?$filter=postingDate ge 2025-09-01 and postingDate le 2025-09-30

Read one agreement with lines

Reading one entry of this table must be done with the record Id which is in this case the systemId.

Lines are shown by adding to the URL $expand=purchaseAgreementLines

GET ... purchaseAgreements([system-id])?$expand=purchaseAgreementLines

GET ... purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)?$expand=purchaseAgreementLines

{
    "@odata.context": "https://api.businesscentral.dynamics.com/v2.0/b33a6a3b-244c-4295-84b3-0ad90823c736/AB_Test_191125/api/wisefish/base/v1.0/$metadata#companies(1691e98a-6a95-f011-b41a-6045bde126e9)/purchaseAgreements/$entity",
    "@odata.etag": "W/\"JzIwOzExMTg5ODcyMDAwMzUyNTUzMzI0MTswMDsn\"",
    "systemId": "b443a749-239a-f011-b41a-000d3adf9fc2",
    "documentType": "Receipt",
    "documentNo": "RA2000004",
    "status": "Released",
    "orderDate": "2025-09-25",
    "vendorOrderNo": "",
    "buyFromVendorNo": "4203690429",
    "buyFromVendorName": "Þorbjörn hf.",
    "buyFromVendorName2": "",
    "buyFromAddress": "",
    "buyFromAddress2": "",
    "buyFromPostCode": "240",
    "buyFromCity": "GRINDAVÍK",
    "buyFromCounty": "",
    "buyFromCountry": "IS",
    "languageCode": "ISL",
    "locationCode": "",
    "stockCenterCode": "",
    "externalProducer": "",
    "vesselCode": "1234",
    "vesselName": "Sæfari GK 123",
    "landingDate": "2025-09-25",
    "fishingArea": "HALI",
    "placeofLoading": "",
    "placeofDischarge": "",
    "placeofDelivery": "",
    "transporter": "",
    "transportMethodCode": "",
    "expectedReceiptDate": "2025-09-25",
    "amount": 10000,
    "currencyCode": "",
    "postingDate": "2025-09-25",
    "vendorInvoiceNo": "",
    "getBCTIInvoice": false,
    "noOfLines": 1,
    "noOfTradeItems": 100,
    "noOfTradeItemsAllocated": 0,
    "noOfTradeItemsReceived": 0,
    "purchaseAgreementLines": [
        {
            "@odata.etag": "W/\"JzIwOzE3MjI2NDI3NTI4MzQ1MzA1NzY2MTswMDsn\"",
            "systemId": "2559e15b-239a-f011-b41a-000d3adf9fc2",
            "documentType": "Receipt",
            "documentNo": "RA2000004",
            "lineNo": 10000,
            "type": "Item",
            "itemNo": "ZZZ1003",
            "description": "Lifur - lánað til Lýsi",
            "noOfTradeItems": 100,
            "tradeItemUnitOfMeasure": "KG",
            "quantity": 100,
            "unitOfMeasure": "KG",
            "quantityBase": 100,
            "baseUnitOfMeasure": "KG",
            "directUnitCost": 100,
            "unitCost": 100,
            "lineAmount": 10000,
            "lineDiscount": 0,
            "lineDiscountAmount": 0,
            "amount": 10000,
            "vat": 11,
            "amountIncludingVAT": 11100,
            "productionDate": "2025-09-25",
            "originalProducer": "",
            "lot": "",
            "netWeight": 100,
            "grossWeight": 0,
            "landingDate": "2025-09-25",
            "portOfLanding": "",
            "addComment": "",
            "systemRowVersion": 2614102,
            "lastModified": "2025-10-02T13:18:31.53Z",
            "modifiedByUser": ""
        }
    ],
    "systemRowVersion": 2614087,
    "lastModified": "2025-09-30T17:14:22.093Z",
    "modifiedByUser": ""
}

Create, change and delete purchase agreements

Create an agreement with lines

POST .../purchaseAgreements?$expand=purchaseAgreementLines

Body:

{
    "orderDate": "2025-12-02",
    "buyFromVendorNo": "4203690429",
    "locationCode": "001",
    "vendorInvoiceNo": "AFH-001",
    "purchaseAgreementLines": [
        {
            "itemNo": "ZZZ1003",
            "noOfTradeItems": 300,
            "tradeItemUnitOfMeasure": "KG",
            "productionDate": "2025-12-02"
        }
    ]
}

The response contains the new entry, both header and lines.

Change an agreement

Sets the vendor invoice no. and the posting date on agreement RA2000004 with PATCH; the If-Match header holds the @odata.etag of the record (the response is shortened).

Request:

PATCH .../openPurchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)
If-Match: W/"JzIwOzExMTg5ODcyMDAwMzUyNTUzMzI0MTswMDsn"

{
    "vendorInvoiceNo": "AFH-001",
    "postingDate": "2025-09-30"
}

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#openPurchaseAgreements/$entity",
    "@odata.etag": "W/\"JzIwOzE2MDQ1NTg4MTkyMDMzNzYxOTA4MTswMDsn\"",
    "systemId": "b443a749-239a-f011-b41a-000d3adf9fc2",
    "documentType": "Receipt",
    "documentNo": "RA2000004",
    ...
    "postingDate": "2025-09-30",
    "vendorInvoiceNo": "AFH-001",
    ...
}

Delete an agreement

Deletes an open agreement; the response is 204 No Content.

DELETE .../openPurchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)
If-Match: *

Status Changes

Release an agreement

Releases agreement RA2000004 with release.

Request:

POST .../purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)/Microsoft.NAV.release

(no parameters)

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Agreement RA2000004 has been released"
}

Release an agreement that is already released

Calling release again on the same agreement fails.

Request:

POST .../purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)/Microsoft.NAV.release

(no parameters)

Response:

{
    "error": {
        "code": "Application_DialogException",
        "message": "Purchase Agreement Header RA2000004 is already released!"
    }
}

Reopen an agreement

Reopens the released agreement RA2000004 with reOpen.

Request:

POST .../purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)/Microsoft.NAV.reOpen

(no parameters)

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Purchase Agreement Header RA2000004 has been re-opened"
}

Posting

Create the posting document for an agreement

Creates the Purchase Order for the released agreement RA2000004 with createPostingDocument.

Request:

POST .../purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)/Microsoft.NAV.createPostingDocument

(no parameters)

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Purchase document Order PO2000123 created for agreement RA2000004."
}

Receive the items of an agreement

Posts the receipt of agreement RA2000004 with receiveItems on the openPurchaseAgreements endpoint; the existing Purchase Order PO2000123 is used.

Request:

POST .../openPurchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)/Microsoft.NAV.receiveItems

(no parameters)

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Receipt of agreement RA2000004: Receipt PR2000045 for Purchase Order PO2000123 posted successfully."
}

Add notes

Add a note to a purchase agreement

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

Request:

POST .../purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)/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 a purchase agreement from a specific user

Adds the same note to agreement RA2000004 with AddNoteFromUser, registered as from user JOHN.

Request:

POST .../purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)/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 .../purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)/Microsoft.NAV.AddNoteFromUser
{
    "noteText": "Quality check completed",
    "fromUser": "NOBODY"
}

Response:

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