Skip to main content
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:
FieldDescriptionCan be negative?
subtotalThe taxable base (amount subject to VAT) after document-level allowances/chargesNo
total_discountTotal document-level allowances (discounts)No
total_taxThe total VAT/tax amountNo
invoice_totalThe final invoice amount including taxNo (usually)
amount_dueThe amount the customer needs to pay after prepaymentsNo
previous_unpaid_balanceAny outstanding balance from previous invoicesNo

​
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: 
{
  "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 FieldUBL Element
subtotalcac:LegalMonetaryTotal/cbc:TaxExclusiveAmount
total_taxcac:TaxTotal/cbc:TaxAmount
total_discountcac:LegalMonetaryTotal/cbc:AllowanceTotalAmount
invoice_totalcac:LegalMonetaryTotal/cbc:TaxInclusiveAmount
amount_duecac: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 or contact support.