Invoice calculation

Overview

This guide explains how B2Brouter calculates net and gross amounts based on inputs such as quantity, price per unit, taxes, and optional discounts or charges, which can be provided as either percentages or fixed amounts. The calculations support adjustments at both the line item and invoice levels.

All the calculations and rounding are done automatically by the B2Brouter. The scope of this guide is to explain the process and what results should you expect.

Required inputs

Invoice level

These are global discounts and charges at the Invoice level:

Discount: (Optional) Can be either:
- Discount Percent (discount_percent): Percentage discount applied to the entire invoice.
- Discount Amount (discount_amount): Fixed discount amount applied to the entire invoice.
Charge: (Optional) Can be either:
- Charge Percent (charge_percent): Percentage charge applied to the entire invoice.
- Charge Amount (charge_amount): Fixed charge amount applied to the entire invoice.

Line level

For each line (invoice_lines_attributes) you need to provide the following inputs:

Quantity (quantity): Number of units.
Price (price): Price of each unit.
Taxes (taxes_attributes):
- Name: Name of the tax (e.g. VAT, IVA, IRPF).
- Category: Tax category.
- Percent: Percentage of tax applied (can be positive or negative).
Discount: (Optional) Can be either:
- Discount Percent (discount_percent): Percentage discount applied to the line.
- Discount Amount (discount_amount): Fixed discount amount applied to the line.
Charge: (Optional) Can be either:
- Charge Percent (charge_percent): Percentage charge applied to the line.
- Charge Amount (charge_amount): Fixed charge amount applied to the line.
Extension Amount: (Optional) The total "net" amount of the Invoice line before applying Taxes. If it is not provided, the API will calculate it as explained in Line-Level Net Amounts .

Calculations

Account-Level Settings

Rounding Method (rounding_method): Rounding method used for further calculations. By default it is set to Round half up (half_up)
Round Before Sum (round_before_sum): Round line taxable amounts before sum. By default it is set to false.
Apply Taxes per Line(apply_taxes_per_line): If set to true, calculate Invoice-Level tax amount by applying taxes to each line and then adding them. Otherwise add all lines' taxable bases and apply the tax to the sum. By default it is set to false.

Line level Net Amounts

Line Base Amount = Quantity * Price

If Extension Amount(extension_amount) has been provided it will be used as the line net amount in all calculations. Otherwise, we calculate the line net amount.

Line with Discount and Charge

For each line item, we calculate the net amount by applying the discount and charge:

Line Net Amount = Line Base Amount - Line Discount Amount + Line Charge Amount

If our discount or charges represented as percentages, we calculate their amount as:

Line Charge Amount   = Line Base Amount * (Line Charge Percentege / 100)

Line Discount Amount = Line Base Amount * (Line Discount Percentege / 100)

If our discount or charge amounts are fixed amounts, we can skip this step.

Finally, we calculate the line net amount by subtracting the discount and adding the charge:

Line Net Amount = Line Base Amount - Line Discount Amount + Line Charge Amount

As the line net amount must be rounded to two decimals, please note that the different parts of the calculation must be rounded separately.
For example, the result of
Line net amount = Line Base Amount must be round to two decimals, and the allowance/charge amounts are also rounded separately.

If line discount/charge amount are not provided, treat it as 0.

Line Net Amount = Line Base Amount

Invoice Level Subtotal

Sum the net amounts for all line items to calculate the subtotal. This calculation depends on the round_before_sum setting.

Round Before Sum is set to true: Rounding method is applied to each line net amount before adding them all.

Subtotal = ∑(rounding_method(Line Net Amount))

Round Before Sum is set to false: Rounding method is applied to the sum of all line net amounts.

Subtotal = rounding_method(∑(Line Net Amount))

If invoice-level discounts or charges are provided:

Subtotal = ∑(Line Net Amounts) - Invoice Discount Amount + Invoice Charge Amount

If the percent is provided for the invoice level discount or charge, we will calculate their amounts similarly as in the line level calculation.

Tax calculation logic

After calculating the line's net amount, apply taxes (if provided) based on the taxes_attributes. A negative tax percent indicates a deduction. The taxes are applied based on the apply_taxes_per_line setting.

Line Taxable Amount (or Base) = Line Net Amount

Apply Taxes per Line is set to true: The taxes will be applied to each line taxable amount (or base) and then summed up all together for the Invoice total tax amount.

Tax Calculation for Each Line

Multiple taxes may apply to each line. Each tax is applied individually.

Line Tax Amount = Line Taxable Amount × (Tax Percent / 100)

If the Round Before Sum setting is active the taxable amount for each line is rounded before the tax percentage is applied. Otherwise it will be rounded after applying tax percentage.

Line Tax Amount = rounding_method(Line Taxable Amount) x (Tax Percent / 100)

Line Tax Amount = rounding_method(Line Taxable Amount x (Tax Percent / 100))

Summing Tax Amounts per Line

The total tax amount for each line is the sum of all taxes applied to that line.

Invoice-Level Tax Calculation

The Invoice-Level Tax Amount calculation is based on the apply_taxes_per_line and round_before_sum setting. So expect 4 different approaches based on the settings:

apply_taxes_per_line = true and round_before_sum = true

The Line Taxable Amount is rounded before calculating the Line Tax Amount.
The Line Tax Amount is calculated and rounded.
Invoice Tax Amount is calculated by adding up all Line Tax Amounts.

Line Taxable Amount = rounding_method(Line Net Amount - Line Discount Amount)
Line Tax Amount = rounding_method(Line Taxable Amount x (Tax Percent / 100))
Invoice Tax Amount = ∑(Line Tax Amounts)

apply_taxes_per_line = true and round_before_sum = false

The Line Taxable Amount is calculated.
The Line Tax Amount is calculated and rounded.
Invoice Tax Amount is calculated by adding up all Line Tax Amounts.

Line Taxable Amount = Line Net Amount - Line Discount Amount
Line Tax Amount = rounding_method(Line Taxable Amount x (Tax Percent / 100))
Invoice Tax Amount = ∑(Line Tax Amounts)

apply_taxes_per_line = false and round_before_sum = true

The Line Taxable Amount is rounded before adding up.
All the Line Taxable Amounts are summed up.
Invoice Tax Amount is calculated by applying the tax to the sum.

Line Taxable Amount = rounding_method(Line Net Amount - Line Discount Amount)
Invoice Tax Amount = Line Taxable Amounts x (Tax Percent / 100)

apply_taxes_per_line = false and round_before_sum = false

The Line Taxable Amount is calculated.
All the Line Taxable Amounts are summed up.
Invoice Tax Amount is calculated by applying the tax to the sum.

Line Taxable Amount = Line Net Amount - Line Discount Amount
Invoice Tax Amount = Line Taxable Amounts x (Tax Percent / 100)

Invoice Level Total:

The total invoice amount is the subtotal plus the sum of the tax amounts from all line items.

Total = Subtotal + Invoice Tax Amount

Rounding Methods

Principles

Decimal Precision

All values are rounded to two decimal places (representing cents in most currencies).

Rounding Rules

Rounding Method setting defines how rounding is applied and it can be set up between three different options:

Round half up (half_up): Is the default rounding method. It follows these steps:
- If the third decimal place is 5 or higher, round the second decimal place up.
- If the third decimal place is 4 or lower, leave the second decimal place unchanged.
Bankers rounding (bankers): Round halfway values to the closest even value. For example:
- If the third decimal place is 6 or higher, round the second decimal place up.
- If the third decimal place is 4 or lower, leave the second decimal place down.
- If the third decimal place is 5, round the second decimal place to the closest even value. For example, 1,235 is rounded to 1,24, but 1,225 is rounded to 1,22.
Truncate (truncate): Removes the decimal part of the number to round. For example:
- The numbers 1,234 and 1,236 both will round to 1,23.

How Rounding is Applied in the API

Line-Level Calculations:
All line-level net amounts are rounded to two decimal places before any further calculations.
Tax Calculations:
Tax amounts are calculated and rounded before being added to the line net amount.
Subtotal and Invoice-Level Adjustments:
Subtotals are rounded before applying invoice-level adjustments.

Summary

First, apply rounding separately at each step (discounts, charges, and tax) to avoid compounding errors.
Always round to two decimal places before using the value in subsequent calculations.

Example API Calculation Flow

Let’s clarify how rounding is applied in a calculation involving multiple components such as discounts, charges, and taxes.

Settings

Rounding Method: bankers
Round before sum: true
Apply taxes per line: true

Input

{
  "invoice_lines_attributes": [
    {
      "quantity": 3,
      "price": 33.275,
      "taxes_attributes": [
        {
          "name": "VAT",
          "category": "S",
          "percent": 21
        }
      ],
      "discount_amount": 5,
      "charge_percent": 12.777
    },
    {
      "quantity": 7,
      "price": 5.355,
      "taxes_attributes": [
        {
          "name": "VAT",
          "category": "S",
          "percent": 21
        }
       ]
    }
  ],
  "discount_percent": 0,
  "charge_amount": 3,
  "currency": "EUR"
}

Line 1:

Quantity: 3
Price per Unit: 33,275€
Line Discount Amount: 5€
Line Charge Percent: 12,777%
Tax 1: 21%

Line 2:

Quantity: 7
Price per Unit: 5,355€
Tax 1: 21%

Invoice:

Discount Percent: 0% (Notice! You cannot set a Discount on Invoice-level with apply_taxes_per_line = true)
Charge Amount: 3€
Currency: EUR

Step-by-Step Calculation done by our API

Line Net Amount (before tax):

Line 1 calculations:
- Base Amount = 3 × 33,275€ = 99,825€ → Rounded to 99,82€.
- Discount Amount = 5,00€.
- Charge Amount = 3 × 33,275€ × 12,777/100 = 12,75464€ → Rounded to 12,76€.
  
  Final Line Net Amount 1: 99,82€ - 5,00€ + 12,76€ = 107,58€
Line 2 calculations:
- Base Amount = 7 x 5,355€ = 37,485€ → Rounded to 37,48€.
Final Line Net Amount 2: 37,48€
Invoice Subtotal:
- Sum of all Line Net Amount = 107,58€ + 37,48€ = 145.06€
- Global Discount Amount = 145.06€ × 10/100 = 14,506€ → Rounded to 14,51€.
- Global Charge Amount = €3.
  
  Invoice Subtotal : 145.06€ - 14,51€ + 3€ = 133.57€
Tax Calculation:

As apply taxes per line set to true, the taxes will be calculated for each line individually and then added up.

Line 1 tax calculations:
- Taxable Amount = 107,58€
- Tax Amount = 107,58€ × 21/100 = 22.5918€ → Rounded to 22.59€.
Line 2 tax calculations:
- Taxable Amount = 37,48€
- Tax Amount = 37,48€ × 21/100 = 7,87079€ → Rounded to 7,87€.
Invoice tax calculations:
- Taxable Amount = 107.58€ + 37.48€ = 145.06€
- Tax Amount = 22.59€ + 7,87€ = 30.46€
Notice! that we by default don't apply Global Charge Amount in to Tax calculation.
Invoice Total:
- Invoice Charge = 3€
- Invoice Subtotal = 145.06€ + 3€ = 148.06€
- Invoice Tax = 30.46€
- Invoice Total = 148.06€ + 30.46€ = 178.52€

Output

After the creation of the invoice with these inputs, we can see some of the numbers we just calculated:

 {
  "subtotal": 148.06,
  "taxes": [
    {
      "name": "VAT 21,00%",
      "base": 145.06,
      "amount": 30.46
    }
  ],
  "total": 178.52
}