> ## 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
> Understanding how invoice totals are calculated and what each field represents
## Overview
The e-invoice.be API calculates invoice totals based on line items, allowances, charges, and tax rates. This guide explains the calculation logic and what each total field represents.
## Total Fields
| Field | Description | Can be negative? |
| ------------------------- | -------------------------------------------- | ---------------- |
| `subtotal` | The taxable base (amount subject to VAT) | No |
| `total_discount` | Net financial adjustments not subject to VAT | Yes |
| `total_tax` | The total VAT/tax amount | No |
| `invoice_total` | The final invoice amount before prepayments | No (usually) |
| `amount_due` | The amount the customer needs to pay | No |
| `previous_unpaid_balance` | Outstanding balance from previous invoices | No |
## Calculation Formula
The basic formula for invoice calculations:
```
invoice_total = subtotal + total_tax + total_discount
amount_due = invoice_total - prepaid_amount
```
## Understanding Each Field
### Subtotal (Taxable Base)
The **subtotal** represents the taxable base - the amount on which VAT is calculated.
**Calculation:**
```
subtotal = sum of line items
- document-level allowances with VAT
+ document-level charges with VAT
```
**Key points:**
* Always positive
* Only includes allowances and charges that have VAT applied
* This is the base amount used for tax calculation
**Example:**
```
Line items: €1,000.00
Commercial discount (21% VAT): -€100.00
Shipping charge (21% VAT): +€50.00
→ Subtotal: €950.00
```
### Total Tax
The **total\_tax** is the total amount of VAT calculated on the subtotal.
**Calculation:**
* VAT is calculated on the subtotal for each applicable tax rate
* Multiple tax rates are grouped and calculated separately
* Results are summed to get the total tax
**Example:**
```
Subtotal at 21% VAT: €950.00
→ Total tax: €199.50 (950.00 × 0.21)
```
### Total Discount (Financial Adjustments)
The **total\_discount** field represents net financial adjustments that are **not subject to VAT**.
Despite its name, this field can represent both discounts AND charges. It is the net of non-VAT charges minus non-VAT allowances.
**Calculation:**
```
total_discount = non-VAT charges - non-VAT allowances
```
**This field can be:**
* **Positive**: When non-VAT charges exceed non-VAT allowances (adds to invoice total)
* **Negative**: When non-VAT allowances exceed non-VAT charges (reduces invoice total)
* **Zero**: When they balance out or don't exist
**Common use case - Early Payment Discount Pattern:**
Many invoices use a pattern where:
1. A discount with VAT is applied to reduce the taxable base
2. The same amount is added back as a charge without VAT
This allows customers to benefit from reduced VAT while maintaining standard payment terms.
**Example:**
```
Line items: €1,000.00
Early payment discount (21% VAT): -€50.00 (reduces tax base)
Early payment charge (0% VAT): +€50.00 (added after tax)
→ Subtotal: €950.00
→ Tax (21%): €199.50
→ Total discount: €50.00 (charge without VAT)
→ Invoice total: €1,199.50
Customer saves: €10.50 in VAT (€50.00 × 0.21)
```
### Invoice Total
The **invoice\_total** is the final amount of the invoice before prepayments.
**Calculation:**
```
invoice_total = subtotal + total_tax + total_discount
```
### Amount Due
The **amount\_due** is what the customer actually needs to pay.
**Calculation:**
```
amount_due = invoice_total - prepaid_amount
```
**Example with prepayment:**
```
Invoice total: €1,199.50
Prepaid amount: €200.00
→ Amount due: €999.50
```
### Previous Unpaid Balance
The **previous\_unpaid\_balance** represents any outstanding amounts from previous invoices. This is a custom field not part of standard UBL.
## VAT vs Non-VAT Allowances and Charges
Understanding the difference between VAT and non-VAT adjustments is critical for correct invoice calculations.
### Allowances/Charges with VAT (tax\_rate > 0)
* **Affect the subtotal** (taxable base)
* VAT is calculated on the adjusted amount
* Examples: Commercial discounts, volume discounts, shipping charges
### Allowances/Charges without VAT (tax\_rate = 0 or exempt)
* **Do NOT affect the subtotal**
* Applied AFTER tax calculation
* Affect the `total_discount` field
* Examples: Financial charges, administrative fees without VAT
Use VAT allowances for commercial discounts that should reduce both the base amount and VAT. Use non-VAT allowances for financial discounts that should not affect VAT calculation.
## Complete Example
Here's a complete invoice with both VAT and non-VAT adjustments:
```json theme={null}
{
"items": [
{
"description": "Product A",
"quantity": 10,
"unit_price": 100.00,
"amount": 1000.00,
"tax_rate": "21.00"
}
],
"allowances": [
{
"reason": "Commercial discount",
"amount": 200.00,
"tax_rate": "21.00"
},
{
"reason": "Early payment discount",
"amount": 50.00,
"tax_rate": "21.00"
}
],
"charges": [
{
"reason": "Early payment terms",
"amount": 50.00,
"tax_rate": "0.00"
}
]
}
```
**Calculation breakdown:**
1. **Line items total:** €1,000.00
2. **Apply VAT allowances:**
* Commercial discount: -€200.00
* Early payment discount: -€50.00
3. **Subtotal (taxable base):** €750.00
4. **Calculate tax:** €750.00 × 21% = €157.50
5. **Apply non-VAT adjustments:**
* Early payment charge (0% VAT): +€50.00
6. **Total discount:** €50.00
7. **Invoice total:** €750.00 + €157.50 + €50.00 = **€957.50**
8. **Amount due:** €957.50 (no prepayment)
## UBL Mapping
For reference, here's how the API fields map to UBL (Universal Business Language) elements:
| API Field | UBL Element |
| ---------------- | ---------------------------------------------------------------- |
| `subtotal` | TaxExclusiveAmount |
| `total_tax` | TaxAmount |
| `invoice_total` | TaxInclusiveAmount / PayableAmount |
| `amount_due` | PayableAmount (after prepayments) |
| `total_discount` | Calculated from ChargeTotal - AllowanceTotal (for non-VAT items) |
In UBL, `AllowanceTotalAmount` and `ChargeTotalAmount` include ALL allowances and charges (both VAT and non-VAT), whereas the API's `total_discount` only includes non-VAT adjustments.
## Validation Rules
When creating or updating invoices, the following validations are applied:
1. **Subtotal** must match the calculated taxable base (within €0.01 tolerance)
2. **Total tax** must match the calculated VAT amount (within €0.01 tolerance)
3. **Total discount** must match the net non-VAT adjustments (within €0.01 tolerance)
4. **Invoice total** must equal `subtotal + total_tax + total_discount` (within €0.01 tolerance)
5. **Amount due** must be between 0 and invoice\_total (inclusive)
## Common Questions
### Why can total\_discount be positive?
The field is named `total_discount` for historical reasons, but it actually represents the **net** of non-VAT charges minus non-VAT allowances. When non-VAT charges exceed non-VAT allowances, the value is positive and increases the invoice total.
### When should I use VAT vs non-VAT allowances?
* Use **VAT allowances** (tax\_rate > 0) for commercial discounts, volume discounts, etc. that should reduce both the base amount and VAT
* Use **non-VAT allowances** (tax\_rate = 0) for financial discounts or adjustments that should not affect VAT calculation
### Can invoice\_total be negative?
While theoretically possible with large negative adjustments, this is unusual. Most invoices should have a positive invoice total.
### What if I don't provide these fields?
If you don't provide `subtotal`, `total_tax`, `total_discount`, or `invoice_total`, the system will automatically calculate them based on your line items, allowances, and charges. The calculated values will be validated if you do provide them.
## Next Steps
Learn the basics of invoice creation
Work with allowances and charges
Test invoices during development
Explore all endpoints