finance - Währungen & Steuern - WEBSALE Dokumentation

Der Konfigurationsknoten finance bündelt alle shopweiten Einstellungen zu Währungen, Steuern und Steuersätzen.
Er definiert, in welcher Währung Preise ausgegeben und formatiert werden, ob Preise inklusive oder exklusive Steuer geführt sind und nach welcher Berechnungslogik die Steuer ermittelt wird.
Zudem werden hier die Steuersätze (z. B. nach Land/Region oder Kategorie) festgelegt sowie optionale Zuschläge wie Pfand oder Abgaben konfiguriert.

`finance*` - Grundstruktur

Nachfolgend der Grundaufbau des Knotens finance

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

Parameterbeschreibung

Parameter	Beschreibung
`currency`	Definiert die Währungs- und Formatierungseinstellungen des Shops. Hier werden Code (z. B. „EUR“), Symbol, Dezimalstellen und Trennzeichen angegeben. Werte in Textform oder numerisch.
`taxes`	Steuert die grundlegende Steuerlogik des Shops. Enthält Parameter wie Preisbasis (`gross` / `net`), Anzeigeart (`pricesIncludeTaxes` = true/false) und Versandsteuer (`shippingTaxDeductible` = true/false). Werte als Schlüssel-Wert-Paare.
`taxRates`	Enthält die länderspezifischen Steuersätze in Listenform. Jeder Eintrag enthält eine ID (z. B. „standard“), den Prozentsatz (`rate`) und optionale Zuordnungen (`appliesTo`). Struktur: Objekt mit Länderkennzeichen als Schlüssel, Array als Wert.
`taxRatesAddition`	Optionale Zusatzsteuern oder Abgaben (z. B. Pfand). Aufbau analog zu `taxRates`, meist mit Feldern wie `type` („fixed_per_unit“ / „percent“), `value` (Zahl) und `appliesTo` (Liste von Artikelgruppen).
`exchangeRates`	Steuert das Verhalten des automatischen Wechselkursabrufs. Definiert Abrufzeitpunkt, Wartezeit und Umgang mit veralteten oder nicht verfügbaren Kursen.
`shopRent`	Konfiguriert den Abrechnungszeitpunkt der Shop-Miete. Enthält die Stichzeit am Monatsersten sowie Verweise auf die zugehörigen Preisstaffelungen.
`shopRentTier`	Definiert einzelne Preisstaffelungen für die Shop-Miete mit Tarif, Volumenobergrenze und monatlicher Grundgebühr.

`finance.currency` - Währungen

Im Abschnitt currency werden eine oder mehrere Währungen definiert, die im Shop verfügbar sein sollen. Jede Währung wird als eigener Unterknoten angelegt und enthält Formatierungsregeln und ISO-Angaben. Über diese Definitionen werden Symbol, Schreibweise und Trennzeichen festgelegt, die später im Frontend bei der Preisdarstellung verwendet werden. Die Zuordnung, welche Währung ein Subshop tatsächlich verwendet, erfolgt in der Subshop-Konfiguration

Beispielkonfiguration für EURO (`finance.currency.euro`)

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

Beispielkonfiguration für BRITISCH PFUND (`finance.currency.britishpound`)

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

Parameterbeschreibung

Parameter	Typ	Beschreibung
`decimalPlaces`	int	Anzahl der Nachkommastellen, die für Preise angezeigt werden (z. B. 2 → „19,99 €“).
`decimalSeparator`	string	Zeichen zur Trennung von Ganz- und Nachkommastellen (z. B. `","` oder `"."`).
`thousandsSeparator`	string	Zeichen zur Trennung von Tausendern (z. B. `"."` oder `","`).
`symbol`	string	Währungssymbol, das im Shop angezeigt wird (z. B. `"€"`, `"£"`, `"$"`).
`symbolPosition`	enum	Position des Symbols relativ zum Betrag. Mögliche Werte: `left` (z. B. „£19.99“) oder `right` (z. B. „19,99 €“).
`isoCode`	string	Dreistelliger ISO-4217-Code der Währung (z. B. `"EUR"`, `"GBP"`, `"CHF"`). Wird systemintern zur Identifikation verwendet.
`isoNum`	string	Numerischer ISO-4217-Code der Währung (z. B. `978` = Euro, `826` = Pfund). Wird für internationale Prozesse und API-Kommunikation genutzt.

`finance.taxRates` - Steuersätze

Im Abschnitt taxRates werden die konkreten Mehrwertsteuersätze pro Land oder Region definiert.
Jeder Eintrag entspricht einem Land (z. B. de, en, at) und enthält eine Liste von steuerlichen Raten, die vom System für die Preisberechnung verwendet werden können. Diese Definitionen sind global verfügbar und werden in der Regel über finance.taxes.defaultTaxRate oder in der jeweiligen Subshop-Konfiguration referenziert.

Beispielkonfiguration für deutsche Steuersätze (`finance.taxRates.de`)

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

Beispielkonfiguration für englische Steuersätze (`finance.taxRates.en`)

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

Parameterbeschreibung

Parameter	Typ	Beschreibung
`id`	string	Interner Bezeichner für die Steuerdefinition des Landes. Wird meist identisch zum Ländercode geführt.
`defaultTaxRate`	string	Standard-Steuersatz-ID, die verwendet wird, wenn kein spezifischer Satz zugeordnet ist (z. B. `"19"`).
`taxRates`	list (object)	Liste aller verfügbaren Steuersätze für dieses Land. Jeder Eintrag enthält eine eindeutige ID und den prozentualen Satz als Dezimalwert.
`id`	string	Bezeichner des Steuersatzes (z. B. `"19"`, `"7"`, `"zero"`). Dient als Referenz innerhalb des Systems.
`rate`	float	Steuerwert als Dezimalzahl, nicht als Prozentangabe (z. B. `0.19` = 19 %). Wird für die Preisberechnung verwendet.

`finance.taxRatesAddition` - Zusatzsteuersätze

Im Abschnitt taxRatesAddition können zusätzliche steuerliche Aufschläge definiert werden, die ergänzend zu den regulären Mehrwertsteuersätzen gelten. Dies kann z. B. für Pfandbeträge, Umweltabgaben oder Sondersteuern genutzt werden. Jede Landesdefinition verweist dabei auf die bestehenden Steuersätze (finance.taxRates.<land>) und ergänzt diese um einen oder mehrere zusätzliche Sätze.

Beispielkonfiguration für deutsche Zuatzsteuersätze (`finance.taxRatesAddition.de`)

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

Beispielkonfiguration für englische Zuatzsteuersätze (`finance.taxRatesAddition.en`)

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

Parameterbeschreibung

Parameter	Typ	Beschreibung
`id`	string	Bezeichner der Steuerdefinition des Landes, meist identisch mit dem Ländercode.
`taxRates`	singleAssoc	Referenz auf die regulären Steuersätze, auf denen die Zusatzsteuern aufbauen (z. B. `"finance.taxRates.de"`).
`additionalTaxRates`	list (object)	Liste zusätzlicher Steuersätze, die zusätzlich zu den regulären angewendet werden können.
`id`	string	Eindeutiger Bezeichner der Zusatzsteuer (z. B. `"30"`, `"luxury"`, `"environment"`).
`rate`	float	Steuer- oder Aufschlagswert als Dezimalzahl (z. B. `0.10` = 10 %). Wird zusätzlich zum regulären Satz berechnet.

`finance.taxes` - Steuerberechnung

Der Abschnitt finance.taxes definiert die Berechnungslogik und die Zuweisung der Steuersätze, die im jeweiligen Shop oder Subshop verwendet werden. Hier wird festgelegt,

ob Preise inklusive oder exklusive Steuer geführt werden,
welche Steuersätze aus der Konfiguration finance.taxRates verwendet werden,
und wie Haupt- und Nebenleistungen (z. B. Produkte, Versand) steuerlich berechnet werden.
ob die MwSt. für Versandkosten, Zahlungsartenkosten und Mindermengenzuschläge abziehbar ist.
nach welchem Modus eine länderbasierte Steuerbefreiung greift.

Damit bildet dieser Abschnitt die Verknüpfung zwischen den definierten Steuersätzen (finance.taxRates) und der praktischen Anwendung für den Subshop.

Beispielkonfiguration

{
  "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"
}

Parameterbeschreibung

Property	Typ	Beschreibung
`pricesIncludeTaxes`	bool	Legt fest, ob Produktpreise inklusive Steuer (true) oder exklusive Steuer (false) geführt werden.
`defaultTaxRate`	singleAssoc	Referenz auf die Standard-Steuersatzdefinition. Typischerweise verweist dieser Eintrag auf einen Knoten unter `finance.taxRates` (z. B. `finance.taxRates.de`).
`usedTaxes`	singleAssoc	Gibt an, welche Steuersätze aus der `taxRates`-Konfiguration aktiv im Shop verwendet werden sollen. Kann ein oder mehrere Verweise enthalten.
`mainServicesCalculation`	enum	Definiert die steuerliche Berechnungsmethode. Beispielwerte: `horizontal` (Berechnung je Position) oder `vertical` (Berechnung auf Gesamtbetrag).
`ancillaryServicesCalculation`	enum	Definiert die Berechnungslogik für Nebenleistungen (z. B. Versand). Mögliche Werte: - `static` - fester Steuersatz - `distributed` - anteilig zur Warensteuer - `highestCost`- Steuersatz mit dem höchsten Warenwert
`ancillaryServicesTaxRate`	string	Fester Prozentsatz für Nebenleistungen (z. B. Versandkostensteuer = „19“). Wird nur verwendet, wenn `ancillaryServicesCalculation = "static"` ist.
`shippingTaxDeductible`	bool	Legt fest, ob die Mehrwertsteuer für Versandkosten abziehbar ist (`true`) oder nicht (`false`).
`paymentTaxDeductible`	bool	Legt fest, ob die Mehrwertsteuer für Zahlungsartenkosten abziehbar ist (`true`) oder nicht (`false`).
`surchargeTaxDeductible`	bool	Legt fest, ob die Mehrwertsteuer für den Mindermengenzuschlag abziehbar ist (`true`) oder nicht (`false`).
`countryTaxMode`	enum	Steuert den Modus der länderbasierten Steuerbefreiung. Mögliche Werte: - `taxableList` - nur Länder in der Liste sind steuerpflichtig (alle anderen befreit) - `exemptList` - nur Länder in der Liste sind steuerbefreit - `disabled` - Feature deaktiviert. Default: `disabled`
`countryList`	multiAssoc -> `general.country`	Liste der Länder, auf die der gewählte `countryTaxMode` angewendet wird.
`countryTaxAddressMatching`	enum	Bestimmt, ob nur die Lieferadresse oder Liefer- und Rechnungsadresse für die Steuerprüfung herangezogen werden. Mögliche Werte: - `shippingOnly`- nur Lieferadresse wird geprüft. - `shippingAndBilling` - beide Adresse müssen (je nach Modus) die Bedingung erfüllen. Default: `shippingOnly`

`finance.exchangeRates` - Wechselkursabruf

Der Abschnitt exchangeRates definiert die Konfiguration des automatischen Wechselkursabrufs. Hier wird festgelegt,

zu welchem Zeitpunkt die EZB-Tageskurse veröffentlicht werden,
wie lange nach der Veröffentlichung gewartet wird, bevor der Abruf erfolgt,
und wie das System mit veralteten oder nicht verfügbaren Kursen umgeht.

Beispielkonfiguration

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

Parameterbeschreibung

Property	Typ	Beschreibung
`ecbRefreshTimeCET`	string	Zeitpunkt (MEZ), zu dem die EZB Tageskurse veröffentlicht. Default: `“16:00”`
`fetchDelayMinutes`	int	Minuten Wartezeit nach Aktualisierungszeit vor dem Abruf. Default: `30`
`enforceRateRecency`	bool	Kurse ablehnen, die älter als `maxRateAgeDays` sind. Default: `true`
`maxRateAgeDays`	int	Maximal zulässiges Alter eines Kurses in Tagen. Default: `7`
`fallbackToPreviousRate`	bool	Älteren Kurs verwenden, wenn aktueller nicht verfügbar. Default: `true`

`finance.shopRent` - Abrechnungszeitpunkt

Im Abschnitt shopRent wir der Abrechnungszeitpunkt für die Shop-Miete konfiguriert. Hier wird definiert,

zu welcher Uhrzeit am Monatsersten der Abrechnungszeitraum endet,
und welche Preisstaffelungen (shopRentTier) für die Abrechnung herangezogen werden.

Beispielkonfiguration

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

Parameterbeschreibung

Property	Typ	Beschreibung
`cutoffCET`	string	MEZ-Stichzeit am 1. des Monats, zu der der Abrechnungszeitraum endet.
`tiers`	multiAssoc → shopRentTier	Verweise auf die Preisstaffelungsdefinitionen, die für die Abrechnung verwendet werden.

`finance.shopRentTier` - Preisstaffelungen

Im Abschnitt shopRentTier werden die einzelnen Preisstaffelungen für die Shop-Miete definiert. Jede Stufe legt einen prozentualen Tarif, eine Volumenobergrenze sowie eine feste monatliche Gebühr fest. Die Zuordnung der aktiven Stufen erfolgt über finance.shopRent. Beispielkonfiguration für die Stufe “Starter” (finance.shopRentTier.starter)

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

Beispielkonfiguration für die Stufe “Professional” (finance.shopRentTier.professional)

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

Parameterbeschreibung

Property	Typ	Beschreibung
`name`	string (unique)	Eindeutige Stufenbezeichnung (z.B. “Starter”, “Professional”). Dient als Referenz innerhalb des Systems.
`rate`	float	Prozentualer Tarif für die Mietberechnung als Dezimalwert (z.B. 0.02 = 2%).
`maxTransactionVolume`	int	EUR-Volumenobergrenze für diese Stufe. Bei Überschreitung greift die nächste Staffel.
`monthsFee`	float	Feste monatliche Grundgebühr in EUR, unabhängig vom Transaktionsvolumen.

Konfiguration

Documentation Index

​finance* - Grundstruktur

​Parameterbeschreibung

​finance.currency - Währungen

​Beispielkonfiguration für EURO (finance.currency.euro)

​Beispielkonfiguration für BRITISCH PFUND (finance.currency.britishpound)

​Parameterbeschreibung

​finance.taxRates - Steuersätze

​Beispielkonfiguration für deutsche Steuersätze (finance.taxRates.de)

​Beispielkonfiguration für englische Steuersätze (finance.taxRates.en)

​Parameterbeschreibung

​finance.taxRatesAddition - Zusatzsteuersätze

​Beispielkonfiguration für deutsche Zuatzsteuersätze (finance.taxRatesAddition.de)

​Beispielkonfiguration für englische Zuatzsteuersätze (finance.taxRatesAddition.en)

​Parameterbeschreibung

​finance.taxes - Steuerberechnung

​Beispielkonfiguration

​Parameterbeschreibung

​finance.exchangeRates - Wechselkursabruf

​finance.shopRent - Abrechnungszeitpunkt

​finance.shopRentTier - Preisstaffelungen

`finance*` - Grundstruktur

Parameterbeschreibung

`finance.currency` - Währungen

Beispielkonfiguration für EURO (`finance.currency.euro`)

Beispielkonfiguration für BRITISCH PFUND (`finance.currency.britishpound`)

Parameterbeschreibung

`finance.taxRates` - Steuersätze

Beispielkonfiguration für deutsche Steuersätze (`finance.taxRates.de`)

Beispielkonfiguration für englische Steuersätze (`finance.taxRates.en`)

Parameterbeschreibung

`finance.taxRatesAddition` - Zusatzsteuersätze

Beispielkonfiguration für deutsche Zuatzsteuersätze (`finance.taxRatesAddition.de`)

Beispielkonfiguration für englische Zuatzsteuersätze (`finance.taxRatesAddition.en`)

Parameterbeschreibung

`finance.taxes` - Steuerberechnung

Beispielkonfiguration

Parameterbeschreibung

`finance.exchangeRates` - Wechselkursabruf

`finance.shopRent` - Abrechnungszeitpunkt

`finance.shopRentTier` - Preisstaffelungen