Document summary / detail totals and roundings

Required versions: API 1.2.9+, Environment 763+

Overview

Document summary and line totals are automatically calculated based on the specified document type rules.

In the most basic example, a purchase invoice is created from the provided detail lines:

POST /api/purchaseInvoice

{
  "docTypeId": "PIN",
  "contactAccountId": "API1",
  "details": [
    {
      "productId": "WIDGETG",
      "quantity": 5,
      "currencyUnitPrice": 20.00
    }
  ]
}

The line totals and document totals are automatically calculated based on the tax setup:

GET /api/purchaseInvoice/xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

{
  "id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "docNo": "PIN0000052",
  "netAmount": 100.00000,
  "taxAmount": 20.00000,
  "grossAmount": 120.00000,
  "currency": "GBP",
  "netCurrencyAmount": 100.00000,
  "taxCurrencyAmount": 20.00000,
  "grossCurrencyAmount": 120.00000,
  ...
  "details": [
    {
      "id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "description": "Widget",
      "taxRate": 20.00000,
      "netCurrencyUnitPrice": 20.00000,
      "grossCurrencyUnitPrice": 24.00000,
      "quantity": 5.00000,
      "netAmount": 100.00000,
      "grossAmount": 120.00000,
      "taxAmount": 20.00000,
      "netCurrencyAmount": 100.00000,
      "taxCurrencyAmount": 20.00000,
      "grossCurrencyAmount": 120.00000,
      ...
    }
  ]
}

Calculating totals

Iplicit calculates document totals from detail lines.

When document is net entry enabled:

  • Line currency amounts are calculated:

    • net is calculated from unit price and quantity; result is rounded to currency precision.
    • tax amount is calculated from currency rate; result is rounded to currency precision
    • gross amount is calculated; result is rounded to currency precision

  • Line base amounts are calculated from the currency rate and currency amounts at previous steps; results are rounded to currency precision

  • Document totals are aggregated from all detail lines; results are rounded to currency precision

For gross entry, similar steps are performed, but determining gross first, then net amounts.

Providing calculated values

To overcome rounding issues between various systems, starting from API v1.2.9+ / Environment 763+, any of the netCurrencyAmount/taxCurrencyAmount/grossCurrencyAmount/netAmount/taxAmount/grossAmount can be provided on header and/or detail lines.

POST /api/purchaseInvoice

{
  "docTypeId": "PIN",
  "contactAccountId": "API1",
  "details": [
    {
      "productId": "WIDGETG",
      "quantity": 3,
      "currencyUnitPrice": 3.33,
      "netCurrencyAmount": 10.00,
      "taxCurrencyAmount": 2.00,
      "grossCurrencyAmount": 12.00
    }
  ],
  "netCurrencyAmount": 10.00,
  "taxCurrencyAmount": 2.00,
  "grossCurrencyAmount": 12.00
}

Rounding tolerance

In the above example, without providing the total amounts, Iplicit would have calculated a total net of 9.99.

When totals are provided, the API will allow for rounding differences of 0.01.

When the provided values are outside of the 0.01 tolerance, the request will be rejected with a 400 status code, for example: { "message": "Provided tax currency amount is invalid (provided=2.50, calculated=2.00)" }

Explicit amounts entry

From API v1.4.0, when the ExplicitAmounts flag is enabled, it is possible to provide all header and detail line amounts when creating a document and bypass the iplicit calculations and rounding tolerance checks. This allows for different calculation methods in other systems.

When ExplicitAmounts is true then all Amount fields must be specified. If any amounts are missing, the request will be rejected with a 400 status code, for example:

{ "message": "Missing required line #1 GrossAmount" }

Front end support

Trying to edit a document with rounding adjustments or explicit amount entry in the front end is not supported and will present a dialog box:

rounding alert