finance - Währungen & Steuern

Der finance-Knoten bündelt shopweite Einstellungen zu Währungen, Preisformatierung, Brutto-/Netto-Logik, Steuersätzen sowie Zuschlägen wie Pfand und Abgaben.

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 Zusatzsteuersätze (finance.taxRatesAddition.de)

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

​

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

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

​

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 wird 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.