> ## 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 in the e-invoice.be API This guide explains how invoice totals are calculated and what each field represents in our e-invoicing system. ## Overview of Total Fields Our API uses the following fields to represent invoice amounts: | Field | Description | Can be negative? | | ------------------------- | -------------------------------------------------------------------------------- | ---------------- | | `subtotal` | The taxable base (amount subject to VAT) after document-level allowances/charges | No | | `total_discount` | Total document-level allowances (discounts) | No | | `total_tax` | The total VAT/tax amount | No | | `invoice_total` | The final invoice amount including tax | No (usually) | | `amount_due` | The amount the customer needs to pay after prepayments | No | | `previous_unpaid_balance` | Any outstanding balance from previous invoices | No | ## The Basic Formula ``` invoice_total = subtotal + total_tax amount_due = invoice_total - prepaid_amount ``` Note: The `subtotal` is calculated after applying document-level allowances and charges, so `total_discount` is already factored into the subtotal. ## Understanding Each Field ### 1. 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:** * This is always positive * Only includes allowances and charges that have VAT applied to them * 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 ``` ### 2. 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 * The results are summed to get the total tax **Example:** ``` Subtotal at 21% VAT: €950.00 → Total tax: €199.50 (950.00 × 0.21) ``` ### 3. Total Discount The **total\_discount** field represents the total amount of document-level allowances (discounts) applied to the invoice. **Calculation:** ``` total_discount = sum of all document-level allowances ``` **Key points:** * This field is always positive (or zero) * Represents the total value of discounts given at the document level * These allowances are already factored into the `subtotal` * Examples: Early payment discounts, volume discounts, promotional discounts **Example:** ``` Line items: €1,000.00 Early payment discount (21% VAT): -€50.00 → Total discount: €50.00 → Subtotal (after discount): €950.00 → Tax (21%): €199.50 → Invoice total: €1,149.50 ``` ### 4. Invoice Total The **invoice\_total** is the final amount of the invoice including VAT. **Calculation:** ``` invoice_total = subtotal + total_tax ``` This is the amount before any prepayments are deducted. The subtotal already includes the effect of document-level allowances and charges. ### 5. 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 ``` ### 6. Previous Unpaid Balance The **previous\_unpaid\_balance** represents any outstanding amounts from previous invoices. This is a custom field not part of standard UBL. ## Document-Level vs Line-Level Allowances and Charges Understanding where to apply adjustments is crucial: ### Document-Level Allowances/Charges * **Affect the subtotal** (taxable base) * Applied to the entire invoice after line items are totaled * VAT is calculated on the adjusted amount * Contribute to the `total_discount` field (for allowances) * Examples: Early payment discounts, shipping charges for the entire order, handling fees ### Line-Level Allowances/Charges * **Affect individual line item amounts** * Applied to specific products or services * Do NOT appear in the document-level `total_discount` field * Examples: Bulk discount on a specific product, special handling for fragile items ## Complete Example Here's a complete invoice calculation: ```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": "Shipping", "amount": 50.00, "tax_rate": "21.00" } ] } ``` **Calculation breakdown:** 1. **Line items total:** €1,000.00 2. **Apply document-level allowances:** * Commercial discount: -€200.00 * Early payment discount: -€50.00 3. **Apply document-level charges:** * Shipping: +€50.00 4. **Subtotal (taxable base):** €800.00 5. **Calculate tax:** €800.00 × 21% = €168.00 6. **Total discount:** €250.00 (sum of allowances only) 7. **Invoice total:** €800.00 + €168.00 = **€968.00** 8. **Amount due:** €968.00 (no prepayment) ## UBL Mapping For reference, here's how our fields map to UBL (Universal Business Language) elements: | Our 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` | **Key points about UBL mapping:** * `TaxExclusiveAmount` (subtotal) is the taxable base after applying document-level allowances and charges * `AllowanceTotalAmount` (total\_discount) represents the sum of all document-level allowances * `TaxInclusiveAmount` (invoice\_total) is the total including VAT * `PayableAmount` (amount\_due) is the final amount to be paid after prepayments ## Validation Rules When creating or updating invoices, the following validations are applied: 1. **Subtotal** must match the calculated taxable base after document-level adjustments (within €0.01 tolerance) 2. **Total tax** must match the calculated VAT amount (within €0.01 tolerance) 3. **Total discount** must match the sum of document-level allowances (within €0.01 tolerance) 4. **Invoice total** must equal `subtotal + total_tax` (within €0.01 tolerance) 5. **Amount due** must be between 0 and invoice\_total (inclusive) ## Common Questions ### What's the difference between document-level and line-level allowances? * **Document-level allowances** apply to the entire invoice and are reflected in the `total_discount` field * **Line-level allowances** apply to specific line items and are included in the line item calculations, not in `total_discount` ### Can invoice\_total be negative? In theory yes, if you have large allowances, but this is unusual. Most invoices should have a positive invoice total. Credit notes are the proper way to issue refunds. ### 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. ### How are document-level charges handled? Document-level charges (like shipping fees) increase the subtotal before VAT is calculated. They are not reflected in the `total_discount` field, which only includes allowances (discounts). ## Need Help? If you have questions about invoice calculations or need help structuring your invoice data, please refer to our [API documentation](/api-reference) or contact support.