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 |
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
- 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.
total_discount = non-VAT charges - non-VAT allowances
- 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:
- A discount with VAT is applied to reduce the taxable base
- 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
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:
{
"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"
}
]
}
- Line items total: €1,000.00
- Apply VAT allowances:
- Commercial discount: -€200.00
- Early payment discount: -€50.00
- Subtotal (taxable base): €750.00
- Calculate tax: €750.00 × 21% = €157.50
- Apply non-VAT adjustments:
- Early payment charge (0% VAT): +€50.00
- Total discount: €50.00
- Invoice total: €750.00 + €157.50 + €50.00 = €957.50
- 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:
- Subtotal must match the calculated taxable base (within €0.01 tolerance)
- Total tax must match the calculated VAT amount (within €0.01 tolerance)
- Total discount must match the net non-VAT adjustments (within €0.01 tolerance)
- Invoice total must equal
subtotal + total_tax + total_discount (within €0.01 tolerance)
- 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
