Skip to main content

​
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

FieldDescriptionCan be negative?
subtotalThe taxable base (amount subject to VAT)No
total_discountNet financial adjustments not subject to VATYes
total_taxThe total VAT/tax amountNo
invoice_totalThe final invoice amount before prepaymentsNo (usually)
amount_dueThe amount the customer needs to payNo
previous_unpaid_balanceOutstanding balance from previous invoicesNo

​
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: 
{
  "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 FieldUBL Element
subtotalTaxExclusiveAmount
total_taxTaxAmount
invoice_totalTaxInclusiveAmount / PayableAmount
amount_duePayableAmount (after prepayments)
total_discountCalculated 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

Creating Invoices

Learn the basics of invoice creation

Advanced Invoicing

Work with allowances and charges

Validation Guide

Test invoices during development

API Reference

Explore all endpoints