> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e-invoice.be/llms.txt
> Use this file to discover all available pages before exploring further.
# Invoice totals and calculations
> Calculate the totals of an invoice in the same way as the API, so that the API accepts the values that you send.
## Overview
Each invoice and credit note has five total fields. You can send them or omit them:
* If you omit a field, the API calculates it from the line items, the document-level allowances and the document-level charges.
* If you send a field, the API compares it with its own calculation and rejects the document if the difference is too large.
This page gives the formulas that the API uses. To add allowances and charges to a document, refer to [Advanced invoicing](/guides/advanced-invoicing).
## Total fields
| Field | Description |
| - | - |
| `subtotal` | The amount without VAT, after document-level allowances and charges |
| `total_discount` | The sum of the document-level allowances |
| `total_tax` | The total VAT amount |
| `invoice_total` | The amount with VAT |
| `amount_due` | The amount that the customer must pay after prepayments |
The API returns these fields as strings (for example `"950.00"`).
## Basic formula
```
line total = sum of (quantity × unit_price - line allowances + line charges)
subtotal = line total - document-level allowances + document-level charges
invoice_total = subtotal + total_tax
amount_due = invoice_total - prepayment
```
The API rounds each line result and each total to 2 decimals (half up).
## Each field in detail
### Subtotal
`subtotal` is the amount of the invoice without VAT.
```
subtotal = line total
- sum of all document-level allowances
+ sum of all document-level charges
```
* The API calculates the line total from `quantity`, `unit_price` and the line-level allowances and charges of each item. It does not use the `amount` of the item for this sum. Send an `amount` that agrees with this calculation.
* All document-level allowances and charges are in the subtotal, also those with a `tax_rate` of `0.00`.
Example:
```
Line items: €1,000.00
Commercial discount: -€100.00
Shipping charge: +€50.00
Subtotal: €950.00
```
### Total tax
`total_tax` is the sum of the VAT of each tax rate.
1. The API adds the line results together for each `tax_rate`.
2. A document-level allowance with a `tax_rate` more than `0.00` decreases the tax base of that rate. A document-level charge with a `tax_rate` more than `0.00` increases it. Allowances and charges with a `tax_rate` of `0.00` do not change a tax base.
3. For each rate: tax = tax base × rate / 100, rounded to 2 decimals.
4. `total_tax` is the sum of these amounts.
Example:
```
Tax base at 21%: €950.00
Total tax: €199.50 (950.00 × 0.21)
```
A document-level allowance or charge has a default `tax_rate` of `21.00`. Send the `tax_rate` and the [tax category code](/glossary#tax-category-code) of the items to which it applies. Items without VAT use a category such as `E`, and an exemption can need a [VATEX](/glossary#vatex) code.
### Total discount
`total_discount` is the sum of all document-level allowances.
```
total_discount = sum of all document-level allowances
```
* These allowances are already subtracted in `subtotal`. Do not subtract `total_discount` again.
* Line-level allowances and document-level charges are not in this field.
Example:
```
Line items: €1,000.00
Early payment discount (21% VAT): -€50.00
Total discount: €50.00
Subtotal: €950.00
Tax (21%): €199.50
Invoice total: €1,149.50
```
### Invoice total
`invoice_total` is the amount of the invoice with VAT, before prepayments.
```
invoice_total = subtotal + total_tax
```
### Amount due
`amount_due` is the amount that the customer must pay. If you omit it, the API sets it to `invoice_total`.
There is no separate field for a prepayment. To state a prepayment, send an `amount_due` that is lower than `invoice_total`. If the difference is more than 0.01, the API writes the difference to the UBL as the prepaid amount.
```
Invoice total: €1,199.50
Amount due: €999.50
Prepaid amount in the UBL: €200.00
```
## Document-level and line-level adjustments
### Document-level allowances and charges
* Change `subtotal`.
* Apply to the full invoice, after the line items are added together.
* Change the tax base of their `tax_rate` (if that rate is more than `0.00`).
* Allowances are added to `total_discount`. Charges are not.
* Examples: early payment discounts, shipping for the full order, handling fees.
### Line-level allowances and charges
* Change the amount of one line item.
* Are not in `total_discount`.
* Examples: bulk discount on one product, special handling for a fragile item.
## Complete example
This fragment shows the parts of a document that the totals are calculated from:
```json theme={null}
{
"items": [
{
"description": "Product A",
"quantity": 10,
"unit": "C62",
"unit_price": 100.00,
"amount": 1000.00,
"tax_rate": "21.00"
}
],
"allowances": [
{
"reason": "Commercial discount",
"amount": 200.00,
"tax_code": "S",
"tax_rate": "21.00"
},
{
"reason": "Early payment discount",
"amount": 50.00,
"tax_code": "S",
"tax_rate": "21.00"
}
],
"charges": [
{
"reason": "Shipping",
"amount": 50.00,
"tax_code": "S",
"tax_rate": "21.00"
}
]
}
```
Calculation:
1. Line total: €1,000.00
2. Document-level allowances: -€200.00 and -€50.00
3. Document-level charge: +€50.00
4. `subtotal`: €800.00
5. `total_tax`: €800.00 × 21% = €168.00
6. `total_discount`: €250.00 (allowances only)
7. `invoice_total`: €800.00 + €168.00 = €968.00
8. `amount_due`: €968.00 (no prepayment)
The totals that you can send with this document:
```json theme={null}
{
"subtotal": 800.00,
"total_discount": 250.00,
"total_tax": 168.00,
"invoice_total": 968.00,
"amount_due": 968.00
}
```
## UBL mapping
| API field | UBL element |
| - | - |
| `subtotal` | `cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount` |
| `total_tax` | `cac:TaxTotal/cbc:TaxAmount` |
| `total_discount` | `cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount` |
| `invoice_total` | `cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount` |
| `amount_due` | `cac:LegalMonetaryTotal/cbc:PayableAmount` |
The API also writes `LineExtensionAmount` (the sum of the line amounts), `ChargeTotalAmount` (the sum of the document-level charges) and, for a prepayment, `PrepaidAmount`. These elements have no API field.
## Validation rules
`POST /api/documents/` and `POST /api/validate/json` do these checks on the totals:
1. `subtotal`, `total_tax`, `total_discount` and `invoice_total`: each value that you send must agree with the value that the API calculates. The API permits a maximum difference of 1.00.
2. `amount_due` must not be more than the calculated `invoice_total` plus 1.00.
If a check fails, the API returns `406` and names the field, the value that you sent and the calculated value (for example `Subtotal mismatch: provided 900.00, calculated 800.00`). Refer to [Errors and troubleshooting](/guides/errors) for the error format.
After these checks, the generated UBL must also pass the Peppol BIS Billing 3.0 rules. Refer to [Validation during development](/guides/validation).
## Frequently asked questions
A document-level allowance applies to the full invoice and is in `total_discount`. A line-level allowance applies to one line item, decreases the amount of that line, and is not in `total_discount`.
The totals check of the API has no minimum value for `subtotal`, `total_tax`, `total_discount`, `invoice_total` or `amount_due`. It only compares each value with the calculated value. Thus `invoice_total` is negative when the document-level allowances are larger than the line total plus the charges, or when the lines have negative quantities.
To refund or correct an invoice, send a [credit note](/guides/credit-notes) with positive amounts, not an invoice with a negative total.
The API calculates each of `subtotal`, `total_tax`, `total_discount` and `invoice_total` that you omit, and sets `amount_due` to `invoice_total`. The response of the create call contains the calculated values.
A document-level charge (for example a shipping fee) increases `subtotal`. If its `tax_rate` is more than `0.00`, it also increases the tax base of that rate. It is not in `total_discount`.
## Next Steps
Add allowances and charges at document level and line level
Examine a document before you create it
Read the error formats and the frequent rule failures
See all fields of a document
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.