> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# finance - Currencies & taxes
> The finance node bundles shop-wide settings for currencies, price formatting, gross/net logic, tax rates and optional surcharges such as deposits or levies.
export const KonfigDeeplink = ({node}) => <>
You can open this setting directly in the Admin Interface via the following link:{" "}
{`https:///admin/config/${node}`}{" "}
(Deeplink overview)
;
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:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"decimalPlaces": 2,
"decimalSeparator": ",",
"isoCode": "EUR",
"isoNum": "978",
"symbol": "€",
"symbolPosition": "right",
"thousandsSeparator": "."
}
```
#### Example configuration for BRITISH POUND (`finance.currency.britishpound`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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](https://www.iso.org/iso-4217-currency-codes.html) of the currency (e.g. `"EUR"`, `"GBP"`, `"CHF"`). Used internally for identification. |
| `isoNum` | string | Numeric [ISO-4217 code](https://www.iso.org/iso-4217-currency-codes.html) 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`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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.`) and adds one or more additional rates to them.
#### Example configuration for German additional tax rates (`finance.taxRatesAddition.de`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"additionalTaxRates": [
{
"id": "30",
"rate": 0.3
}
],
"id": "de",
"taxRates": "finance.taxRates.de"
}
```
#### Example configuration for English additional tax rates (`finance.taxRatesAddition.en`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"name": "Starter",
"rate": 0.02,
"maxTransactionVolume": 10000,
"monthsFee": 29.99
}
```
#### Example configuration for the "Professional" tier (`finance.shopRentTier.professional`)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. |