Steuerregeln und Steuerklassen für mehrere Länder korrekt konfigurieren

1. Steuerklassen: Product Tax Class und Customer Tax Class

Das Magento_Tax Modul basiert auf zwei unabhängigen Klassifizierungsdimensionen, die zusammen erst eine Steuerberechnung ergeben. Die Product Tax Class ist ein Produktattribut (tax_class_id) und wird pro Artikel vergeben, typischerweise "Taxable Goods" für reguläre Ware oder "None" für steuerbefreite Artikel wie Gutscheine. Die Customer Tax Class hängt am Kundengruppen-Datensatz und wird in den Kundengruppen unter Stores > Other Settings > Customer Groups gepflegt, wo jede Gruppe, etwa "General", "Retailer" oder eine eigene B2B-Gruppe, einer Steuerklasse zugeordnet wird. Beide Steuerklassen selbst besitzen in Magento 2 kein eigenes Admin-Grid, sondern werden über den Dropdown "Add New Tax Class" direkt im Formular einer Steuerregel unter Stores > Taxes > Tax Rules angelegt.

Diese Trennung erlaubt es, dieselbe Steuerregel für unterschiedliche Kombinationen aus Kunde und Produkt zu verwenden, ohne für jede Kombination eine eigene Preislogik zu programmieren. Für Multi-Country-Setups ist das entscheidend: Ein Produkt kann in Deutschland als "Taxable Goods" behandelt werden, während dieselbe Product Tax Class in einer Steuerregel für Schweizer Kunden über eine andere Customer Tax Class auf einen abweichenden Satz oder auf 0 Prozent bei Reverse-Charge gemappt wird. Wer die Steuerklassen nicht sauber trennt und stattdessen versucht, länderspezifische Sonderfälle über zusätzliche Produktattribute zu lösen, verliert genau die Flexibilität, die die Kombination aus Product Tax Class und Customer Tax Class in den Steuerregeln eigentlich bietet.

2. Tax Zones and Rates: Steuersätze pro Land pflegen

Unter Stores > Taxes > Tax Zones and Rates verwaltet Magento die eigentlichen Steuersätze als eigenständige Entitäten, unabhängig von den Steuerregeln, die sie später referenzieren. Jeder Tax Rate besteht aus ISO-Ländercode, optionalem Bundesland oder Region, einem Postleitzahlen-Muster oder -Bereich, einem Rate Code als eindeutigem Bezeichner und dem eigentlichen Prozentsatz. Für ein Multi-Country-Setup mit Deutschland, Österreich, Frankreich, der Schweiz und weiteren EU-Ländern braucht jedes Zielland mindestens einen eigenen Tax Rate Datensatz, da die Mehrwertsteuersätze innerhalb der EU stark variieren: 19 Prozent in Deutschland, 20 Prozent in Österreich und Frankreich, 23 Prozent in Polen, während die Schweiz mit 8,1 Prozent Normalsatz außerhalb der EU-Mehrwertsteuerlogik steht.

Seit der EU-One-Stop-Shop-Reform ist die Destination-Country-Logik für B2C-Fernverkäufe verbindlich: Der Steuersatz richtet sich nach dem Land der Lieferadresse, nicht nach dem Sitzland des Händlers. Das bedeutet in der Tax-Konfiguration, dass für jedes EU-Zielland ein eigener Tax Rate mit dem dortigen Satz angelegt werden muss, verknüpft über die passende Steuerregel mit der Standard-Customer-Tax-Class. Für den Import vieler Tax Rates auf einmal bietet der Admin-Bereich Stores > Taxes > Import/Export Tax Rates eine CSV-Schnittstelle mit den Spalten Code, Country, State, Zip/Postal Code, Rate, Zip From und Zip To, über die sich Sätze für ein ganzes EU-Rollout in einem Rutsch importieren lassen.

3. Steuerregeln: Customer Tax Class, Product Tax Class und Rate kombinieren

Eine Steuerregel (Tax Rule) ist die Klammer, die Customer Tax Class, Product Tax Class und Tax Rate zu einer anwendbaren Steuerberechnung verbindet. Jede Steuerregel referenziert dabei nicht nur je eine, sondern potenziell mehrere Customer Tax Classes, mehrere Product Tax Classes und mehrere Tax Rates gleichzeitig. Magento bildet daraus intern das Kreuzprodukt und sucht bei der Berechnung für eine konkrete Kombination aus aktueller Kundengruppe, Produkt und Lieferadresse den passenden Treffer. Diese Architektur macht Steuerregeln kompakt, weil eine einzige Regel mehrere Länder oder mehrere Kundengruppen gleichzeitig abdecken kann, solange die zugrunde liegende Rate für jede Kombination korrekt hinterlegt ist.

Zwei weitere Felder jeder Steuerregel sind für Multi-Country-Setups besonders relevant: die Priority und die Reihenfolge der Berechnung. Regeln mit derselben Priorität werden addiert, ihre Sätze also summiert, während Regeln mit unterschiedlicher Priorität kaskadierend angewendet werden, jede weitere Regel rechnet auf dem bereits versteuerten Zwischenbetrag der vorherigen Regel. Das ist etwa in Kanada mit GST und PST üblich, aber für europäische Steuerregeln in der Regel nicht gewünscht, weshalb alle EU-Sätze standardmäßig dieselbe Priorität erhalten sollten, sofern nicht bewusst kaskadierende Steuerregeln, etwa für eine kombinierte Verbrauchssteuer, benötigt werden.

4. Berechnungseinstellungen: Preisanzeige in Katalog, Cart und Checkout

Unter Stores > Configuration > Sales > Tax > Calculation Settings legt "Tax Calculation Based On" fest, ob für die Steuerregel-Auswertung die Lieferadresse, die Rechnungsadresse oder die Shop-Herkunftsadresse herangezogen wird. Für grenzüberschreitende Multi-Country-Shops ist "Shipping Address" die praxisrelevante Wahl, weil sie der Destination-Country-Logik der EU entspricht. Getrennt davon steuert "Catalog Prices" ob hinterlegte Produktpreise als Netto- oder Bruttopreise interpretiert werden, während "Display Product Prices In Catalog" unabhängig davon regelt, ob im Frontend brutto, netto oder beides angezeigt wird.

Für Cart und Checkout existieren dieselben Anzeige-Optionen noch einmal separat unter "Shopping Cart Display Settings" und "Orders, Invoices, Credit Memos Display Settings", jeweils mit eigenen Feldern für Preis, Subtotal, Versandkosten und den ausgewiesenen Steuerbetrag selbst. In einem Shop, der gleichzeitig B2C-Kunden mit Bruttopreisen in Deutschland und B2B-Kunden mit Nettopreisen in einem anderen EU-Land bedient, führt eine falsche Kombination dieser Einstellungen zu Preisen, die zwar technisch korrekt aus den Steuerregeln berechnet werden, aber an der falschen Stelle im Checkout inklusive oder exklusive Steuer ausgewiesen werden. Diese Anzeige-Logik ist von der eigentlichen Steuerberechnung getrennt zu betrachten: Die Steuerregeln liefern den korrekten Betrag, die Display-Settings entscheiden nur, wie er dargestellt wird.

5. EU B2B Reverse-Charge: VAT-ID-Validierung und Kundengruppen

Für grenzüberschreitende B2B-Geschäfte innerhalb der EU greift das Reverse-Charge-Verfahren: Der liefernde Händler stellt ohne Umsatzsteuer in Rechnung, der Empfänger führt die Steuer im eigenen Land ab. Magento bildet diesen Fall über die integrierte VAT-ID-Validierung in Magento_Customer ab, konfigurierbar unter Stores > Configuration > Customers > Customer Configuration > Create New Account Options. Trägt ein Kunde eine USt-IdNr. in der Adresse ein und klickt auf "Validate VAT Number", ruft Magento den VIES-Webservice der EU-Kommission auf und erhält als Ergebnis, ob die Nummer gültig ist und ob Händler- und Kundenland identisch sind.

Ist "Enable Automatic Assignment of Customer Group" aktiviert, weist Magento den Kunden automatisch einer von vier konfigurierbaren Gruppen zu: Domestic für eine gültige USt-IdNr. im selben Land wie der Shop, Intra-Union für eine gültige USt-IdNr. in einem anderen EU-Land, Invalid für eine erkennbar ungültige Nummer und einen Error-Fallback, falls der VIES-Dienst nicht erreichbar war. In der Tax-Konfiguration wird dann typischerweise eine eigene Customer Tax Class für die Intra-Union-Gruppe angelegt und über eine dedizierte Steuerregel mit einem Tax Rate von 0 Prozent verknüpft. Wichtig für den Betrieb: Die Gruppenzuweisung erfolgt nur beim expliziten Validierungs-Klick oder beim erneuten Speichern der Adresse, nicht rückwirkend automatisch für Bestandskunden, deren USt-IdNr. sich nachträglich ändert oder ungültig wird.

<?php

declare(strict_types=1);

namespace Mironsoft\Tax\Plugin\Customer;

use Magento\Customer\Model\Vat;
use Psr\Log\LoggerInterface;

/**
 * Plugin to add custom domestic-treatment logic for VAT-ID validation results.
 * Some non-EU countries with special customs union agreements (e.g. Monaco with France)
 * need to be treated as domestic even though checkVatNumber() reports them as foreign.
 */
class VatNumberValidationPlugin
{
    /**
     * @param LoggerInterface $logger Logger for auditing VAT validation decisions
     */
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {
    }

    /**
     * Overrides the "isCountryInEU" style result for special customs union countries.
     *
     * @param Vat $subject The core VAT validation model
     * @param \Magento\Framework\DataObject $result Result of checkVatNumber()
     * @param string $countryCode ISO country code of the customer
     * @param string $vatNumber The VAT identification number submitted
     * @return \Magento\Framework\DataObject Modified validation result
     */
    public function afterCheckVatNumber(
        Vat $subject,
        \Magento\Framework\DataObject $result,
        string $countryCode,
        string $vatNumber,
    ): \Magento\Framework\DataObject {
        if ($countryCode === 'MC' && $result->getIsValid()) {
            $result->setIsCountryInEU(true);
            $this->logger->info(sprintf('Treated MC VAT-ID %s as domestic per customs union', $vatNumber));
        }

        return $result;
    }
}

6. Steuerregeln programmatisch anlegen: TaxRuleRepository und TaxRateRepository

Für den Rollout neuer Länder oder Store Views ist das manuelle Anlegen von Tax Rates und Steuerregeln über den Admin-Bereich fehleranfällig und schlecht wiederholbar. Die Service Contracts Magento\Tax\Api\TaxRateRepositoryInterface und Magento\Tax\Api\TaxRuleRepositoryInterface erlauben es, dieselbe Tax-Konfiguration deklarativ über einen Data Patch oder ein CLI-Kommando zu provisionieren, wodurch neue Umgebungen reproduzierbar denselben Satz an Steuerregeln erhalten. Die Datenobjekte TaxRateInterface und TaxRuleInterface werden über ihre jeweiligen Factories erzeugt und anschließend über save() persistiert, wobei ein Tax Rule erst gespeichert werden kann, nachdem die referenzierten Tax Rate IDs bereits existieren.

Diese Vorgehensweise ist besonders wertvoll in CI/CD-Pipelines, in denen Staging- und Produktionsumgebungen dieselbe Tax-Konfiguration erhalten sollen, ohne dass ein Mensch die Werte manuell im Admin-Bereich nachpflegt. Ein Data Patch, der Steuerregeln über die Repositories anlegt, ist zudem idempotent gestaltbar, indem vor dem Anlegen über getList() mit einem SearchCriteria-Filter auf den Rate Code geprüft wird, ob der entsprechende Datensatz bereits existiert.

<?php

declare(strict_types=1);

namespace Mironsoft\Tax\Setup\Patch\Data;

use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Tax\Api\Data\TaxRateInterfaceFactory;
use Magento\Tax\Api\Data\TaxRuleInterfaceFactory;
use Magento\Tax\Api\TaxRateRepositoryInterface;
use Magento\Tax\Api\TaxRuleRepositoryInterface;

/**
 * Data patch to provision EU multi-country tax rates and a matching tax rule.
 * Ensures new environments reproduce the same tax configuration without manual admin steps.
 */
class ProvisionEuTaxRates implements DataPatchInterface
{
    /**
     * @param TaxRateRepositoryInterface $taxRateRepository Repository to persist tax rates
     * @param TaxRateInterfaceFactory $taxRateFactory Factory creating TaxRateInterface instances
     * @param TaxRuleRepositoryInterface $taxRuleRepository Repository to persist tax rules
     * @param TaxRuleInterfaceFactory $taxRuleFactory Factory creating TaxRuleInterface instances
     */
    public function __construct(
        private readonly TaxRateRepositoryInterface $taxRateRepository,
        private readonly TaxRateInterfaceFactory $taxRateFactory,
        private readonly TaxRuleRepositoryInterface $taxRuleRepository,
        private readonly TaxRuleInterfaceFactory $taxRuleFactory,
    ) {
    }

    /**
     * Creates tax rates for Germany, Austria and France, then links them via one tax rule.
     *
     * @return static
     */
    public function apply(): static
    {
        $rateIds = [];

        foreach ([
            ['code' => 'DE-VAT-19', 'country' => 'DE', 'rate' => 19.0000],
            ['code' => 'AT-VAT-20', 'country' => 'AT', 'rate' => 20.0000],
            ['code' => 'FR-VAT-20', 'country' => 'FR', 'rate' => 20.0000],
        ] as $rateData) {
            $rate = $this->taxRateFactory->create();
            $rate->setCode($rateData['code']);
            $rate->setTaxCountryId($rateData['country']);
            $rate->setRate($rateData['rate']);
            $saved = $this->taxRateRepository->save($rate);
            $rateIds[] = $saved->getId();
        }

        $rule = $this->taxRuleFactory->create();
        $rule->setCode('EU-Standard-Rule');
        $rule->setPriority(0);
        $rule->setPosition(0);
        $rule->setCustomerTaxClassIds([3]);
        $rule->setProductTaxClassIds([2]);
        $rule->setTaxRateIds($rateIds);
        $this->taxRuleRepository->save($rule);

        return $this;
    }

    /**
     * @return array
     */
    public static function getDependencies(): array
    {
        return [];
    }

    /**
     * @return array
     */
    public function getAliases(): array
    {
        return [];
    }
}

7. Eigene Steuerberechnung: Plugin auf Magento\Tax\Model\Calculation

Wenn Standard-Steuerregeln für einen Sonderfall nicht ausreichen, etwa eine mengenabhängige Sonderbehandlung für Großlieferungen in ein bestimmtes Land, bieten sich zwei Wege an: eine Preference auf TaxCalculationInterface oder ein Plugin auf Magento\Tax\Model\Calculation. Eine Preference ersetzt die komplette Klasse und zwingt dazu, jede zukünftige Core-Änderung an der Originalklasse manuell nachzuziehen, zusätzlich verhindert sie, dass andere Module eigene Plugins auf dieselbe Methode registrieren können, ohne dass diese ins Leere laufen. Ein Plugin dagegen hakt sich gezielt in eine einzelne Methode wie getRate() ein, bleibt mit Core-Updates kompatibel und lässt sich über sortOrder sauber mit Plugins anderer Erweiterungen koordinieren.

In der Praxis ist die Preference-Variante nur dann gerechtfertigt, wenn die komplette Berechnungslogik grundsätzlich anders arbeiten soll als die Core-Implementierung, etwa bei Anbindung eines externen Steuerdienstes wie Avalara oder Vertex, der die komplette Rate-Ermittlung übernimmt. Für punktuelle Anpassungen an bestehenden Steuerregeln, wie im folgenden Beispiel eine Sonderregel für eine bestimmte Kombination aus Ländercode und Produktklasse, ist ein Plugin die robustere und wartbarere Lösung.

<?php

declare(strict_types=1);

namespace Mironsoft\Tax\Plugin\Model;

use Magento\Tax\Model\Calculation;
use Psr\Log\LoggerInterface;

/**
 * Plugin adding a custom rate override for a specific country and product tax class
 * combination that the standard tax rule matrix cannot express directly.
 */
class CalculationRatePlugin
{
    /**
     * @param LoggerInterface $logger Logger used for auditing rate overrides
     */
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {
    }

    /**
     * Applies a reduced rate for cross-border bulk shipments into Switzerland
     * when the request carries the custom "bulk_shipment" flag.
     *
     * @param Calculation $subject The core tax calculation model
     * @param float $result Rate computed by the core implementation
     * @param \Magento\Framework\DataObject $request Rate lookup request object
     * @return float Possibly overridden tax rate
     */
    public function afterGetRate(
        Calculation $subject,
        float $result,
        \Magento\Framework\DataObject $request,
    ): float {
        if ($request->getCountryId() === 'CH' && $request->getData('bulk_shipment')) {
            $this->logger->info(sprintf('Overriding CH rate %.4f with reduced bulk rate', $result));
            return 2.6000;
        }

        return $result;
    }
}

<?xml version="1.0"?>
<!-- File: app/code/Mironsoft/Tax/etc/di.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Tax\Model\Calculation">
        <plugin name="Mironsoft_Tax::calculation_rate_plugin"
                type="Mironsoft\Tax\Plugin\Model\CalculationRatePlugin"
                sortOrder="10" />
    </type>
</config>

8. Fixed Product Tax (WEEE) und Performance bei vielen Steuerregeln

Neben den prozentualen Steuersätzen kennt Magento über das Magento_Weee Modul die Fixed Product Tax, in einigen EU-Ländern als WEEE-Gebühr für Elektrogeräte oder Batterien bekannt. FPT ist ein fixer Betrag pro Einheit, unabhängig vom Warenwert, konfiguriert über ein eigenes Produktattribut je Land unter Stores > Configuration > Sales > Tax > Fixed Product Taxes und im Frontend separat neben dem eigentlichen Steuerbetrag ausgewiesen. Für Multi-Country-Shops mit Elektronik-Sortiment ist wichtig, dass FPT pro Land unterschiedlich hinterlegt werden kann und unabhängig von den regulären Steuerregeln berechnet wird, in der Cart-Totals-Kollektion aber als eigener Posten neben der Umsatzsteuer erscheint.

Bei der Performance wächst der Suchraum für eine Steuerregel mit der Anzahl der Kombinationen aus Ländern, Regionen, Kundengruppen und Product Tax Classes. Shops mit zahlreichen Store Views und jeweils eigenen Steuerregeln pro Land sollten Wildcard-Werte für Region und Postleitzahl nutzen, wo dies rechtlich zulässig ist, statt für jede Postleitzahl einen eigenen Tax Rate anzulegen. Für die programmatische Abfrage vieler Steuerregeln ist TaxRuleRepositoryInterface::getList() mit einem auf die relevante Store-Zuordnung gefilterten SearchCriteria-Objekt effizienter als das Iterieren über sämtliche im System hinterlegten Steuerregeln, insbesondere wenn ein Custom-Modul zur Laufzeit auf Tax-Daten zugreift statt nur im Rahmen der Quote-Totals-Kollektion.

9. Typische Fallstricke bei Steuerregeln und Steuerklassen

Der häufigste Fehler ist eine falsch zugewiesene Product Tax Class. Bleibt ein Produkt versehentlich auf "Taxable Goods" stehen, obwohl es eigentlich steuerbefreit sein müsste, oder umgekehrt, gibt es dafür keine Fehlermeldung im Admin-Bereich: Der Preis wird einfach mit dem falschen Satz berechnet, und das fällt oft erst auf, wenn ein Kunde sich über den ausgewiesenen Betrag beschwert. Ebenso tückisch ist eine unbedacht geänderte Priorität bei mehreren Steuerregeln: Wird eine neue Regel mit derselben Priorität wie eine bestehende angelegt, werden beide Sätze addiert statt kaskadierend berechnet, was bestehende Preise für ein Land unerwartet erhöht, ohne dass im Code etwas verändert wurde.

Beim CSV-Import von Tax Rates ist die dritte häufige Fehlerquelle falsch angegebene Regionscodes. Für Länder wie die USA oder Kanada erwartet die State-Spalte den internen Region-Code aus der Magento-Regionstabelle, nicht den ISO-3166-2-Code direkt, während für die meisten EU-Länder ohne Bundesland-Bezug das Feld schlicht leer bleiben muss und nicht mit "0" oder einem Platzhalter gefüllt werden darf. Ein falsch gesetzter Regionscode führt dazu, dass die Steuerregel für die betroffene Adresse überhaupt keinen Treffer findet und der Kunde ohne jede Steuer im Checkout landet, ein Fehler, der bei Stichprobentests mit einer einzigen Testadresse leicht übersehen wird.

#!/usr/bin/env bash
# Create a new tax rate via the REST API instead of the CSV import screen,
# useful for scripted multi-country rollouts and CI validation.
set -euo pipefail

TOKEN=$(bin/magento admin:token 2>/dev/null || true)
BASE_URL="https://shop.example.com/rest/V1"

curl -s -X POST "${BASE_URL}/taxRates" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "rate": {
      "code": "PL-VAT-23",
      "tax_country_id": "PL",
      "tax_postcode": "*",
      "rate": 23.0000
    }
  }'

# Verify the newly created rate is retrievable by rate code before
# wiring it into a tax rule via the admin UI or a data patch.
curl -s -X GET "${BASE_URL}/taxRates/search?searchCriteria[filterGroups][0][filters][0][field]=code&searchCriteria[filterGroups][0][filters][0][value]=PL-VAT-23" \
  -H "Authorization: Bearer ${TOKEN}"

Steuersätze im Ländervergleich

Die folgende Übersicht zeigt, wie unterschiedlich Steuerregeln pro Land ausfallen müssen, sobald mehrere europäische Märkte gleichzeitig bedient werden.

Diese Tabelle macht deutlich, warum eine einzelne globale Steuerregel für einen Multi-Country-Shop fast nie ausreicht. Jedes Land benötigt einen eigenen Tax Rate, teils sogar mehrere Sätze für ermäßigte Warengruppen, und die Reverse-Charge-Fähigkeit hängt direkt von der EU-Mitgliedschaft ab. Steuerklassen und Steuerregeln müssen diese Unterschiede so abbilden, dass ein einziges Set an Product Tax Classes über alle Länder hinweg wiederverwendet werden kann, während die länderspezifischen Sätze allein über die Tax Rates variieren.

10. Zusammenfassung

Steuerregeln in Magento 2 kombinieren drei Bausteine: Product Tax Class und Customer Tax Class definieren, wer und was besteuert wird, Tax Rates definieren die konkreten Prozentsätze pro Land oder Region, und eine Steuerregel verknüpft beide mit einer Priorität, die bei mehreren gleichzeitig greifenden Regeln über Addition oder Kaskadierung entscheidet. Für EU-B2B-Geschäfte kommt die Reverse-Charge-Prüfung über VAT-ID-Validierung hinzu, für Elektronik-Sortimente die von regulären Steuersätzen unabhängige Fixed Product Tax.

Die größten Risiken liegen nicht in der Konfiguration selbst, sondern in stillen Fehlern: eine falsch zugewiesene Product Tax Class ohne Fehlermeldung, ein falscher Regionscode beim CSV-Import, der eine Adresse komplett steuerfrei lässt, und eine unbedacht doppelt vergebene Priorität, die Sätze addiert statt kaskadiert. Ein regelmäßiger Blick auf die programmatische Anlage über TaxRuleRepository und TaxRateRepository, kombiniert mit gezielten Testadressen pro Land, deckt diese Fehler zuverlässig auf, bevor sie im Checkout sichtbar werden.

11. FAQ: Steuerregeln in Magento 2