Invoice totals and calculations

Overview

Each invoice and credit note has five total fields. You can send them or omit them:

If you omit a field, the API calculates it from the line items, the document-level allowances and the document-level charges.
If you send a field, the API compares it with its own calculation and rejects the document if the difference is too large.

This page gives the formulas that the API uses. To add allowances and charges to a document, refer to Advanced invoicing.

Total fields

Field	Description
`subtotal`	The amount without VAT, after document-level allowances and charges
`total_discount`	The sum of the document-level allowances
`total_tax`	The total VAT amount
`invoice_total`	The amount with VAT
`amount_due`	The amount that the customer must pay after prepayments

The API returns these fields as strings (for example "950.00").

Basic formula

line total     = sum of (quantity × unit_price - line allowances + line charges)
subtotal       = line total - document-level allowances + document-level charges
invoice_total  = subtotal + total_tax
amount_due     = invoice_total - prepayment

The API rounds each line result and each total to 2 decimals (half up).

Each field in detail

Subtotal

subtotal is the amount of the invoice without VAT.

subtotal = line total
         - sum of all document-level allowances
         + sum of all document-level charges

The API calculates the line total from quantity, unit_price and the line-level allowances and charges of each item. It does not use the amount of the item for this sum. Send an amount that agrees with this calculation.
All document-level allowances and charges are in the subtotal, also those with a tax_rate of 0.00.

Example:

Line items: €1,000.00
Commercial discount: -€100.00
Shipping charge: +€50.00
Subtotal: €950.00

Total tax

total_tax is the sum of the VAT of each tax rate.

The API adds the line results together for each tax_rate.
A document-level allowance with a tax_rate more than 0.00 decreases the tax base of that rate. A document-level charge with a tax_rate more than 0.00 increases it. Allowances and charges with a tax_rate of 0.00 do not change a tax base.
For each rate: tax = tax base × rate / 100, rounded to 2 decimals.
total_tax is the sum of these amounts.

Example:

Tax base at 21%: €950.00
Total tax: €199.50 (950.00 × 0.21)

A document-level allowance or charge has a default tax_rate of 21.00. Send the tax_rate and the tax category code of the items to which it applies. Items without VAT use a category such as E, and an exemption can need a VATEX code.

Total discount

total_discount is the sum of all document-level allowances.

total_discount = sum of all document-level allowances

These allowances are already subtracted in subtotal. Do not subtract total_discount again.
Line-level allowances and document-level charges are not in this field.

Example:

Line items: €1,000.00
Early payment discount (21% VAT): -€50.00

Total discount: €50.00
Subtotal: €950.00
Tax (21%): €199.50
Invoice total: €1,149.50

Invoice total

invoice_total is the amount of the invoice with VAT, before prepayments.

invoice_total = subtotal + total_tax

Amount due

amount_due is the amount that the customer must pay. If you omit it, the API sets it to invoice_total. There is no separate field for a prepayment. To state a prepayment, send an amount_due that is lower than invoice_total. If the difference is more than 0.01, the API writes the difference to the UBL as the prepaid amount.

Invoice total: €1,199.50
Amount due: €999.50
Prepaid amount in the UBL: €200.00

Document-level and line-level adjustments

Document-level allowances and charges

Change subtotal.
Apply to the full invoice, after the line items are added together.
Change the tax base of their tax_rate (if that rate is more than 0.00).
Allowances are added to total_discount. Charges are not.
Examples: early payment discounts, shipping for the full order, handling fees.

Line-level allowances and charges

Change the amount of one line item.
Are not in total_discount.
Examples: bulk discount on one product, special handling for a fragile item.

Complete example

This fragment shows the parts of a document that the totals are calculated from:

{
  "items": [
    {
      "description": "Product A",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "allowances": [
    {
      "reason": "Commercial discount",
      "amount": 200.00,
      "tax_code": "S",
      "tax_rate": "21.00"
    },
    {
      "reason": "Early payment discount",
      "amount": 50.00,
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ],
  "charges": [
    {
      "reason": "Shipping",
      "amount": 50.00,
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Calculation:

Line total: €1,000.00
Document-level allowances: -€200.00 and -€50.00
Document-level charge: +€50.00
subtotal: €800.00
total_tax: €800.00 × 21% = €168.00
total_discount: €250.00 (allowances only)
invoice_total: €800.00 + €168.00 = €968.00
amount_due: €968.00 (no prepayment)

The totals that you can send with this document:

{
  "subtotal": 800.00,
  "total_discount": 250.00,
  "total_tax": 168.00,
  "invoice_total": 968.00,
  "amount_due": 968.00
}

UBL mapping

API 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`

The API also writes LineExtensionAmount (the sum of the line amounts), ChargeTotalAmount (the sum of the document-level charges) and, for a prepayment, PrepaidAmount. These elements have no API field.

Validation rules

POST /api/documents/ and POST /api/validate/json do these checks on the totals:

subtotal, total_tax, total_discount and invoice_total: each value that you send must agree with the value that the API calculates. The API permits a maximum difference of 1.00.
amount_due must not be more than the calculated invoice_total plus 1.00.

If a check fails, the API returns 406 and names the field, the value that you sent and the calculated value (for example Subtotal mismatch: provided 900.00, calculated 800.00). Refer to Errors and troubleshooting for the error format. After these checks, the generated UBL must also pass the Peppol BIS Billing 3.0 rules. Refer to Validation during development.

Frequently asked questions

What is the difference between document-level and line-level allowances?

A document-level allowance applies to the full invoice and is in total_discount. A line-level allowance applies to one line item, decreases the amount of that line, and is not in total_discount.

Can a total be negative?

The totals check of the API has no minimum value for subtotal, total_tax, total_discount, invoice_total or amount_due. It only compares each value with the calculated value. Thus invoice_total is negative when the document-level allowances are larger than the line total plus the charges, or when the lines have negative quantities.To refund or correct an invoice, send a credit note with positive amounts, not an invoice with a negative total.

What occurs if I do not send the total fields?

The API calculates each of subtotal, total_tax, total_discount and invoice_total that you omit, and sets amount_due to invoice_total. The response of the create call contains the calculated values.

How are document-level charges handled?

A document-level charge (for example a shipping fee) increases subtotal. If its tax_rate is more than 0.00, it also increases the tax base of that rate. It is not in total_discount.

Next Steps

Advanced invoicing

Add allowances and charges at document level and line level

Validation during development

Examine a document before you create it

Errors and troubleshooting

Read the error formats and the frequent rule failures

Document

See all fields of a document

Getting started

Send documents

Receive and manage

Other input formats

Integrate

SDKs and tools

Resellers

Reference

Invoice totals and calculations

Overview

Total fields

Basic formula

Each field in detail

Subtotal

Total tax

Total discount

Invoice total

Amount due

Document-level and line-level adjustments

Document-level allowances and charges

Line-level allowances and charges

Complete example

UBL mapping

Validation rules

Frequently asked questions

Next Steps

Advanced invoicing

Validation during development

Errors and troubleshooting

Document

​Overview

​Total fields

​Basic formula

​Each field in detail

​Subtotal

​Total tax

​Total discount

​Invoice total

​Amount due

​Document-level and line-level adjustments

​Document-level allowances and charges

​Line-level allowances and charges

​Complete example

​UBL mapping

​Validation rules

​Frequently asked questions

​Next Steps

Advanced invoicing

Validation during development

Errors and troubleshooting

Document

Overview

Total fields

Basic formula

Each field in detail

Subtotal

Total tax

Total discount

Invoice total

Amount due

Document-level and line-level adjustments

Document-level allowances and charges

Line-level allowances and charges

Complete example

UBL mapping

Validation rules

Frequently asked questions

Next Steps