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.
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
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(default1) and the line-level allowances and charges of each item. It does not use theamountof the item for this sum. Send anamountthat agrees with this calculation. - All document-level allowances and charges are in the subtotal, also those with a
tax_rateof0.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_ratemore than0.00decreases the tax base of that rate. A document-level charge with atax_ratemore than0.00increases it. Allowances and charges with atax_rateof0.00do not change a tax base. - For each rate: tax = tax base × rate / 100, rounded to 2 decimals.
total_taxis the sum of these amounts.
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 subtracttotal_discountagain. - Line-level allowances and document-level charges are not in this field.
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.00to5.00. It can be negative. The API rejects a value outside this range with422. For example,"rounding_amount": 6gives themsgInput 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.405gives themsgDecimal input should have no more than 2 decimal places, withloc["body", "rounding_amount"]. - A JSON number with a small binary error is accepted. For example,
-0.6000000000000227(the result ofMath.round(total) - totalin JavaScript) becomes-0.60. - The API does not calculate this field. If you omit it, the API uses
0. rounding_amountdoes not changesubtotal,total_taxorinvoice_total. It changes onlyamount_due.
"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
Usetax_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 gives422. This field is not limited to the codes ofcurrency.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_currencywithouttotal_tax_in_tax_currencygives themsgValue error, tax_currency requires total_tax_in_tax_currency (BR-53). tax_currencymust be different fromcurrency(rulePEPPOL-EN16931-R005). If they are equal, the API returns422with themsgValue error, tax_currency must differ from currency (PEPPOL-EN16931-R005).total_tax_in_tax_currencydoes not changetotal_tax,invoice_totaloramount_due. These totals stay incurrency.
<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 than0.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:- Line total: €1,000.00
- Document-level allowances: -€200.00 and -€50.00
- Document-level charge: +€50.00
subtotal: €800.00total_tax: €800.00 × 21% = €168.00total_discount: €250.00 (allowances only)invoice_total: €800.00 + €168.00 = €968.00amount_due: €968.00 (no prepayment)
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:
subtotal,total_tax,total_discountandinvoice_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_duemust not be more than the calculatedinvoice_total+rounding_amount+ 0.01.- If
rounding_amountis not0,amount_duemust not be equal toinvoice_total. Sendinvoice_total+rounding_amount, or omitamount_due.
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
What is the difference between document-level and line-level allowances?
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?
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?
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 + rounding_amount (or to invoice_total if you do not send rounding_amount). The response of the create call contains the calculated values.How are document-level charges handled?
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