Skip to main content

​
Overview

The TaxTotal class represents the total tax amount for a particular taxation scheme (e.g., VAT, Sales Tax). It contains the aggregated tax amount and detailed breakdowns through tax subtotals. This component is essential in invoices and other commercial documents for calculating and reporting tax obligations.

​
Class Definition

import { TaxTotal } from 'ubl-builder/lib/ubl21/CommonAggregateComponents';

​
Constructor Parameters

​
taxAmount
string | UdtAmount
required
The total tax amount for a particular taxation scheme (e.g., VAT). This is the sum of all tax subtotals for each tax category within the taxation scheme.
​
taxSubtotals
TaxSubtotal[]
required
An array of tax subtotals, where each subtotal represents a different tax category or rate. The sum of these subtotals equals the taxAmount.
​
roundingAmount
string | UdtAmount
The rounding amount (positive or negative) added to the calculated tax total to produce the rounded taxAmount
​
taxEvidenceIndicator
string | UdtIndicator
An indicator that this total is recognized as legal evidence for taxation purposes (true) or not (false)

​
Methods

​
setTaxAmount()

Sets the total tax amount. 
setTaxAmount(value: string | UdtAmount): void
​
value
string | UdtAmount
required
The tax amount. Can be a string (e.g., “19.00”) or a UdtAmount instance.

​
getTaxAmount()

Gets the total tax amount. 
getTaxAmount(raw?: boolean): string | UdtAmount
​
raw
boolean
default:"true"
If true, returns the raw string value. If false, returns the UdtAmount instance.
​
return
string | UdtAmount
The tax amount as a string (if raw=true) or UdtAmount instance (if raw=false)

​
getTaxSubtotals()

Returns the array of tax subtotals. 
getTaxSubtotals(): TaxSubtotal[]
​
return
TaxSubtotal[]
Array of tax subtotals

​
setTaxSubtotals()

Sets the array of tax subtotals. 
setTaxSubtotals(taxSubtotals: TaxSubtotal[]): void
​
taxSubtotals
TaxSubtotal[]
required
Array of TaxSubtotal instances. All items must be instances of the TaxSubtotal class.

​
calculateTotalTaxAmount()

Calculates the total tax amount by summing all tax subtotals. 
calculateTotalTaxAmount(): number
​
return
number
The calculated total tax amount as a number

​
Usage Examples

import { 
  TaxTotal, 
  TaxSubtotal,
  TaxCategory
} from 'ubl-builder/lib/ubl21/CommonAggregateComponents';
import { TaxScheme } from 'ubl-builder/lib/ubl21/CommonAggregateComponents';

// Create a tax category
const taxCategory = new TaxCategory({
  id: 'S',
  percent: '21',
  taxScheme: new TaxScheme({ id: 'VAT' })
});

// Create a tax subtotal
const taxSubtotal = new TaxSubtotal({
  taxableAmount: '100.00',
  taxAmount: '21.00',
  taxCategory: taxCategory
});

// Create tax total
const taxTotal = new TaxTotal({
  taxAmount: '21.00',
  taxSubtotals: [taxSubtotal]
});
The TaxTotal class is also exported as WithholdingTaxTotal for representing withholding taxes. Both exports reference the same class implementation.

​
Tax Calculation Notes

  1. Tax Subtotals: Each TaxSubtotal represents a different tax category or rate. The sum of all subtotal tax amounts should equal the taxAmount in the TaxTotal.
  2. Rounding: Use the roundingAmount field when you need to adjust for rounding differences between the sum of subtotals and the final tax amount.
  3. Multiple Tax Rates: When an invoice contains items with different tax rates, create separate TaxSubtotal instances for each rate.
  4. Document vs Line Level: Tax totals can appear at both the document level (total taxes for the entire invoice) and at the line level (taxes for individual invoice lines).
  • TaxSubtotal - Individual tax category breakdowns
  • TaxCategory - Tax category information (rate, type)
  • TaxScheme - Taxation scheme identifier (VAT, GST, etc.)
  • InvoiceLine - Uses tax totals at the line level
  • Invoice - Uses tax totals at the document level

​
UBL Schema Reference

For more information, see the UBL 2.1 TaxTotal specification.

Build docs developers (and LLMs) love

Get started for freeTalk to us