API Reference

VatCalculator Class

The main class for handling VAT calculations and validations.

Constructor

constructor(config: Partial<VatCalculatorConfig> = {})

Creates a new VAT calculator instance with optional configuration.

Configuration Options

interface VatCalculatorConfig {
  businessCountryCode?: CountryCode
  validateVatNumbers?: boolean
  validatePostalCodes?: boolean
  validateCountryCodes?: boolean
  forwardSoapFaults?: boolean
  soapTimeout?: number
  rules?: VatRules
}

Core Methods

calculate

calculate(
  netPrice: number,
  countryCode?: CountryCode,
  postalCode?: string,
  company: boolean = false,
  type?: VatRateType
): VatCalculationResult

Calculates VAT for a given price and location.

Returns:

interface VatCalculationResult {
  netPrice: number
  grossPrice: number
  vatAmount: number
  vatRate: number
  countryCode: CountryCode
  isCompany: boolean
  details: {
    ruleApplied: VatRateType
    reverseCharge: boolean
    vatNumberUsed?: string
    postalCodeUsed?: string
  }
}

calculateNet

calculateNet(
  grossPrice: number,
  countryCode?: CountryCode,
  postalCode?: string,
  company: boolean = false,
  type?: VatRateType
): VatCalculationResult

Calculates the net price from a gross price.

VAT Number Methods

isValidVatNumber

async isValidVatNumber(vatNumber: string): Promise<boolean>

Validates a VAT number against the VIES service.

getVatDetails

async getVatDetails(vatNumber: string): Promise<VatNumberValidationResult>

Gets detailed information about a VAT number.

Returns:

interface VatNumberValidationResult {
  isValid: boolean
  name?: string
  address?: string
  countryCode?: CountryCode
  vatNumber?: string
  isCompany: boolean
}

Setter Methods

setCountryCode

setCountryCode(countryCode: CountryCode): this

Sets the country code for VAT calculations.

setPostalCode

setPostalCode(postalCode: string): this

Sets the postal code for VAT calculations.

setCompany

setCompany(company: boolean): this

Sets whether the customer is a business.

setVatNumber

setVatNumber(vatNumber: string): this

Sets the VAT number for the calculation.

setBusinessCountryCode

setBusinessCountryCode(businessCountryCode: CountryCode): this

Sets the business country code.

Getter Methods

getNetPrice

getNetPrice(): number

Gets the current net price.

getCountryCode

getCountryCode(): CountryCode | undefined

Gets the current country code.

getPostalCode

getPostalCode(): string | undefined

Gets the current postal code.

isCompany

isCompany(): boolean

Gets whether the customer is a business.

getVatNumber

getVatNumber(): string | undefined

Gets the current VAT number.

Utility Methods

shouldCollectVat

shouldCollectVat(countryCode: CountryCode): boolean

Determines whether VAT should be collected for a given country.

getTaxRateForCountry

getTaxRateForCountry(
  countryCode: CountryCode,
  company: boolean = false,
  type?: VatRateType
): number

Gets the VAT rate for a specific country.

getTaxRateForLocation

getTaxRateForLocation(
  countryCode: CountryCode,
  postalCode?: string,
  company: boolean = false,
  type?: VatRateType
): number

Gets the VAT rate for a specific location, considering special territories.

Types

CountryCode

type CountryCode = 'AT' | 'BE' | 'BG' | 'CY' | 'CZ' | 'DE' | 'DK' | 'EE' | 'EL' |
  'ES' | 'FI' | 'FR' | 'GB' | 'HR' | 'HU' | 'IE' | 'IT' | 'LT' | 'LU' | 'LV' |
  'MT' | 'NL' | 'PL' | 'PT' | 'RO' | 'SE' | 'SI' | 'SK'

VatRateType

type VatRateType = 'standard' | 'reduced' | 'super-reduced' | 'parking' | 'high' | 'low'

VatRules

interface VatRules {
  [key: string]: CountryVatRule
}

interface CountryVatRule {
  rate: number
  rates?: {
    [key in VatRateType]?: number
  }
  specialRules?: {
    vatNumberRequired?: boolean
    reverseCharge?: boolean
  }
}

Exceptions

The library throws the following exceptions:

VatCalculatorException

Base exception class for all VAT calculator errors.

InvalidCountryCodeException

Thrown when an invalid country code is provided.

InvalidPostalCodeException

Thrown when an invalid postal code format is provided.

InvalidVatNumberException

Thrown when an invalid VAT number format is provided.

VatCheckUnavailableException

Thrown when the VIES VAT validation service is unavailable.

Usage Examples

See the Usage Guide for detailed examples of how to use these APIs.