finance - Currencies & taxes - WEBSALE Dokumentation

The finance configuration node bundles all shop-wide settings for currencies, taxes and tax rates.
It defines in which currency prices are displayed and formatted, whether prices are including or excluding tax and according to which calculation logic the tax is determined.
In addition, it sets the tax rates (e.g. by country/region or category) and configures optional surcharges such as deposits or levies.

`finance*` - Basic structure

The basic structure of the finance node is shown below:

{
"finance": {
  "currency": { ... },
  "taxes": { ... },
  "taxRates": { ... },
  "taxRatesAddition": { ... },
  "exchangeRates": { ... },
  "shopRent": { ... },
  "shopRentTier": { ... }
 }
}

Parameter description

Parameter	Description
`currency`	Defines the shop’s currency and formatting settings. Code (e.g. “EUR”), symbol, decimal places and separators are specified here. Values in text or numeric form.
`taxes`	Controls the basic tax logic of the shop. Contains parameters such as price basis (`gross` / `net`), display type (`pricesIncludeTaxes` = true/false) and shipping tax (`shippingTaxDeductible` = true/false). Values as key-value pairs.
`taxRates`	Contains the country-specific tax rates in list form. Each entry contains an ID (e.g. “standard”), the percentage (`rate`) and optional assignments (`appliesTo`). Structure: object with country identifier as key, array as value.
`taxRatesAddition`	Optional additional taxes or levies (e.g. deposit). The structure is analogous to `taxRates`, mostly with fields such as `type` (“fixed_per_unit” / “percent”), `value` (number) and `appliesTo` (list of item groups).
`exchangeRates`	Controls the behaviour of the automatic exchange rate retrieval. Defines fetch time, waiting time and how outdated or unavailable rates are handled.
`shopRent`	Configures the billing time of the shop rent. Contains the cutoff time on the first of the month as well as references to the associated price tiers.
`shopRentTier`	Defines individual price tiers for the shop rent with rate, volume cap and monthly base fee.

`finance.currency` - Currencies

In the currency section, one or more currencies that should be available in the shop are defined. Each currency is created as its own sub-node and contains formatting rules and ISO information. These definitions specify the symbol, notation and separators later used in the frontend when displaying prices. The assignment of which currency a subshop actually uses is done in the subshop configuration.

Example configuration for EURO (`finance.currency.euro`)

{
  "decimalPlaces": 2,
  "decimalSeparator": ",",
  "isoCode": "EUR",
  "isoNum": "978",
  "symbol": "€",
  "symbolPosition": "right",
  "thousandsSeparator": "."
}

Example configuration for BRITISH POUND (`finance.currency.britishpound`)

{
  "decimalPlaces": 2,
  "decimalSeparator": ".",
  "isoCode": "GBP",
  "isoNum": "826",
  "symbol": "£",
  "symbolPosition": "left",
  "thousandsSeparator": ","
}

Parameter description

Parameter	Type	Description
`decimalPlaces`	int	Number of decimal places shown for prices (e.g. 2 → “19.99 €”).
`decimalSeparator`	string	Character separating integer and decimal parts (e.g. `","` or `"."`).
`thousandsSeparator`	string	Character separating thousands (e.g. `"."` or `","`).
`symbol`	string	Currency symbol shown in the shop (e.g. `"€"`, `"£"`, `"$"`).
`symbolPosition`	enum	Position of the symbol relative to the amount. Possible values: `left` (e.g. “£19.99”) or `right` (e.g. “19.99 €”).
`isoCode`	string	Three-letter ISO-4217 code of the currency (e.g. `"EUR"`, `"GBP"`, `"CHF"`). Used internally for identification.
`isoNum`	string	Numeric ISO-4217 code of the currency (e.g. `978` = euro, `826` = pound). Used for international processes and API communication.

`finance.taxRates` - Tax rates

In the taxRates section, the concrete VAT rates per country or region are defined.
Each entry corresponds to a country (e.g. de, en, at) and contains a list of tax rates that the system can use for price calculation. These definitions are globally available and are usually referenced via finance.taxes.defaultTaxRate or in the respective subshop configuration.

Example configuration for German tax rates (`finance.taxRates.de`)

{
  "id": "de",
  "defaultTaxRate": "19",
  "taxRates": [
    {
      "id": "19",
      "rate": 0.19
    },
    {
      "id": "7",
      "rate": 0.07
    },
    {
      "id": "0",
      "rate": 0
    }
  ]
}

Example configuration for English tax rates (`finance.taxRates.en`)

{
  "id": "en",
  "defaultTaxRate": "19",
  "taxRates": [
    {
      "id": "20",
      "rate": 0.2
    },
    {
      "id": "5",
      "rate": 0.05
    },
    {
      "id": "0",
      "rate": 0
    }
  ]
}

Parameter description

Parameter	Type	Description
`id`	string	Internal identifier for the tax definition of the country. Usually identical to the country code.
`defaultTaxRate`	string	Default tax rate ID used when no specific rate is assigned (e.g. `"19"`).
`taxRates`	list (object)	List of all available tax rates for this country. Each entry contains a unique ID and the rate as a decimal value.
`id`	string	Identifier of the tax rate (e.g. `"19"`, `"7"`, `"zero"`). Used as a reference within the system.
`rate`	float	Tax value as a decimal number, not as a percentage (e.g. `0.19` = 19 %). Used for price calculation.

`finance.taxRatesAddition` - Additional tax rates

In the taxRatesAddition section, additional tax surcharges can be defined that apply in addition to the regular VAT rates. This can be used, for example, for deposit amounts, environmental levies or special taxes. Each country definition references the existing tax rates (finance.taxRates.<country>) and adds one or more additional rates to them.

Example configuration for German additional tax rates (`finance.taxRatesAddition.de`)

{
  "additionalTaxRates": [
    {
      "id": "30",
      "rate": 0.3
    }
  ],
  "id": "de",
  "taxRates": "finance.taxRates.de"
}

Example configuration for English additional tax rates (`finance.taxRatesAddition.en`)

{
  "additionalTaxRates": [
        {
          "id": "luxury",
          "rate": 0.25
        },
        {
          "id": "environment",
          "rate": 0.10
        }
  ],
  "id": "en",
  "taxRates": "finance.taxRates.en"
}

Parameter description

Parameter	Type	Description
`id`	string	Identifier of the country tax definition, usually identical to the country code.
`taxRates`	singleAssoc	Reference to the regular tax rates the additional taxes build upon (e.g. `"finance.taxRates.de"`).
`additionalTaxRates`	list (object)	List of additional tax rates that can be applied in addition to the regular ones.
`id`	string	Unique identifier of the additional tax (e.g. `"30"`, `"luxury"`, `"environment"`).
`rate`	float	Tax or surcharge value as a decimal number (e.g. `0.10` = 10 %). Calculated in addition to the regular rate.

`finance.taxes` - Tax calculation

The finance.taxes section defines the calculation logic and the assignment of the tax rates used in the respective shop or subshop. Here you specify:

whether prices are stored including or excluding tax,
which tax rates from the finance.taxRates configuration are used,
and how main and ancillary services (e.g. products, shipping) are calculated for tax purposes,
whether VAT is deductible for shipping costs, payment method costs and minimum quantity surcharges,
and under which mode a country-based tax exemption applies.

This section therefore forms the link between the defined tax rates (finance.taxRates) and the practical application in the subshop.

Example configuration

{
  "ancillaryServicesCalculation": "static",
  "ancillaryServicesTaxRate": "19",
  "defaultTaxRate": "finance.taxRates.de",
  "mainServicesCalculation": "vertical",
  "pricesIncludeTaxes": true,
  "shippingTaxDeductible": true,
  "paymentTaxDeductible": true,
  "surchargeTaxDeductible": false,
  "usedTaxes": "finance.taxRates.de",
  "countryTaxMode": "exemptList",
  "countryList": ["general.country.de", "general.country.at"],
  "countryTaxAddressMatching": "shippingAndBilling"
}

Parameter description

Property	Type	Description
`pricesIncludeTaxes`	bool	Defines whether product prices are stored including tax (true) or excluding tax (false).
`defaultTaxRate`	singleAssoc	Reference to the default tax rate definition. Typically this entry references a node under `finance.taxRates` (e.g. `finance.taxRates.de`).
`usedTaxes`	singleAssoc	Specifies which tax rates from the `taxRates` configuration are actively used in the shop. Can contain one or more references.
`mainServicesCalculation`	enum	Defines the tax calculation method. Example values: `horizontal` (calculation per position) or `vertical` (calculation on total).
`ancillaryServicesCalculation`	enum	Defines the calculation logic for ancillary services (e.g. shipping). Possible values: - `static` — fixed tax rate. - `distributed` — proportionally to the goods tax. - `highestCost` — tax rate associated with the highest goods value.
`ancillaryServicesTaxRate`	string	Fixed percentage rate for ancillary services (e.g. shipping cost tax = “19”). Only used if `ancillaryServicesCalculation = "static"`.
`shippingTaxDeductible`	bool	Defines whether VAT for shipping costs is deductible (`true`) or not (`false`).
`paymentTaxDeductible`	bool	Defines whether VAT for payment method costs is deductible (`true`) or not (`false`).
`surchargeTaxDeductible`	bool	Defines whether VAT for the minimum quantity surcharge is deductible (`true`) or not (`false`).
`countryTaxMode`	enum	Controls the mode of country-based tax exemption. Possible values: - `taxableList` — only countries in the list are taxable (all others are exempt). - `exemptList` — only countries in the list are tax-exempt. - `disabled` — feature disabled. Default: `disabled`
`countryList`	multiAssoc -> `general.country`	List of countries to which the selected `countryTaxMode` is applied.
`countryTaxAddressMatching`	enum	Determines whether only the delivery address or delivery and billing addresses are used for the tax check. Possible values: - `shippingOnly` — only the delivery address is checked. - `shippingAndBilling` — both addresses must (depending on the mode) satisfy the condition. Default: `shippingOnly`

`finance.exchangeRates` - Exchange rate retrieval

The exchangeRates section defines the configuration of the automatic exchange rate retrieval. Here you specify:

the time at which ECB daily rates are published,
how long after the publication the retrieval is delayed,
and how the system handles outdated or unavailable rates.

Example configuration

{
  "ecbRefreshTimeCET": "16:00",
  "enforceRateRecency": true,
  "fallbackToPreviousRate": true,
  "fetchDelayMinutes": 30,
  "maxRateAgeDays": 7
}

Parameter description

Property	Type	Description
`ecbRefreshTimeCET`	string	Time (CET) at which the ECB publishes daily rates. Default: `"16:00"`
`fetchDelayMinutes`	int	Minutes to wait after the update time before the retrieval. Default: `30`
`enforceRateRecency`	bool	Reject rates older than `maxRateAgeDays`. Default: `true`
`maxRateAgeDays`	int	Maximum allowed age of a rate in days. Default: `7`
`fallbackToPreviousRate`	bool	Use an older rate if the current one is unavailable. Default: `true`

`finance.shopRent` - Billing time

In the shopRent section, the billing time for the shop rent is configured. Here you define:

the time on the first of the month at which the billing period ends,
and which price tiers (shopRentTier) are used for the billing.

Example configuration

{
  "cutoffCET": "00:30",
  "tiers": [
    "finance.shopRentTier.starter",
    "finance.shopRentTier.professional",
    "finance.shopRentTier.enterprise"
  ]
}

Parameter description

Property	Type	Description
`cutoffCET`	string	CET cutoff time on the 1st of the month at which the billing period ends.
`tiers`	multiAssoc → shopRentTier	References to the price tier definitions used for the billing.

`finance.shopRentTier` - Price tiers

In the shopRentTier section the individual price tiers for the shop rent are defined. Each tier defines a percentage rate, a volume cap and a fixed monthly fee. The assignment of the active tiers is done via finance.shopRent.

Example configuration for the “Starter” tier (`finance.shopRentTier.starter`)

{
  "name": "Starter",
  "rate": 0.02,
  "maxTransactionVolume": 10000,
  "monthsFee": 29.99
}

Example configuration for the “Professional” tier (`finance.shopRentTier.professional`)

{
  "name": "Professional",
  "rate": 0.015,
  "maxTransactionVolume": 50000,
  "monthsFee": 99.99
}

Parameter description

Property	Type	Description
`name`	string (unique)	Unique tier name (e.g. “Starter”, “Professional”). Used as a reference within the system.
`rate`	float	Percentage rate for the rent calculation as a decimal value (e.g. 0.02 = 2 %).
`maxTransactionVolume`	int	EUR volume cap for this tier. When exceeded, the next tier applies.
`monthsFee`	float	Fixed monthly base fee in EUR, independent of the transaction volume.

​finance* - Basic structure

​Parameter description

​finance.currency - Currencies

​Example configuration for EURO (finance.currency.euro)

​Example configuration for BRITISH POUND (finance.currency.britishpound)

​Parameter description

​finance.taxRates - Tax rates

​Example configuration for German tax rates (finance.taxRates.de)

​Example configuration for English tax rates (finance.taxRates.en)

​Parameter description

​finance.taxRatesAddition - Additional tax rates

​Example configuration for German additional tax rates (finance.taxRatesAddition.de)

​Example configuration for English additional tax rates (finance.taxRatesAddition.en)

​Parameter description

​finance.taxes - Tax calculation

​Example configuration

​Parameter description

​finance.exchangeRates - Exchange rate retrieval

​Example configuration

​Parameter description

​finance.shopRent - Billing time

​Example configuration

​Parameter description

​finance.shopRentTier - Price tiers

​Example configuration for the “Starter” tier (finance.shopRentTier.starter)

​Example configuration for the “Professional” tier (finance.shopRentTier.professional)

​Parameter description

`finance*` - Basic structure

Parameter description

`finance.currency` - Currencies

Example configuration for EURO (`finance.currency.euro`)

Example configuration for BRITISH POUND (`finance.currency.britishpound`)

Parameter description

`finance.taxRates` - Tax rates

Example configuration for German tax rates (`finance.taxRates.de`)

Example configuration for English tax rates (`finance.taxRates.en`)

Parameter description

`finance.taxRatesAddition` - Additional tax rates

Example configuration for German additional tax rates (`finance.taxRatesAddition.de`)

Example configuration for English additional tax rates (`finance.taxRatesAddition.en`)

Parameter description

`finance.taxes` - Tax calculation

Example configuration

Parameter description

`finance.exchangeRates` - Exchange rate retrieval

Example configuration

Parameter description

`finance.shopRent` - Billing time

Example configuration

Parameter description

`finance.shopRentTier` - Price tiers

Example configuration for the “Starter” tier (`finance.shopRentTier.starter`)

Example configuration for the “Professional” tier (`finance.shopRentTier.professional`)

Parameter description