1. Eigenschaft, Option, Variante: drei Begriffe, ein Missverständnis
Ein Hemd wird in den Grössen S, M und L geführt, dazu in den Farben Blau und Weiss. Ausserdem soll im Shop sichtbar sein, dass das Hemd aus Baumwolle besteht. Drei Angaben, die auf den ersten Blick ähnlich wirken – Grösse, Farbe, Material –, gehören in Shopware 6 aber zu zwei unterschiedlichen Konzepten.
Material ist eine Eigenschaft. Es beschreibt das Produkt, unterscheidet aber keine Variante von einer anderen: Jede Grösse und jede Farbe dieses Hemds besteht aus Baumwolle, das Merkmal ändert sich nicht. Grösse und Farbe dagegen sind Optionen. Sie sind der Grund, warum aus einem Hemd sechs unterschiedliche Artikel werden – S/Blau, M/Blau, L/Blau, S/Weiss, M/Weiss, L/Weiss.
Technisch zeigt sich der Unterschied im verwendeten Feld. Eine Eigenschaft wird über properties gepflegt, eine Option über options. Laut der offiziellen Shopware-Dokumentation (Einstellungen, Import/Export) verweisen beide Felder auf dieselbe Datenbanktabelle property_group_option. Damit ist es technisch dieselbe Quelle – ob ein Wert dort als beschreibendes Merkmal oder als variantenbildende Ausprägung verwendet wird, entscheidet sich erst über das Feld, mit dem er dem Produkt zugewiesen wird.
Genau das ist der Grund, warum die Verwechslung so häufig vorkommt. Wer eine Ausprägung versehentlich über properties statt über options zuweist, sieht im Administration-Panel eine scheinbar korrekt zugeordnete Eigenschaft – und wundert sich anschliessend, warum daraus keine Variante entsteht. Die Zuordnung ist nicht falsch im Sinne eines Fehlers, sie landet nur in der Struktur, die für Varianten nicht ausgewertet wird.
Eine dritte Grösse kommt hinzu, sobald tatsächlich Varianten entstehen sollen: die Variante selbst. Sie ist kein Merkmal und keine Ausprägung, sondern ein eigener Datensatz, der über parent auf den Hauptartikel verweist und über optionIds mit den ihn definierenden Optionen verknüpft wird. optionIds referenziert dabei die Tabelle product_option.
| Begriff | Technisches Feld | Wofür es da ist |
|---|---|---|
| Eigenschaft | properties | Beschreibendes, filterbares Merkmal eines Produkts (z. B. Material, Gewicht). Erwartet UUIDs aus property_group_option, getrennt durch das Pipe-Symbol. |
| Option | options | Die Ausprägung, die eine Variante von einer anderen unterscheidet (z. B. Grösse M, Farbe Blau). Verweist ebenfalls auf property_group_option. |
| Variante | parent, optionIds | Ein eigener Datensatz, der über parent dem Hauptartikel zugeordnet und über optionIds (Tabelle product_option) mit seinen Optionen verknüpft wird. |
Dieser Unterschied ist der Kern dieses Beitrags. Alles Weitere – warum Varianten nicht erscheinen, warum Eigenschaften leer bleiben, wie sich Lieferantendaten sauber zuordnen lassen – lässt sich auf diese eine Verwechslung zurückführen.
2. Wie Lieferanten Varianten liefern
Shopware erwartet eine klare Struktur aus Hauptartikel, Varianten und Optionen. Lieferantendaten liefern diese Struktur so gut wie nie in dieser Form – sie sind für die Lektüre durch einen Menschen entstanden, nicht für den Import in ein Shopsystem. Vier Formen tauchen in der Praxis immer wieder auf, oft auch in Kombination innerhalb desselben Lieferantensortiments.
Eine Zeile pro Variante, Grösse in eigener Spalte. Eine Preisliste enthält pro Zeile eine eigene Artikelnummer, dazu Spalten für Bezeichnung, Grösse und Bestand. Das Hemd erscheint hier sechsmal, einmal pro Grösse-Farbe-Kombination. Diese Form ist die dankbarste: Jede Zeile entspricht bereits fast einer Variante, es fehlt im Wesentlichen die Zuordnung zu einem gemeinsamen Hauptartikel über parent sowie die Übersetzung der Grössen- und Farbwerte in optionIds.
Eine Zeile pro Artikel, Grössen als Spalten nebeneinander. Andere Lieferanten liefern eine Zeile pro Farbe, mit separaten Spalten für S, M und L, in denen jeweils der Bestand steht. Diese Form muss zunächst „entpivotiert“ werden: Aus einer Zeile mit drei Bestandsspalten werden drei Zeilen mit je einer Grössenangabe, bevor daraus Varianten abgeleitet werden können.
Varianten stecken im Produktnamen. Häufig taucht die Variantenangabe nicht in einer eigenen Spalte auf, sondern im Freitext der Produktbezeichnung, etwa „Hemd Classic blau M“. Grösse und Farbe müssen hier zunächst aus dem Namen herausgelöst werden, bevor sie als separate Optionswerte verwendet werden können. Bei uneinheitlicher Schreibweise – „blau“ versus „Blau“ versus „BLAU“ – ist zusätzlich eine Vereinheitlichung nötig, damit nicht versehentlich mehrere Optionswerte für dieselbe Farbe entstehen.
Grössentabelle in einem separaten Abschnitt des Dokuments. In Katalog-PDFs steht die Grössenverfügbarkeit teilweise in einer eigenen Tabelle, getrennt vom eigentlichen Artikeltext, und lässt sich nur über die Artikelnummer der jeweiligen Seite zuordnen. Hier müssen zwei Bereiche eines Dokuments korrekt miteinander verknüpft werden, bevor überhaupt eine Zeile pro Variante entsteht.
In allen vier Fällen ist die eigentliche Arbeit nicht der Import selbst, sondern der Schritt davor: aus uneinheitlichen Rohdaten eine Struktur mit Hauptartikel, Varianten und eindeutigen Optionswerten abzuleiten. Erst wenn diese Struktur steht, stellt sich überhaupt die Frage, welches Importprofil oder welcher API-Aufruf dafür sinnvoll ist – Abschnitt 8 geht auf diese Wahl näher ein.
3. Was Shopware daraus braucht
Unabhängig vom Ausgangsformat läuft die Ableitung auf dasselbe Ziel hinaus: ein Hauptartikel, dem mehrere Varianten über parent zugeordnet sind, sowie Optionswerte, die diese Varianten über optionIds voneinander unterscheiden.
Lieferantendaten (Rohformat)
Zeile aus einer Preisliste: Artikelnummer „HEMD-CL“, Bezeichnung „Hemd Classic blau M“, Bestand „12“.
Keine Trennung zwischen Hauptartikel und Variante, Grösse und Farbe stehen im Freitext, keine Verkaufspreise mit Steuerbezug.
Für Shopware abgeleitete Struktur
Hauptartikel „Hemd Classic“ mit productNumber „HEMD-CL“.
Variante mit parent = Hauptartikel, options = Blau, M, sowie befülltem stock und price.DEFAULT.gross.
Wie ein entsprechender Ausschnitt für den Import aussehen könnte, zeigt die folgende, bewusst reduzierte Darstellung. Es handelt sich um eine illustrative Vereinfachung zur Veranschaulichung der Struktur, nicht um ein copy-paste-fertiges Importprofil – die tatsächlich benötigten Spalten hängen vom eigenen Profil und den Pflichtfeldern (id, taxId, productNumber, stock, name) ab.
productNumber;name;parent;options;properties;stock;price.DEFAULT.gross
HEMD-CL;Hemd Classic;;;;0;29.90
HEMD-CL-BL-M;Hemd Classic Blau M;HEMD-CL;Blau|M;Baumwolle;12;29.90
HEMD-CL-BL-L;Hemd Classic Blau L;HEMD-CL;Blau|L;Baumwolle;7;29.90
HEMD-CL-WS-M;Hemd Classic Weiss M;HEMD-CL;Weiss|M;Baumwolle;9;29.90In dieser Vereinfachung stehen unter options und properties lesbare Bezeichnungen statt UUIDs, um die Struktur nachvollziehbar zu machen. Im tatsächlichen Importprofil erwarten beide Felder die UUIDs der jeweiligen property_group_option-Einträge, bei properties durch das Pipe-Symbol getrennt. Der Hauptartikel steht in der ersten Zeile mit leerem parent, die Varianten darunter verweisen über parent auf dessen productNumber beziehungsweise – bei Verwendung des Second Unique Identifiers – auf den gewählten Bezeichner. Wie sich dieser gesamte Ableitungsschritt aus Lieferanten-PDF oder Excel-Datei automatisieren lässt, beschreibt Produktdaten aus Lieferantendokumenten automatisch anlegen.
4. Warum importierte Varianten im Frontend nicht erscheinen
Die häufigste Beobachtung nach einem Variantenimport: In der Administration sind die Datensätze vorhanden, Anzahl und Bezeichnung der Varianten stimmen, im Shop-Frontend erscheinen sie aber nicht oder nur teilweise. Das ist kein Widerspruch, sondern zeigt lediglich, dass die Daten korrekt in Shopware angekommen sind, ohne dass alle für die Storefront relevanten Felder mitgeliefert wurden. Da die genaue Ursache vom individuellen Setup abhängt, lassen sich hier nur die Punkte nennen, die sich aus den dokumentierten Feldern ergeben und die typischerweise zuerst zu prüfen sind.
Typische Ursachen, die zu prüfen sind
Verkaufskanalzuordnung über visibilities.all, visibilities.link und visibilities.search: Fehlt die UUID des betroffenen Verkaufskanals oder ist sie nur beim Hauptartikel, nicht aber bei den Varianten gesetzt, bleiben Varianten unsichtbar.
variantListingConfig: Dieses Feld steuert die Varianten-Darstellung in der Storefront. Eine nicht oder falsch gesetzte Konfiguration kann dazu führen, dass Varianten zwar existieren, aber nicht wie erwartet dargestellt werden.
Fehlende oder unvollständige Optionszuordnung über optionIds: Ohne korrekt zugeordnete Optionen fehlt die Verknüpfung, die eine Variante als Variante des Hauptartikels ausweist.
Reihenfolge der Importschritte: Ob Hauptartikel und Varianten in einem Durchlauf oder nacheinander importiert werden sollten, ist im Einzelfall zu prüfen – insbesondere wenn Varianten über parent auf einen Hauptartikel verweisen, der zum Zeitpunkt des Imports noch nicht vollständig angelegt ist.
Diese vier Punkte sind keine abschliessende Fehlerdiagnose, sondern eine Prüfreihenfolge. Erst wenn visibilities, variantListingConfig, optionIds und die Importreihenfolge kontrolliert wurden, lohnt sich die Suche nach selteneren Ursachen.
5. Warum Eigenschaften und Custom Fields leer bleiben
Neben unsichtbaren Varianten ist eine leere oder unvollständige Eigenschaft die zweithäufigste Beobachtung. Auch hierfür lässt sich die Ursache direkt aus der Feldbeschreibung ableiten.
Was properties konkret erwartet
properties erwartet UUIDs aus der Tabelle property_group_option, getrennt durch das Pipe-Symbol – keine Klartextwerte wie „Baumwolle“. Wird stattdessen ein lesbarer Text in die Importdatei geschrieben, kann das Feld nicht wie vorgesehen befüllt werden.
Ausserdem müssen die Eigenschaften selbst vor dem Import bereits als Optionswerte existieren. Ein Import legt referenzierte Eigenschaften nicht automatisch neu an, er verknüpft nur vorhandene Datensätze.
Für Custom Fields gilt dieselbe Grundregel: Sie müssen vor dem Import angelegt sein, damit eine Importdatei ihnen Werte zuweisen kann. Ebenso werden Verkaufskanäle, wie bei den Varianten bereits beschrieben, über UUIDs referenziert – auch hier führt ein Klartextwert statt der passenden UUID dazu, dass die Zuordnung ins Leere läuft.
Ein weiterer, oft übersehener Punkt betrifft nicht das Hinzufügen, sondern das Entfernen von Daten. Laut Dokumentation lassen sich mit einem Import generell nur Informationen hinzufügen, nicht entfernen. Eine bestehende Verkaufskanalzuordnung kann per Import beispielsweise nicht wieder entfernt werden. Wer also einen fehlerhaften Wert per Re-Import „löschen“ möchte, indem das Feld in der Importdatei leer gelassen wird, wird feststellen, dass der ursprüngliche Wert stehen bleibt. Eine leere Spalte bedeutet für den Import „keine Angabe“, nicht „bestehenden Wert entfernen“.
6. Der Second Unique Identifier: Arbeiten ohne UUID-Chaos
Ein Importprofil benötigte bislang immer eine UUID, um eine Zeile der Importdatei eindeutig einer Entität zuzuordnen – in jeder Zeile eine lange, kryptische Zeichenfolge, die von Hand kaum zu pflegen ist. Genau das ist bei Lieferantendaten ein praktisches Problem: Ein Lieferant liefert Artikelnummern, niemals Shopware-UUIDs.
Der Second Unique Identifier löst dieses Problem, indem sich selbst festlegen lässt, mit welchem Bezeichner gemappt wird – zum Beispiel productNumber statt der internen UUID. Die Einstellung findet sich unter Einstellungen, Automatisierung, Import/Export, im Reiter Profile, dort im Reiter Erweiterte Einstellungen. Ist sie einmal gesetzt, gilt sie für das jeweilige Profil und muss nicht für jeden einzelnen Import neu konfiguriert werden.
Für Lieferantendaten ist das mehr als eine Komfortfunktion. Ohne einen selbst gewählten Bezeichner müsste vor jedem Import erst eine Zuordnungstabelle gepflegt werden, die jeder Lieferanten-Artikelnummer die passende Shopware-UUID zuordnet – ein zusätzlicher Datenbestand, der bei jedem neuen Artikel und jeder Sortimentsänderung aktuell gehalten werden müsste. Mit productNumber als Bezeichner entfällt dieser Zwischenschritt vollständig.
Warum das bei Lieferantendaten den Unterschied macht
Sobald productNumber als Bezeichner hinterlegt ist, lässt sich eine Lieferantendatei direkt anhand der ohnehin vorhandenen Artikelnummer importieren und bei einem erneuten Import aktualisieren, ohne dass zuvor eine UUID aus Shopware in die Lieferantendatei übertragen werden muss.
Die Dokumentation weist an dieser Stelle ausdrücklich auf eine Einschränkung hin: Nicht jedes Mapping ist sinnvoll. Wird beispielsweise der Produktname als Bezeichner gewählt und tragen mehrere Produkte denselben Namen, kann das System darüber nur den ersten gefundenen Datensatz eindeutig identifizieren.
Bezeichner sorgfältig wählen
Ein Second Unique Identifier ist nur so gut wie seine Eindeutigkeit. productNumber eignet sich in aller Regel, weil Artikelnummern konstruktionsbedingt eindeutig sind. Ein Feld wie der Produktname ist dafür ungeeignet, sobald Namensdopplungen im Sortiment vorkommen können.
7. Prüfen, bevor importiert wird
Ein grosser Teil der Probleme, die in den vorherigen Abschnitten beschrieben wurden, lässt sich vor dem eigentlichen Import erkennen. Shopware stellt dafür eine Reihe von Prüfmöglichkeiten bereit.
Grundlegend ist zunächst die Datei selbst: valides UTF-8, Semikolon als Feldtrenner und Anführungszeichen als Zeichenketten-Trenner sind laut Dokumentation Grundvoraussetzung für einen erfolgreichen Import. Preis-Nachkommastellen müssen mit einem Punkt getrennt werden – bei einem Komma wird der Preis nicht korrekt importiert. Da einige Tabellenkalkulationsprogramme Trennzeichen oder führende Nullen beim Speichern verändern, empfiehlt die Dokumentation ein Werkzeug, das native CSV-Dateien erzeugt, statt sich auf den CSV-Export einer Tabellenkalkulation zu verlassen.
Darüber hinaus lohnt sich vor dem Import eine Kontrolle auf inhaltlicher Ebene. In der Praxis bewährt sich eine kurze Liste, die vor jedem Import durchgegangen wird:
- Ist die Datei valides UTF-8 und verwendet Semikolon als Feldtrenner sowie Anführungszeichen als Zeichenketten-Trenner?
- Sind Preisangaben mit Punkt statt Komma als Dezimaltrennzeichen geschrieben?
- Sind führende Nullen in Artikelnummern erhalten geblieben, oder hat die Tabellenkalkulation sie beim Speichern entfernt?
- Sind alle Artikelnummern innerhalb der Datei eindeutig?
- Ist zu jeder Variantenzeile ein passender Hauptartikel vorhanden, und stimmt die Anzahl der Variantenzeilen mit der erwarteten Anzahl an Optionskombinationen überein?
- Ergeben die Optionskombinationen inhaltlich Sinn, oder tauchen durch uneinheitliche Schreibweise versehentlich doppelte Optionswerte auf, wie im Beispiel „blau“ und „Blau“ aus Abschnitt 2?
Jeder dieser Punkte lässt sich vor dem eigentlichen Import prüfen und ist günstiger zu korrigieren als ein fehlerhafter Import, der im Nachhinein wieder zurückgenommen werden muss – zumal ein Import, wie in Abschnitt 5 beschrieben, ohnehin nur hinzufügt und nicht entfernt.
Testlauf vor dem echten Import nutzen
Für den Import selbst steht ein Testlauf-Button zur Verfügung, mit dem sich der Import vollständig durchspielen lässt, bevor er tatsächlich ausgeführt wird. Fehlerhafte Datensätze werden im Anschluss an einen Import in einer separaten CSV-Datei zusammengefasst, die sich herunterladen und gezielt korrigieren lässt.
Bei Daten, die aus einem fremden Dokument wie einem Lieferanten-PDF stammen, kommt ein weiterer Punkt hinzu: Diese Daten wurden nicht für den direkten Import erzeugt, sondern für die menschliche Lektüre. Ein Prüfschritt, in dem eine Person die abgeleiteten Daten stichprobenartig mit dem Ursprungsdokument abgleicht, bevor sie produktiv übernommen werden, ist bei dieser Art von Quelle sinnvoll – unabhängig davon, ob die Ableitung von Hand oder automatisiert erfolgt.
8. Importdatei oder API: wann was sinnvoll ist
Für das Anlegen und Aktualisieren von Varianten stehen grundsätzlich zwei Wege offen: die Importdatei über das Administration-Panel oder die direkte Anbindung über die API. Beide haben einen klaren Anwendungsbereich.
| Kriterium | Importdatei | API |
|---|---|---|
| Eignet sich für | Einmalige oder gelegentliche Aktionen | Wiederkehrende, automatisierte Abläufe |
| Datenmenge | Überschaubare, absehbare Mengen | Grosse oder laufend wechselnde Mengen, mehrere Lieferanten |
| Entwicklungsaufwand | Keiner, Bordmittel von Shopware genügen | Anbindung und Fehlerbehandlung müssen entwickelt werden |
| Fehlerbehandlung | Manuell anhand der Fehler-CSV nach dem Import | Kann direkt im Prozess geprüft und behandelt werden |
| Grenzen | Komplexe, stark verschachtelte Strukturen sind mühsam | Ohne Entwicklungsaufwand nicht nutzbar |
Die ehrliche Einschätzung fällt entsprechend eindeutig aus: Wer einmal im Jahr 200 Artikel einspielt, braucht dafür keine API – die Importdatei erledigt das ohne zusätzlichen Aufwand. Wer dagegen wöchentlich Lieferantendateien in wechselnden Formaten verarbeitet, spart mit der Importdatei nichts, weil die manuelle Aufbereitung jede Woche erneut anfällt. In diesem Fall amortisiert sich der Aufwand für eine API-Anbindung durch die Wiederholung.
Zwischen diesen beiden Polen liegt ein grosser Bereich, in dem beide Wege vertretbar sind und die Entscheidung von den eigenen Ressourcen abhängt: eine Handvoll Lieferanten mit monatlichen Aktualisierungen lässt sich mit der Importdatei bewältigen, sofern jemand die Aufbereitung übernimmt und Zeit dafür einplant. Steigt die Anzahl der Lieferanten oder die Frequenz der Aktualisierungen, verschiebt sich der Aufwand zunehmend von der einmaligen Entwicklung hin zur wiederkehrenden manuellen Pflege – und damit tendenziell in Richtung API. Für laufende, wiederkehrende Prozesse rund um den eigenen Shop liefert Shopware-Automatisierung einen umfassenderen Überblick.