Invoice calculation

This guide explains how B2Brouter calculates net and gross amounts based on inputs such as quantity, price, base quantity, 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 calculations and rounding are done automatically by B2Brouter. The scope of this guide is to explain the process and what results you should expect.

Required inputs

Invoice level

These are global discounts and charges at the Invoice level, using allowance_charges_attributes:

Allowance (Discount): (Optional) {allowance_charge_indicator: "allowance"} with either:
- percentage: Percentage discount applied to the entire invoice.
- amount: Fixed discount amount applied to the entire invoice.
Charge: (Optional) {allowance_charge_indicator: "charge"} with either:
- percentage: Percentage charge applied to the entire invoice.
- 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 for the given base quantity of units.
Base Quantity (base_quantity): The number of units to which the price applies. Defaults to 1. Use this when the price is quoted per multiple units (e.g., price per 100 pieces).
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).
Allowance (Discount): (Optional) via allowance_charges_attributes[]{allowance_charge_indicator: "allowance"} with either:
- percentage: Percentage discount applied to the line.
- amount: Fixed discount amount applied to the line.
Charge: (Optional) via allowance_charges_attributes[]{allowance_charge_indicator: "charge"} with either:
- percentage: Percentage charge applied to the line.
- 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.
- Skip Line Taxable Base Rounding (skip_line_taxable_base_rounding): When enabled, per-line taxable bases and tax amounts are not individually rounded — only the final accumulated tax total is rounded. By default, it is set to false.
Important: This setting is intended exclusively for accounts whose ERP uses VAT-inclusive totals, as it deviates from the standard tax calculation. Requires apply_taxes_per_line: true to have any effect.

Line level Net Amounts

Line Base Amount = Quantity * Price / Base Quantity

When base_quantity is 1 (the default), this simplifies to Quantity * Price.

When base_quantity is greater than 1, it allows prices to be expressed per multiple units. For example, if screws are priced at 12.50 per 100 pieces and you order 500:

Line Base Amount = 500 * 12.50 / 100 = 62.50

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 Percentage / 100)

Line Discount Amount = Line Base Amount * (Line Discount Percentage / 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)  [Active]
Line Tax Amount = rounding_method(Line Taxable Amount x (Tax Percent / 100))  [Inactive]

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

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

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

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

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

Invoice Level Total:

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.
- 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.
- 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.
- 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

Example 1: Standard pricing

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
        }
      ],
      "allowance_charges_attributes": [
        { "allowance_charge_indicator": "allowance", "amount": 5 },
        { "allowance_charge_indicator": "charge", "percentage": 12.777 }
      ]
    },
    {
      "quantity": 7,
      "price": 5.355,
      "taxes_attributes": [
        {
          "name": "VAT",
          "category": "S",
          "percent": 21
        }
      ]
    }
  ],
  "allowance_charges_attributes": [
    { "allowance_charge_indicator": "charge", "amount": 3 }
  ],
  "currency": "EUR"
}

Step-by-Step Calculation

Line Net Amount (before tax):

Line 1:
- Base Amount = 3 × 33.275€ = 99.825€
- Allowance (discount) Amount = 5.00€.
- Charge Amount = 99.825€ × 12.777/100 = 12.75464€ → Rounded to 12.75€.
- Line Net Amount = 99.825€ - 5.00€ + 12.75€ = 107.575€ → Rounded to 107.58€.
Line 2:
- Base Amount = 7 x 5.355€ = 37.485€ → Rounded to 37.48€.
Invoice Subtotal:
- Sum of all Line Net Amount = 107.58€ + 37.48€ = 145.06€
- Global Charge Amount = 3€.
Tax Calculation (apply taxes per line = true):
- Line 1: 107.58€ × 21/100 = 22.5918€ → Rounded to 22.59€.
- Line 2: 37.48€ × 21/100 = 7.8708€ → Rounded to 7.87€.
- Total Tax = 22.59€ + 7.87€ = 30.46€
Invoice Total:
- Invoice Subtotal = 145.06€ + 3€ = 148.06€
- Invoice Total = 148.06€ + 30.46€ = 178.52€

Output

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

Example 2: Using base quantity for bulk pricing

Input

{
  "invoice_lines_attributes": [
    {
      "description": "Steel screws M6x20",
      "quantity": 500,
      "price": 12.5,
      "base_quantity": 100,
      "unit": 1,
      "taxes_attributes": [{ "name": "VAT", "category": "S", "percent": 21 }]
    },
    {
      "description": "A4 printing paper",
      "quantity": 5000,
      "price": 45.0,
      "base_quantity": 1000,
      "unit": 1,
      "taxes_attributes": [{ "name": "VAT", "category": "S", "percent": 21 }]
    }
  ],
  "currency": "EUR"
}

Step-by-Step Calculation

Line 1: 500 * 12.50 / 100 = 62.50€
Line 2: 5000 * 45.00 / 1000 = 225.00€
Subtotal: 62.50 + 225.00 = 287.50€
VAT 21%: 287.50 × 21 / 100 = 60.375 → Rounded to 60.38€
Total: 287.50 + 60.38 = 347.88€

Output

{
  "subtotal": 287.5,
  "taxes": [
    {
      "name": "VAT 21.00%",
      "base": 287.5,
      "amount": 60.38
    }
  ],
  "total": 347.88
}