Skip to main content

Overview

Each invoice and credit note has five total fields and an optional rounding amount. You can send the total fields 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

The API returns these fields as strings (for example "950.00"). The schema also has the field previous_unpaid_balance. The API ignores it: the totals checks do not use it, the UBL does not contain it, and the response does not return it. For example, "previous_unpaid_balance": 100.00 does not change amount_due.

Basic formula

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.
  • The API calculates the line total from quantity, unit_price, price_base_quantity (default 1) 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:

Total tax

total_tax is the sum of the VAT of each tax rate.
  1. The API adds the line results together for each tax_rate.
  2. 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.
  3. For each rate: tax = tax base × rate / 100, rounded to 2 decimals.
  4. total_tax is the sum of these amounts.
Example:
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.
  • 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:

Invoice total

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

Amount due

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

Rounding amount

rounding_amount (BT-114) is an amount that the API adds to invoice_total to get a rounded amount for payment. For example, use it to round a Swedish invoice to whole kronor.
  • The value is from -5.00 to 5.00. It can be negative. The API rejects a value outside this range with 422. For example, "rounding_amount": 6 gives the msg Input should be less than or equal to 5.
  • The value has a maximum of 2 decimals. The API rejects a value with more decimals with 422. For example, "rounding_amount": 0.405 gives the msg Decimal input should have no more than 2 decimal places, with loc ["body", "rounding_amount"].
  • A JSON number with a small binary error is accepted. For example, -0.6000000000000227 (the result of Math.round(total) - total in JavaScript) becomes -0.60.
  • The API does not calculate this field. If you omit it, the API uses 0.
  • rounding_amount does not change subtotal, total_tax or invoice_total. It changes only amount_due.
When there is no prepayment:
Example: the invoice total is SEK 1,249.60. You round it to SEK 1,250.00.
To round down, send a negative value. For an invoice total of SEK 1,249.40, send "rounding_amount": -0.40 and "amount_due": 1249.00. If you send rounding_amount, also send an amount_due that includes it, or omit amount_due. The API rejects an amount_due that is equal to invoice_total when rounding_amount is not 0. With a prepayment, the formula is the Peppol rule BR-CO-16:

Total tax in the VAT accounting currency

Use tax_currency and total_tax_in_tax_currency when the invoice currency is not the currency of your VAT return. For example, a Belgian vendor sends an invoice in USD, but declares the VAT in EUR.
  • tax_currency (BT-6) is the VAT accounting currency, as an ISO 4217 code in capital letters. A code that is not in ISO 4217 gives 422. This field is not limited to the codes of currency.
  • total_tax_in_tax_currency (BT-111) is the total VAT in that currency. You calculate it. The API does not convert amounts.
  • Send the two fields together. If you send only one, the API returns 422. For example, tax_currency without total_tax_in_tax_currency gives the msg Value error, tax_currency requires total_tax_in_tax_currency (BR-53).
  • tax_currency must be different from currency (rule PEPPOL-EN16931-R005). If they are equal, the API returns 422 with the msg Value error, tax_currency must differ from currency (PEPPOL-EN16931-R005).
  • total_tax_in_tax_currency does not change total_tax, invoice_total or amount_due. These totals stay in currency.
Example: the VAT is USD 210.00. At the exchange rate of the tax date, this is EUR 193.20.
The UBL then contains <cbc:TaxCurrencyCode>EUR</cbc:TaxCurrencyCode> and a second cac:TaxTotal. The second cac:TaxTotal has only <cbc:TaxAmount currencyID="EUR">193.20</cbc:TaxAmount>, with no VAT breakdown.

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:
Calculation:
  1. Line total: €1,000.00
  2. Document-level allowances: -€200.00 and -€50.00
  3. Document-level charge: +€50.00
  4. subtotal: €800.00
  5. total_tax: €800.00 × 21% = €168.00
  6. total_discount: €250.00 (allowances only)
  7. invoice_total: €800.00 + €168.00 = €968.00
  8. amount_due: €968.00 (no prepayment)
The totals that you can send with this document:

UBL mapping

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:
  1. 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.
  2. amount_due must not be more than the calculated invoice_total + rounding_amount + 0.01.
  3. If rounding_amount is not 0, amount_due must not be equal to invoice_total. Send invoice_total + rounding_amount, or omit amount_due.
The API does not write the subtotal, total_tax, total_discount and invoice_total that you send to the UBL. The UBL always contains the values that the API calculates. For the UBL, the API adds the line amount values together, and then applies the document-level allowances and charges. For example, one line with "amount": 1000.00 and no allowances or charges gives cbc:TaxExclusiveAmount 1000.00, also if you send "subtotal": 1000.50. The API stores and returns the values that you send. Thus the UBL can be different from the response by a maximum of 1.00. amount_due and rounding_amount go to the UBL as you send them. Exception: if amount_due is within 0.01 of invoice_total + rounding_amount, the UBL contains that sum. 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

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.
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.
The API calculates each of subtotal, total_tax, total_discount and invoice_total that you omit, and sets amount_due to invoice_total + rounding_amount (or to invoice_total if you do not send rounding_amount). The response of the create call contains the calculated values.
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