Händlerbund & Shopware 6: Integration und Best Practices 2026

Eine fehlerhafte Widerrufsbelehrung, ein nicht verlinktes Impressum oder fehlende AGB im Checkout können schnell zu teuren Abmahnungen führen. Für Online-Händler, die mit Shopware 6 arbeiten, ist die korrekte Einbindung von Rechtstexten keine optionale Maßnahme, sondern rechtliche Pflicht – gerade wenn die technische Umsetzung zusammen mit einer Shopware Agentur sauber geplant wird.

Der Händlerbund bietet als spezialisierter Rechtsdienstleister nicht nur aktuelle Rechtstexte, sondern auch einen automatischen Update-Service, rechtliche Beratung und Abmahnschutz. Shopware 6 ist eines der flexibelsten E-Commerce-Systeme auf dem Markt, bringt aber auch technische Komplexität mit: Sales Channels, CMS-Seiten, Rule Builder und Theme-Anpassungen müssen verstanden und korrekt konfiguriert werden.

Wer beide Systeme sauber verzahnt, schafft nicht nur Rechtssicherheit, sondern spart langfristig Zeit und Geld. Dieser Guide zeigt praxisnah, wie du den Händlerbund für Shopware 6 optimal nutzt, welche Konfigurationen relevant sind, wie du automatisierte Tests aufsetzt und wie du deinen Shop so aufstellst, dass Pflichtinhalte nicht nur vorhanden, sondern auch sichtbar, aktuell und wartbar eingebunden sind.

Technische Grundlagen: Entities und Datenbankstruktur in Shopware 6

Rechtstexte in Shopware 6 sind Teil eines komplexen Datenmodells. Für die Integration ist es wichtig, die relevanten Entities und deren Beziehungen zu verstehen.

SystemConfig und CMS-Seiten-Zuordnung

Die Rechtstext-Zuordnung erfolgt primär über die SystemConfig-Entity. Hier werden unter dem Namespace core.basicInformation die IDs der CMS-Seiten für Impressum, AGB, Widerruf, Datenschutz und Zahlungsversand hinterlegt. Die Konfiguration ist sales-channel-spezifisch, das heißt jeder Verkaufskanal kann eigene Zuordnungen haben.

Relevante Config-Keys ab Shopware 6.4:

• core.basicInformation.tosPage (AGB)
• core.basicInformation.revocationPage (Widerrufsbelehrung)
• core.basicInformation.privacyPage (Datenschutzerklärung)
• core.basicInformation.imprintPage (Impressum)
• core.basicInformation.shippingPaymentInfoPage (Versand und Zahlung)

Diese Konfiguration findest du im Admin unter: Einstellungen → Shop → Stammdaten (Shopware 6.4.x) beziehungsweise Einstellungen → Verkaufskanäle → Kanal auswählen → Stammdaten (ab Shopware 6.5.x). Die genaue Positionierung hat sich mit Version 6.5 geändert, da die Sales-Channel-spezifische Konfiguration stärker in den Fokus gerückt ist.

CMS-Seiten und Layout-Struktur

Die eigentlichen Rechtstexte werden als CMS-Seiten in der cms_page-Entity verwaltet. Jede Seite hat ein Layout (Standard: landingpage) und besteht aus Sections, Blocks und Slots. Für Rechtstexte reicht typischerweise ein einfaches Text-Layout aus einem Text-Block aus.

Wichtig: Die CMS-Seite muss aktiv sein (active = true) und einer Kategorie zugeordnet werden, damit sie im Frontend über die Navigation erreichbar ist.

Kategorie-Struktur und Footer-Navigation

Die Footer-Navigation wird über Kategorien aus der category-Entity gesteuert. Du erstellst eine Footer-Kategorie (Typ: link oder page), verlinkst die CMS-Seiten und ordnest die Kategorie dem jeweiligen Sales Channel zu (navigationCategoryId oder footerCategoryId im sales_channel-Entity). Achte auf die active- und visible-Flags sowie auf die afterCategoryId für die Sortierung.

Admin-Pfade in verschiedenen Shopware-Versionen

Die Admin-Benutzeroberfläche hat sich zwischen Shopware 6.4 und 6.5+ deutlich geändert. Hier die konkreten Pfade für die wichtigsten Konfigurationspunkte:

Shopware 6.4.x

• Rechtstext-Zuordnung: Einstellungen → Shop → Stammdaten → Rechtstext-Seiten
• CMS-Seiten: Inhalte → Erlebniswelten → Seite erstellen oder bearbeiten
• Kategorien: Kataloge → Kategorien → Footer-Kategorie erstellen
• Sales-Channel-Konfiguration: Einstellungen → Shop → Verkaufskanäle → Kanal wählen → Tab Stammdaten

Shopware 6.5.x und 6.6.x

• Rechtstext-Zuordnung: Einstellungen → Verkaufskanäle → Kanal auswählen → Stammdaten → Rechtstext-Seiten
• CMS-Seiten: Inhalte → Erlebniswelten → Seite erstellen oder bearbeiten
• Kategorien: Kataloge → Kategorien → Footer-Kategorie erstellen
• Sales-Channel-Konfiguration: Einstellungen → Verkaufskanäle → Kanal auswählen → Verschiedene Tabs (Stammdaten, Domains, etc.)

Der entscheidende Unterschied: Ab Version 6.5 ist die Konfiguration stärker sales-channel-zentriert. Du musst also für jeden Kanal einzeln prüfen und zuweisen. Bei Multi-Channel-Setups ist das fehleranfälliger, weshalb automatisierte Checks umso wichtiger sind.

Template-Anpassungen und Checkout-Integration

Für die korrekte Darstellung von Rechtstexten im Checkout sind mehrere Templates relevant. Hier die wichtigsten Dateien und deren Funktion:

Relevante Twig-Templates

• storefront/page/checkout/confirm/index.html.twig: Haupttemplate der Checkout-Confirm-Seite. Hier werden AGB-Checkbox, Widerrufshinweise und Datenschutzlinks dargestellt.
• storefront/component/checkout/confirm-tos.html.twig: AGB-Checkbox-Komponente. Überschreibe dieses Template, wenn du zusätzliche Checkboxen (zum Beispiel für digitale Produkte) einbauen musst.
• storefront/component/checkout/confirm-payment-shipping.html.twig: Zeigt Zahlungs- und Versandhinweise. Hier kannst du zusätzliche Rechtstextlinks platzieren.

Beispiel für Template-Override

Erstelle in deinem Custom-Theme unter src/Resources/views/storefront/component/checkout/confirm-tos.html.twig ein Override. Wichtig: Nach jedem Theme-Update dieses Override prüfen. Nutze Git-Diffs und automatisierte Template-Tests.

Flow Builder für Automatisierung

Ab Shopware 6.4.6 kannst du den Flow Builder nutzen, um Rechtstexte automatisiert in Bestellprozesse zu integrieren. Beispiel-Flow: Bei Trigger Bestellung abgeschlossen → Aktion E-Mail senden mit angehängtem Widerrufsformular als PDF. Alternativ: Beim Trigger Bestellung abgeschlossen → Aktion Tag hinzufügen für B2B-Kunden, um später Widerrufsseiten auszublenden. Wenn du tiefer einsteigen willst, lohnt sich ein Blick in den Flow Builder in Shopware 6, um typische Stolperfallen (Trigger, Conditions, Sequencing) sauber zu vermeiden.

Omnibus-Richtlinie: Preishistorie korrekt umsetzen

Die Omnibus-Richtlinie verlangt bei Preisermäßigungen die Angabe des niedrigsten Preises der letzten 30 Tage. Technisch wurde das in Shopware 6 sukzessive umgesetzt.

Versionsstand und Implementierung

• Shopware 6.4.13.0 bis 6.4.20.x: Erste Implementierung der Preishistorie. Neues Feld cheapest_price in der product-Entity, jedoch nur für Listenpreise und ohne automatische Historisierung.
• Shopware 6.5.0.0+: Erweiterte Implementierung mit automatischer Erfassung und Speicherung in der product_price-Entity. Einführung der regulation_price im product-Schema.
• Shopware 6.6.0.0+: Vollständige Preishistorie mit automatischer 30-Tage-Berechnung und API-Endpunkten zur Abfrage.

Im Admin findest du das Feld unter: Kataloge → Produkte → Produkt auswählen → Tab Preise → Regulierungspreis (30-Tage-Niedrigstpreis). Ab Shopware 6.5 wird dieser Wert automatisch berechnet, wenn du die Preishistorie aktiviert hast (Settings → Shop → Product → Enable price history).

API-Zugriff für komplexe Preismodelle

Für komplexe Preismodelle oder externe Systeme kannst du die Preishistorie über die Admin-API abfragen. So kannst du Custom-Logik für B2B-Preise oder Kundengruppen-spezifische Preishistorien bauen.

Automatisierte Tests und kontinuierliches Monitoring

Rechtssicherheit ist nur dann gegeben, wenn du kontinuierlich prüfst, ob alle Verlinkungen und Zuordnungen korrekt sind. Hier konkrete Ansätze für automatisierte Checks.

End-to-End-Tests für Checkout und Footer

Integriere Tests in deine CI/CD-Pipeline (zum Beispiel GitLab CI, GitHub Actions). Führe sie nach jedem Deployment und nach jedem Shopware- oder Theme-Update aus.

HTTP-Checks und Curl-Monitoring

Führe HTTP-Checks alle 15 Minuten via Cronjob aus und sende Alerts bei Fehlern (zum Beispiel via Slack-Webhook).

Cache-Invalidierung und Config-Prüfung

Nach Rechtstext-Updates musst du sicherstellen, dass der HTTP-Cache invalidiert wird. Nutze Shopware CLI: bin/console cache:clear und bin/console http:cache:warm:up. Für automatisierte Config-Prüfung kannst du ein Custom-Command schreiben, das die SystemConfig-Werte ausliest und gegen Soll-Werte prüft (Details und typische Ursachen findest du auch im Beitrag zu Shopware Cache löschen).

Multi-Sales-Channel-Setup: B2B, B2C und Headless

Bei mehreren Verkaufskanälen wird die Rechtstext-Verwaltung komplex. Hier die Herausforderungen und Lösungen.

B2B versus B2C: Widerrufsrecht und Rule Builder

B2B-Kunden haben kein Widerrufsrecht, wenn sie als Unternehmer handeln. Du musst die Widerrufsseite für B2B-Kundengruppen ausblenden. Nutze den Rule Builder: Erstelle eine Regel Kundengruppe ist B2B und verwende diese in einem CMS-Layout-Assignment oder in einer Twig-Condition. Alternativ: Erstelle separate Footer-Kategorien für B2B und B2C und weise sie den jeweiligen Sales Channels zu.

Headless und PWA-Integration

Bei Headless-Setups über Storefront-API oder Store-API musst du sicherstellen, dass die CMS-Seiten korrekt ausgeliefert werden. Prüfe, ob die Response die korrekten Sections, Blocks und Slots enthält und das Frontend diese korrekt rendert. Bei Nuxt oder Next.js: Baue einen Custom-Hook, der die Rechtstext-Links aus der Store-API lädt und im Footer rendert. Für die Grundlagen (inkl. typischer Limitierungen und Caching) ist ein tieferer Blick in die Shopware Storefront hilfreich.

Internationalisierung und Mehrsprachigkeit

Für jeden Sales Channel und jede Sprache musst du eigene CMS-Seiten anlegen. Nutze die translations-Association der cms_page-Entity, um Inhalte mehrsprachig zu pflegen. Prüfe in der Admin-UI unter Inhalte → Erlebniswelten → Seite → Tab Übersetzungen, ob alle Sprachen vollständig sind. Wichtig: Auch die SystemConfig-Zuordnung ist sales-channel-spezifisch, das heißt du musst für den englischen Sales Channel die englische CMS-Seiten-ID hinterlegen.

Plugin-Integration und sichere Update-Strategie

Das offizielle Händlerbund-Plugin für Shopware 6 automatisiert die Synchronisation der Rechtstexte. Es nutzt die Händlerbund-API und schreibt die Texte in CMS-Seiten. Hier die wichtigsten Punkte für eine sichere Integration.

Plugin-Installation und API-Konfiguration

Installiere das Plugin über den Shopware Store oder via Composer. Nach der Installation konfiguriere im Admin unter Einstellungen → System → Plugins → Händlerbund → Konfiguration deine API-Zugangsdaten (API-Key aus dem Händlerbund-Mitgliederbereich). Das Plugin legt dann automatisch CMS-Seiten an oder aktualisiert bestehende, je nach Konfiguration.

Kompatibilität und Versionsprüfung

Prüfe vor jedem Plugin-Update die Kompatibilitätsmatrix auf der Plugin-Detailseite im Shopware Store. Beispiel: Plugin-Version 2.3.x ist kompatibel mit Shopware 6.4.13+, Plugin-Version 3.0.x erfordert Shopware 6.5.0+.

Update-Prozess und Staging-Tests

Führe Plugin-Updates immer zuerst auf einem Staging-System durch. Prozess:

• Erstelle ein Backup der Datenbank und Files
• Aktualisiere das Plugin via Composer und Console
• Führe automatisierte Tests aus
• Prüfe die CMS-Seiten auf korrekte Inhalte (Diff-View via Git)
• Teste manuell alle Sales Channels, Sprachen, Checkout-Flows und Footer-Links
• Bei Problemen: Rollback via Composer und Datenbank-Restore

Plugin-Konflikte debuggen

Typische Konflikte: Theme-Overrides werden vom Plugin überschrieben, Custom-Checkboxen verschwinden, Footer-Links zeigen auf falsche Seiten. Debug-Strategie: Aktiviere Shopware-Debug-Modus (APP_ENV=dev in .env), checke Logs unter var/log/, nutze Profiler und Xdebug. Bei Template-Konflikten: Vergleiche Template-Hierarchie via bin/console debug:twig.

CI/CD-Integration und Deployment-Best-Practices

Für professionelle Shops ist eine automatisierte Deployment-Pipeline mit Rechtstext-Checks unerlässlich. Erweitere die Pipeline um Config-Checks, Cache-Invalidierung und automatische Rollbacks bei Testfehlern.

Performance-Optimierung: Cache-Strategien

Rechtstexte sind statische Inhalte und sollten aggressiv gecacht werden. Nutze Shopware HTTP-Cache und CDN:

• HTTP-Cache-TTL: Setze für CMS-Seiten eine hohe Cache-Lifetime (zum Beispiel 3600 Sekunden). Konfiguration in config/packages/shopware.yaml unter shopware.http_cache.default_ttl.
• CDN-Integration: Nutze Cloudflare, Fastly oder AWS CloudFront. Konfiguriere Cache-Rules für URLs mit /impressum, /datenschutz, /agb mit hoher TTL und automatischer Invalidierung via Webhook bei CMS-Updates.
• Reverse-Proxy-Setup: Wenn du Varnish oder nginx als Reverse-Proxy nutzt, konfiguriere VCL-Rules für aggressive Caching von Rechtstextseiten.

Wichtig: Nach Rechtstext-Updates muss der Cache invalidiert werden. Nutze Shopware CLI oder API-Endpoints.

Häufige Fehlerbilder und Lösungsstrategien

Selbst bei sorgfältiger Umsetzung können Fehler auftreten. Hier die häufigsten und wie du sie behebst:

Seite existiert, aber Checkout verlinkt falsch

Problem: SystemConfig-Zuordnung fehlt oder ist nicht gespeichert. Debug: Prüfe system_config-Tabelle in der Datenbank. Falls leer oder falsche Werte: Setze via Admin oder direkt via SQL.

Footer-Link fehlt nach Theme-Update

Problem: Kategorie ist nicht aktiv oder nicht dem Sales Channel zugeordnet. Debug: Prüfe category-Tabelle und category_translation für Übersetzungen. Prüfe sales_channel-Tabelle: footer_category_id. Falls falsch: Korrigiere via Admin oder SQL.

B2B sieht B2C-Widerruf trotz Rule Builder

Problem: Regel ist nicht korrekt zugeordnet oder Twig-Condition fehlerhaft. Debug: Prüfe rule-Tabelle und rule_condition. Aktiviere Twig-Debug-Output und prüfe, ob die Kundengruppen-ID korrekt ist. Falls Template-Override: Prüfe Template-Hierarchie via bin/console debug:twig.

Nach Plugin-Update fehlen Inhalte

Problem: Plugin überschreibt CMS-Seiten oder Config-Werte. Debug: Erstelle vor Update ein Backup und Diff-View der CMS-Seiten. Prüfe Plugin-Logs unter var/log/. Falls Plugin fehlerhaft: Rollback via Composer und Datenbank-Restore. Kontaktiere Plugin-Anbieter mit detailliertem Error-Log.

Deployment-Checkliste: Rechtssicherheit vor Go-Live

Nutze diese Checkliste vor jedem Go-Live oder Major-Update:

• CMS-Seiten für alle Rechtstexte vorhanden und aktiv
• SystemConfig-Zuordnungen für alle Sales Channels korrekt gesetzt
• Footer-Kategorien aktiv und allen Sales Channels zugeordnet
• Alle Sprachen vollständig gepflegt (CMS-Translations vorhanden)
• Checkout-Templates korrekt: AGB-Checkbox required, Widerrufshinweise sichtbar
• Digitale Produkte: Zusätzliche Checkbox für Verzicht auf Widerrufsrecht
• B2B-Kundengruppen: Widerrufsseite ausgeblendet via Rule Builder
• Bestellbestätigung enthält Links zu Widerruf, AGB, Datenschutz
• Widerrufsformular als PDF oder Link verfügbar
• Omnibus-Preishistorie aktiv und korrekt dargestellt
• Bewertungs-Transparenztext platziert
• Grundpreise für alle Produkte korrekt
• Automatisierte Tests erfolgreich durchlaufen
• HTTP-Checks für alle Rechtstextseiten erfolgreich (Status 200)
• Cache invalidiert und warm-up durchgeführt
• Mobile Ansicht für alle Sales Channels und Sprachen geprüft
• Headless/PWA: API-Responses korrekt und Frontend rendert Links
• Flow Builder: Automatisierungen für Retouren und Bestellbestätigungen aktiv
• Backup vor Deployment erstellt und Rollback-Prozess getestet

Praxisbeispiel: Multi-Channel-Setup mit B2B, B2C und Headless

Ein konkretes Szenario: Ein mittelgroßer Elektronik-Händler betreibt drei Sales Channels: B2C-Storefront (DE/EN), B2B-Storefront (DE) und Headless-API für Mobile-App. Die Herausforderung: Rechtstexte müssen kanalspezifisch sein, B2B-Kunden dürfen kein Widerrufsrecht sehen, die Mobile-App muss CMS-Seiten korrekt darstellen.

Setup-Strategie

• CMS-Seiten anlegen: Je Sprache und Kanal eigene Seiten (B2C-DE-Impressum, B2C-EN-Impressum, B2B-DE-Impressum, etc.)
• SystemConfig-Zuordnung: Für jeden Sales Channel die korrekten CMS-Seiten-IDs hinterlegen
• Footer-Kategorien: B2C-Footer mit Widerruf, B2B-Footer ohne Widerruf
• Rule Builder: Regel Kundengruppe ist B2B erstellen und in Footer-Kategorie-Assignment nutzen
• Headless-API: Custom-Endpoint bauen, der CMS-Seiten-IDs aus SystemConfig lädt und Texte ausliefert
• Mobile-App: React-Native-Komponente, die API-Response rendert

Testing und Monitoring

• End-to-End-Tests für B2C-DE, B2C-EN, B2B-DE mit jeweils eigenen Testfällen
• API-Tests (Postman/Newman) für Headless-Endpoint
• CI/CD-Pipeline mit automatischem Rollback bei Testfehlern
• Monitoring via Cronjob für alle Rechtstextseiten (HTTP 200 Check)

Vorbereitung auf One-Click-Widerruf ab 2026

Ab 19. Juni 2026 muss ein One-Click-Widerruf möglich sein. Technische Anforderungen:

• Button im Kundenkonto: Vertrag widerrufen mit Link zu Widerrufsformular
• Formular muss auch für Gastbesteller funktionieren (Login-less via Token/E-Mail-Link)
• Backend: Custom-Controller, der Widerruf erfasst, Order-State ändert und Bestätigungs-E-Mail sendet
• Flow Builder: Automatisierung für Widerrufsbestätigung und Rückzahlungsprozess

Plane dieses Feature in deine Roadmap ein und teste es auf Staging ab Q1 2026.

Fazit: Deine nächsten Schritte zur Rechtssicherheit

Die Kombination aus Händlerbund und Shopware 6 ist eine der effektivsten Möglichkeiten, deinen Online-Shop rechtlich abzusichern – vorausgesetzt, du verstehst die technischen Details. Dieser Guide hat dir gezeigt, wie die Entity-Struktur funktioniert, wo die Admin-Pfade liegen, wie du Template-Anpassungen sauber umsetzt und wie du automatisierte Tests und Monitoring aufbaust.

Die wichtigsten Erkenntnisse:

• Rechtstexte sind Teil eines komplexen Datenmodells aus SystemConfig, CMS-Seiten, Kategorien und Sales Channels
• Admin-Pfade haben sich zwischen Shopware 6.4 und 6.5+ geändert – prüfe immer die aktuelle Dokumentation
• Template-Anpassungen und Flow Builder sind mächtige Werkzeuge, aber fehleranfällig bei Theme-Updates – nutze Git und automatisierte Tests
• Multi-Channel-Setups erfordern klare Zuordnungslogik und sales-channel-spezifische Config-Checks
• Automatisierte Tests und HTTP-Monitoring sind für produktive Shops unerlässlich
• Plugin-Updates müssen auf Staging getestet werden – mit Rollback-Plan und Diff-View der Rechtstexte
• Performance-Optimierung via HTTP-Cache und CDN spart Ressourcen und verbessert User Experience

Deine To-Do-Liste für heute:

• Prüfe SystemConfig-Zuordnungen für alle Sales Channels (core.basicInformation.*)
• Erstelle automatisierte Tests für Checkout, Footer und Bestellbestätigung
• Richte HTTP-Monitoring für alle Rechtstextseiten ein (Cronjob + Curl)
• Dokumentiere Template-Anpassungen und Custom-Checkboxen in deinem Projekt-Wiki
• Baue Omnibus-Preishistorie-Checks in deine Produktpflege-Prozesse ein
• Plane One-Click-Widerruf in Roadmap ein (Q1 2026 Testing, Q2 2026 Go-Live)
• Teste Rollback-Prozess auf Staging (Plugin-Downgrade + DB-Restore)
• Erstelle Sales-Channel-spezifische Deployment-Checklisten

Wichtiger Hinweis: Dieser Artikel stellt keine Rechtsberatung dar. Gesetze und Shopware-Versionen ändern sich. Lass deine finale Shop-Konfiguration von einem Fachanwalt oder einem Dienstleister wie dem Händlerbund prüfen. Die Verantwortung für die rechtliche Umsetzung liegt immer beim Händler.