Overview
The estimated additional costs of sales agreements (Delivery and Blanket), for example freight, insurance, pallets or interest. These are the costs registered on the agreement in Business Central (page Sales Agreement Estimated Additional Cost). The costs are estimated when the agreement is made, so that the contribution margin of the agreement can be calculated before the actual costs are known.
|
Endpoint name |
|
|
Source table |
|
|
Fixed view |
Document Type = Blanket or Delivery, and Document Line No. = 0 (only the costs registered on the agreement, not the costs distributed to the agreement lines). |
|
Requests allowed |
GET, POST, PATCH, DELETE |
|
Primary key |
“Document Type”, “Document No.”, “Document Line No.”, “Line No.” |
|
Record ID |
|
|
Procedures |
|
Cost calculation methods
The API uses a few generic properties for all calculation methods: costCalculationMethod, costUnit, rate, quantity and basis. In Business Central each method has its own fields (e.g. Unit Cost per Pallet, No. of Pallets); the endpoint maps the generic properties to those fields, and Business Central does the calculation.
|
costCalculationMethod |
costUnit |
rate |
quantity |
basis |
costAmount |
|---|---|---|---|---|---|
|
|
|
Unit cost |
Entered (default 1) |
|
|
|
|
|
Percent |
Agreement amount (calculated) |
|
|
|
|
|
Cost per BWU |
Agreement net or gross weight in BWU (calculated) |
|
|
|
|
|
Cost per pallet |
No. of pallets (entered) |
|
|
|
|
|
Cost per container |
No. of containers (entered) |
|
|
|
|
|
Annual interest % |
Agreement amount (calculated) |
|
|
In Business Central the method PerUnit is three methods: BWU (Base Weight Unit), Unit Cost per Pallet and Unit Cost per Container. BWU is the base weight unit set up in Wisefish (kg or lb).
Creating, changing and deleting costs
-
The same validation applies as when the cost is registered in Business Central. A new cost needs at least
documentNoanditemChargeNo; the item charge gives the default method and basis. -
Only the properties given in the request are changed. They are applied in this order:
costCalculationMethodandcostUnit,basis,rate,quantity,noOfDaysCalcMethodandnoOfDays,costAmount. -
Changing
costCalculationMethod(orcostUnit) clears the rate and quantity of the previous method, as in Business Central. Give the newrate(andquantity) in the same request. -
A new or changed cost is not distributed to the agreement lines until
updateEstimatedCostsis called (the same as action Update Estimated Costs in Business Central). -
A cost that has an accrue document (posted item charge cost distribution) cannot be deleted with the API, because Business Central asks the user for confirmation. Delete it in Business Central.
Possible errors from the endpoint (checked in this order). Methods and basis values are shown with their captions in the messages (e.g. Per Unit, Gross Weight):
-
costUnit must be given when costCalculationMethod is Per Unit. -
costUnit is only used when costCalculationMethod is PerUnit. -
basis %1 cannot be used with costCalculationMethod %2. -
quantity is calculated for costCalculationMethod %1 and cannot be set. -
noOfDays is only used when costCalculationMethod is AnnualInterest.(ornoOfDaysCalcMethod is only used…) -
costAmount can only be set when costCalculationMethod is FixedCost. -
Errors from the validation in Business Central and Wisefish (e.g. the agreement or item charge does not exist).
The agreements are available with the salesAgreements endpoint, see API - Sales Agreements, and the agreement lines with salesAgreementLines, see API - Sales Agreement Lines.
Data
Field List
|
Property |
Type |
Format |
Description |
|
|
|
string |
uuid |
SystemId |
Record ID non-editable |
|
|
string |
enum |
Document Type: |
primary key optional |
|
|
string |
max 20 |
Document No., the sales agreement the cost belongs to. The agreement must exist. |
primary key mandatory |
|
|
integer |
|
Line No. If not given (or 0), the next free number is used (last line + 10000). |
primary key optional |
|
|
string |
max 20 |
Item Charge No., the type of cost (e.g. freight, insurance). Must be an item charge with Estimated Cost Type Sales or Both. Sets the default |
mandatory |
|
|
string |
max 100 |
Item Charge Description. Copied from the item charge; can be overwritten. |
optional |
|
|
string |
max 20 |
Vendor No., the vendor of the cost. Needed to realize the cost in a purchase document. |
optional |
|
|
string |
enum |
How the cost is calculated: |
recommended |
|
|
string |
enum |
The unit the |
optional |
|
|
string |
enum |
|
optional |
|
|
number |
decimal |
The rate: the unit cost ( |
recommended |
|
|
number |
decimal |
The quantity the rate is applied to. Entered for |
optional |
|
|
string |
enum |
Only for |
optional |
|
|
number |
decimal |
Only for |
optional |
|
|
number |
decimal |
Cost Amount, in the currency of |
optional |
|
|
string |
max 10 |
Currency Code of the cost. Default: the currency of the agreement. Blank = local currency (LCY). |
optional |
|
|
number |
decimal |
Cost Amount (LCY), the cost amount in local currency. |
non-editable |
|
|
number |
decimal |
Cost Amount (Agr. CY), the cost amount in the agreement’s currency. |
non-editable |
|
|
number |
decimal |
Unit Cost (LCY) per BWU: |
non-editable |
|
|
string |
enum |
Realization Status: |
optional |
|
|
string |
max 20 |
Document No. (Realized), the posted purchase invoice or credit memo of |
optional |
|
|
integer |
|
System row version. Increments every time the record is modified. |
non-editable |
|
|
string |
date-time |
SystemModifiedAt (date and time of last change) |
non-editable |
|
|
string |
|
User name of the user who made the last change (SystemModifiedBy). |
non-editable |
Object Example
An example of one object, a pallet cost of 25 EUR per pallet for 18 pallets:
{
"systemId": "a41c7e05-9b5f-f011-b02a-8bca792786d1",
"documentType": "Delivery",
"documentNo": "DS-034",
"lineNo": 20000,
"itemChargeNo": "PALLETS",
"itemChargeDescription": "Pallet handling",
"vendorNo": "44127914",
"costCalculationMethod": "PerUnit",
"costUnit": "Pallet",
"basis": "NetWeight",
"rate": 25,
"quantity": 18,
"noOfDaysCalcMethod": " ",
"noOfDays": 0,
"costAmount": 450,
"currencyCode": "EUR",
"costAmountLCY": 65250,
"unitCostLCYPerBWU": 5.4375,
"realizationStatus": "Unrealized",
"documentNoRealized": "",
"systemRowVersion": 2601144,
"lastModified": "2026-11-12T14:20:31.207Z",
"modifiedByUser": "BJARTEY"
}
Procedures
The procedure is called on a specific cost: POST salesAgreementCosts(<systemId>)/Microsoft.NAV.<procedureName>. It returns a text message in the value property of the response on success. On failure it returns an error with a readable message.
|
Procedure |
Parameters |
Description |
Details |
|---|---|---|---|
|
|
None |
Recalculate the estimated costs of the whole agreement and distribute them to the agreement lines. |
Update Estimated Costs
Does the same as action Update Estimated Costs on the estimated additional costs in Business Central. All costs of the agreement that the cost belongs to are recalculated from the current agreement values (amount, weight, currency) and distributed to the agreement lines. The procedure can be called on any cost of the agreement; the result is the same.
POST
[server]/api/wisefish/base/v1.0/companies([CompanyGUID])
/salesAgreementCosts([record-id])/Microsoft.NAV.updateEstimatedCosts
The costs are recalculated and distributed, and the value property of the response is Estimated additional costs updated for sales agreement %1. (%1 = the agreement no.).
Possible errors:
-
The cost or the agreement does not exist (standard Business Central error, record not found).
-
Errors from the recalculation in Wisefish (e.g. missing exchange rate).
Examples
Read costs
Read the costs of an agreement
Reads all estimated additional costs of agreement DS-034 with $filter. The response is a list of cost objects, as shown in Object Example.
GET .../salesAgreementCosts?$filter=documentNo eq 'DS-034'
Read the costs in local currency
Reads only the item charge and the cost in local currency, for agreement DS-034.
Request:
GET .../salesAgreementCosts?$filter=documentNo eq 'DS-034'&$select=itemChargeNo,costAmountLCY,unitCostLCYPerBWU
Response:
{
"@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/salesAgreementCosts(itemChargeNo,costAmountLCY,unitCostLCYPerBWU)",
"value": [
{
"@odata.etag": "W/\"JzE5OzEyMzQ1Njc4OTAxMjM0NTY3ODk7MDA7Jw==\"",
"itemChargeNo": "FREIGHT",
"costAmountLCY": 217500,
"unitCostLCYPerBWU": 18.125
},
{
"@odata.etag": "W/\"JzE5Ojk4NzY1NDMyMTA5ODc2NTQzMjE7MDA7Jw==\"",
"itemChargeNo": "PALLETS",
"costAmountLCY": 65250,
"unitCostLCYPerBWU": 5.4375
}
]
}
Create costs
Insert a fixed cost
Adds a freight cost of 1,500 EUR to agreement DS-034. Only the amount is given, so quantity is set to 1 and rate to 1,500.
Request:
POST .../salesAgreementCosts
Body:
{
"documentNo": "DS-034",
"itemChargeNo": "FREIGHT",
"costCalculationMethod": "FixedCost",
"costAmount": 1500,
"currencyCode": "EUR"
}
Response (shortened):
{
"systemId": "5e2b8d17-9b5f-f011-b02a-8bca792786d1",
"documentType": "Delivery",
"documentNo": "DS-034",
"lineNo": 10000,
"itemChargeNo": "FREIGHT",
"itemChargeDescription": "Freight",
"costCalculationMethod": "FixedCost",
"costUnit": "None",
"basis": "Value",
"rate": 1500,
"quantity": 1,
"costAmount": 1500,
"currencyCode": "EUR",
"costAmountLCY": 217500,
"unitCostLCYPerBWU": 18.125
}
Insert a percent of value cost
Adds an insurance cost of 0.5% of the agreement amount. The quantity is the agreement amount (48,000 EUR) and is calculated.
POST .../salesAgreementCosts
Body:
{
"documentNo": "DS-034",
"itemChargeNo": "INSURANCE",
"costCalculationMethod": "PercentOfValue",
"rate": 0.5
}
Response (shortened):
{
"costCalculationMethod": "PercentOfValue",
"basis": "Value",
"rate": 0.5,
"quantity": 48000,
"costAmount": 240,
"currencyCode": "EUR"
}
Insert a cost per pallet
Adds a pallet cost of 25 EUR per pallet for 18 pallets (the object in Object Example).
POST .../salesAgreementCosts
Body:
{
"documentNo": "DS-034",
"itemChargeNo": "PALLETS",
"costCalculationMethod": "PerUnit",
"costUnit": "Pallet",
"rate": 25,
"quantity": 18
}
Insert a cost per base weight unit
Adds a cost of 0.12 EUR per kg (BWU) of the gross weight of the agreement. The quantity is the gross weight of the agreement and is calculated.
POST .../salesAgreementCosts
Body:
{
"documentNo": "DS-034",
"itemChargeNo": "STORAGE",
"costCalculationMethod": "PerUnit",
"costUnit": "BWU",
"basis": "GrossWeight",
"rate": 0.12
}
Insert an annual interest cost
Adds an interest cost of 6% a year, for the number of days from the posting date to the due date of the agreement (from its payment terms).
POST .../salesAgreementCosts
Body:
{
"documentNo": "DS-034",
"itemChargeNo": "INTEREST",
"costCalculationMethod": "AnnualInterest",
"rate": 6,
"noOfDaysCalcMethod": "DueDateCalcByPaymTerms"
}
Change and delete costs
Change the rate
Changes the pallet cost to 27 EUR per pallet. A PATCH request needs the If-Match header with the @odata.etag of the record (or *).
PATCH .../salesAgreementCosts(a41c7e05-9b5f-f011-b02a-8bca792786d1)
If-Match: *
Body:
{
"rate": 27
}
Change from pallets to a container
Changes the pallet cost to one container at 1,200 EUR. costCalculationMethod is still PerUnit, so only costUnit, rate and quantity are given.
PATCH .../salesAgreementCosts(a41c7e05-9b5f-f011-b02a-8bca792786d1)
If-Match: *
Body:
{
"costUnit": "Container",
"rate": 1200,
"quantity": 1
}
Distribute the costs to the agreement lines
After the costs have been changed, they are distributed to the agreement lines by calling updateEstimatedCosts on one of the costs.
Request:
POST .../salesAgreementCosts(a41c7e05-9b5f-f011-b02a-8bca792786d1)/Microsoft.NAV.updateEstimatedCosts
Response:
{
"@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
"value": "Estimated additional costs updated for sales agreement DS-034."
}
Delete a cost
Deletes the cost. On success the response is empty (HTTP status 204 No Content).
DELETE .../salesAgreementCosts(a41c7e05-9b5f-f011-b02a-8bca792786d1)