Invoice Totals and Calculations

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:

{
  "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:

Line items total: €1,000.00
Apply document-level allowances:
- Commercial discount: -€200.00
- Early payment discount: -€50.00
Apply document-level charges:
- Shipping: +€50.00
Subtotal (taxable base): €800.00
Calculate tax: €800.00 × 21% = €168.00
Total discount: €250.00 (sum of allowances only)
Invoice total: €800.00 + €168.00 = €968.00
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:

Subtotal must match the calculated taxable base after document-level adjustments (within €0.01 tolerance)
Total tax must match the calculated VAT amount (within €0.01 tolerance)
Total discount must match the sum of document-level allowances (within €0.01 tolerance)
Invoice total must equal subtotal + total_tax (within €0.01 tolerance)
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.

Getting started

Core guides

Alternative formats

Integration

Partners

Invoice Totals and Calculations

Overview of Total Fields

The Basic Formula

Understanding Each Field

1. Subtotal (Taxable Base)

2. Total Tax

3. Total Discount

4. Invoice Total

5. Amount Due

6. Previous Unpaid Balance

Document-Level vs Line-Level Allowances and Charges

Document-Level Allowances/Charges

Line-Level Allowances/Charges

Complete Example

UBL Mapping

Validation Rules

Common Questions

What’s the difference between document-level and line-level allowances?

Can invoice_total be negative?

What if I don’t provide these fields?

How are document-level charges handled?

Need Help?

​Overview of Total Fields

​The Basic Formula

​Understanding Each Field

​1. Subtotal (Taxable Base)

​2. Total Tax

​3. Total Discount

​4. Invoice Total

​5. Amount Due

​6. Previous Unpaid Balance

​Document-Level vs Line-Level Allowances and Charges

​Document-Level Allowances/Charges

​Line-Level Allowances/Charges

​Complete Example

​UBL Mapping

​Validation Rules

​Common Questions

​What’s the difference between document-level and line-level allowances?

​Can invoice_total be negative?

​What if I don’t provide these fields?

​How are document-level charges handled?

​Need Help?

Overview of Total Fields

The Basic Formula

Understanding Each Field

1. Subtotal (Taxable Base)

2. Total Tax

3. Total Discount

4. Invoice Total

5. Amount Due

6. Previous Unpaid Balance

Document-Level vs Line-Level Allowances and Charges

Document-Level Allowances/Charges

Line-Level Allowances/Charges

Complete Example

UBL Mapping

Validation Rules

Common Questions

What’s the difference between document-level and line-level allowances?

Can invoice_total be negative?

What if I don’t provide these fields?

How are document-level charges handled?

Need Help?