API - Sales Agreement Costs


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

salesAgreementCosts

Source table

WiFi Sales Agr Add. Estim Cost

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

systemId

Procedures

updateEstimatedCosts

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

FixedCost

None

Unit cost

Entered (default 1)

Value or NetWeight (distribution)

rate × quantity, or entered

PercentOfValue

None

Percent

Agreement amount (calculated)

Value

rate / 100 × quantity

PerUnit

BWU

Cost per BWU

Agreement net or gross weight in BWU (calculated)

NetWeight or GrossWeight

rate × quantity

PerUnit

Pallet

Cost per pallet

No. of pallets (entered)

Value or NetWeight (distribution)

rate × quantity

PerUnit

Container

Cost per container

No. of containers (entered)

Value or NetWeight (distribution)

rate × quantity

AnnualInterest

None

Annual interest %

Agreement amount (calculated)

Value

rate / 100 × noOfDays / 365 × quantity

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 documentNo and itemChargeNo; the item charge gives the default method and basis.

  • Only the properties given in the request are changed. They are applied in this order: costCalculationMethod and costUnit, basis, rate, quantity, noOfDaysCalcMethod and noOfDays, costAmount.

  • Changing costCalculationMethod (or costUnit) clears the rate and quantity of the previous method, as in Business Central. Give the new rate (and quantity) in the same request.

  • A new or changed cost is not distributed to the agreement lines until updateEstimatedCosts is 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. (or noOfDaysCalcMethod 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


systemId

string

uuid

SystemId

Record ID

non-editable

documentType

string

enum

Document Type: Blanket or Delivery. Default Delivery.

primary key

optional

documentNo

string

max 20

Document No., the sales agreement the cost belongs to. The agreement must exist.

primary key

mandatory

lineNo

integer


Line No. If not given (or 0), the next free number is used (last line + 10000).

primary key

optional

itemChargeNo

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 costCalculationMethod, basis and description from the item charge.

mandatory

itemChargeDescription

string

max 100

Item Charge Description. Copied from the item charge; can be overwritten.

optional

vendorNo

string

max 20

Vendor No., the vendor of the cost. Needed to realize the cost in a purchase document.

optional

costCalculationMethod

string

enum

How the cost is calculated: FixedCost, PercentOfValue, PerUnit or AnnualInterest. Default from the item charge. See Cost calculation methods.

recommended

costUnit

string

enum

The unit the rate is given per, when costCalculationMethod is PerUnit: BWU (base weight unit), Pallet or Container. None for the other methods. Mandatory with PerUnit.

optional

basis

string

enum

Value, NetWeight or GrossWeight (None = not set). For PerUnit with BWU: which agreement weight is the quantity. For FixedCost, Pallet and Container: how the cost is distributed to the agreement lines (by value or by net weight). Always Value for PercentOfValue and AnnualInterest. Default from the item charge.

optional

rate

number

decimal

The rate: the unit cost (FixedCost), the percent (PercentOfValue, e.g. 0.5 = 0.5%), the cost per unit (PerUnit) or the annual interest % (AnnualInterest). In the currency of currencyCode.

recommended

quantity

number

decimal

The quantity the rate is applied to. Entered for FixedCost (default 1) and for PerUnit with Pallet or Container (no. of pallets/containers). Calculated for the other methods: the agreement amount (PercentOfValue, AnnualInterest) or the agreement net/gross weight (BWU).

optional

noOfDaysCalcMethod

string

enum

Only for AnnualInterest. DueDateCalcByPaymTerms: noOfDays is calculated from the payment terms of the agreement (due date − posting date). Blank: noOfDays is entered.

optional

noOfDays

number

decimal

Only for AnnualInterest. Number of days the interest is calculated for.

optional

costAmount

number

decimal

Cost Amount, in the currency of currencyCode. Calculated from rate and quantity. Can only be entered for FixedCost; then rate is set to costAmount / quantity.

optional

currencyCode

string

max 10

Currency Code of the cost. Default: the currency of the agreement. Blank = local currency (LCY). PercentOfValue and AnnualInterest always use the currency of the agreement.

optional

costAmountLCY

number

decimal

Cost Amount (LCY), the cost amount in local currency.

non-editable

costAmountAgreementCY

number

decimal

Cost Amount (Agr. CY), the cost amount in the agreement’s currency.

non-editable

unitCostLCYPerBWU

number

decimal

Unit Cost (LCY) per BWU: costAmountLCY divided by the net weight (BWU) of the agreement.

non-editable

realizationStatus

string

enum

Realization Status: Unrealized, Realized or WithoutSettlement (Unrealized Cost, Realized Cost, Without Settlement). Can only be changed when vendorNo is filled.

optional

documentNoRealized

string

max 20

Document No. (Realized), the posted purchase invoice or credit memo of vendorNo where the cost was realized. Must exist in the vendor's ledger entries; sets realizationStatus to Realized.

optional

systemRowVersion

integer


System row version. Increments every time the record is modified.

non-editable

lastModified

string

date-time

SystemModifiedAt (date and time of last change)

non-editable

modifiedByUser

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:

JSON
{
    "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

updateEstimatedCosts

None

Recalculate the estimated costs of the whole agreement and distribute them to the agreement lines.

Show more

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.

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

JSON
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:

JSON
GET .../salesAgreementCosts?$filter=documentNo eq 'DS-034'&$select=itemChargeNo,costAmountLCY,unitCostLCYPerBWU

Response:

JSON
{
    "@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:

JSON
POST .../salesAgreementCosts

Body:
{
    "documentNo": "DS-034",
    "itemChargeNo": "FREIGHT",
    "costCalculationMethod": "FixedCost",
    "costAmount": 1500,
    "currencyCode": "EUR"
}

Response (shortened):

JSON
{
    "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.

JSON
POST .../salesAgreementCosts

Body:
{
    "documentNo": "DS-034",
    "itemChargeNo": "INSURANCE",
    "costCalculationMethod": "PercentOfValue",
    "rate": 0.5
}

Response (shortened):

JSON
{
    "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).

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

JSON
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).

JSON
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 *).

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

JSON
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:

JSON
POST .../salesAgreementCosts(a41c7e05-9b5f-f011-b02a-8bca792786d1)/Microsoft.NAV.updateEstimatedCosts

Response:

JSON
{
    "@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).

JSON
DELETE .../salesAgreementCosts(a41c7e05-9b5f-f011-b02a-8bca792786d1)