This section focuses on understanding the methodology used to calculate totals on documents. Familiarizing yourself with this approach is helpful when setting up front-end calculations to ensure consistency with the values on the final created documents.
Decimal places
In the initial stage, we truncate any numbers that exceed the limit set on the document itself in the decimalPlaces property, with the default being 9 decimal places. No rounding is performed.
This applies to values such as price, priceGross, quantity, and discount (if amount-based).
Any percentge or tax values are always truncated to 2 decimal places. This includes properties like discount (if percent-based) and taxRate.
The document decimalPlaces can be increased by passing the property or by setting a Default.
Rounding
After each mathematical operation, we round the result to 2 digits using the half-up rounding strategy. For example, after calculating the product of quantity and price, we round the result and then use the rounded value in the subsequent operation.
Rounding offset correction
In situations where invoice data is sent from another system with calculations performed beforehand, resulting in slightly different values, you can use the equalization property to rectify minor discrepancies. This property accepts a number, such as 0.01, and the API will utilize this value to adjust the final total of the invoice, correcting for the offset.
For instance, if the expected total is 99.99, but the API calculations return 99.98, you can apply a 0.01 equalization to reconcile the difference.
Forcing an API error on an unexpected calculation result
To ensure that the final total value of an invoice matches the expected total from the submitted data, you can add the expectedTotalWithTax property to the invoice request body. If the calculated result deviates from the expected value, the API will return an error.
This safeguard is particularly beneficial when ensuring a calculated final total, such as when issuing invoices for payments of fixed values, or generating invoices for orders originating from a user-facing checkout form. It guarantees that the expected total aligns with the actual total, maintaining accuracy and consistency in your invoicing process.