Custom Fields in Shopware: eigene Felder ohne Plugin

Shopware liefert out of the box eine solide Datenbasis: Produktname, Preis, Beschreibung, Lagerbestand. Aber kein Standardfeld für deine Zolltarifnummer, deine interne Artikelklassifikation oder den Mindestbestellhinweis für B2B-Kunden. Genau hier kommen Custom Fields ins Spiel. Du erweiterst damit das Datenmodell von Shopware ohne ein Plugin zu schreiben und ohne in den Code einzugreifen.

Was Custom Fields sind und was sie nicht sind

Custom Fields sind frei definierbare Zusatzfelder, die du an nahezu jedes Datenobjekt in Shopware hängen kannst: Produkte, Varianten, Kategorien, Kunden, Bestellungen, Adressen, Hersteller. Du legst fest, welcher Datentyp gespeichert wird (Text, Zahl, Datum, Checkbox, Auswahlliste, Farbwähler, Media-Upload) und ob das Feld im Backend sichtbar und bearbeitbar ist.

Wichtig ist das Wort “Zusatz”. Custom Fields erweitern das bestehende Datenmodell, ersetzen es aber nicht. Ein Custom Field für Produkte ist kein eigenes Datenbankfeld in der engeren Sinne, sondern wird als JSON-Blob im Feld customFields der jeweiligen Entity gespeichert. Das hat Konsequenzen für Performance und Abfragen, dazu später mehr.

Custom Fields sind auch kein Ersatz für echte Plugin-Entitäten, wenn du strukturierte, verknüpfte Daten brauchst. Wer eine vollständige Stückliste oder ein Konfigurator-Datenmodell abbilden will, kommt mit Custom Fields allein nicht weit. Das ist ein Bereich, in dem wir häufig mit Kunden sprechen, die denken, Custom Fields lösen ihr Problem, und dann feststellen, dass eine individuelle Softwarelösung die sauberere Antwort ist.

Custom Fields einrichten: Schritt für Schritt

Du findest das Modul im Shopware-Backend unter “Einstellungen > Custom Fields”. Der Aufbau folgt einem Zwei-Ebenen-System:

Custom Field Sets sind Gruppen von Feldern, die du einer oder mehreren Entitäten zuordnest. Ein Set könnte zum Beispiel “Produktdaten Lager” heißen und die Entität “Produkt” bekommen. Innerhalb dieses Sets liegen dann die einzelnen Felder.

Custom Fields sind die eigentlichen Felder innerhalb eines Sets. Du vergibst einen technischen Namen (Pflicht: lowercase, Unterstriche, kein Leerzeichen), einen Anzeigenamen für das Backend, den Feldtyp und optional eine Reihenfolge.

Der technische Name entscheidet, wie du das Feld in Twig-Templates und über die API ansprichst. Einmal gesetzt, solltest du ihn nicht mehr ändern, da er in Templates, Flows und API-Abfragen referenziert wird.

Mögliche Feldtypen im Überblick:

• Text (einzeilig oder mehrzeilig)
• Ganze Zahl oder Dezimalzahl
• Datum und Uhrzeit
• Ja/Nein (Checkbox)
• Auswahlliste (Select, auch Mehrfachauswahl)
• Farbwähler (für visuelle Konfigurationen)
• Media-Upload (Bild oder Datei)
• HTML-Editor für formatierten Text

Custom Fields in Templates und der Storefront nutzen

Ein Custom Field, das nur im Backend gespeichert wird, nützt wenig. Der häufigste Einsatz ist die Ausgabe auf der Produktdetailseite, zum Beispiel ein technisches Datenblatt, ein Hinweistext für Zollangaben oder eine eigene Badge-Beschriftung.

In Twig greifst du auf Custom Fields über die Variable customFields des jeweiligen Objekts zu:

{% if product.customFields.bui_zolltarifnummer %}
    <p>Zolltarifnummer: {{ product.customFields.bui_zolltarifnummer }}</p>
{% endif %}

Das Präfix im technischen Namen (hier bui_) ist eine Konvention, aber eine wichtige. Shopware-Plugins und Themes nutzen denselben Namespace. Wer keine Präfixe verwendet, riskiert Kollisionen mit anderen Feldern. Wir empfehlen immer ein kurzes, projekteigenes Präfix.

Custom Fields stehen auch in E-Mail-Templates zur Verfügung, was für automatisierte Bestellbestätigungen oder individuelle Versandhinweise nützlich ist.

Custom Fields per API lesen und schreiben

Für ERP-Anbindungen sind Custom Fields häufig der einfachste Weg, systemspezifische Daten anzudocken. Du schreibst zum Beispiel die interne Artikelnummer aus deinem ERP per API in ein Custom Field, und dein Shop kann sie im Template ausgeben oder in Flows nutzen.

Das Admin-API gibt Custom Fields direkt mit dem Produkt-Objekt zurück. Schreiben geht über einen PATCH-Request auf die Entität:

PATCH /api/product/{id}
{
  "customFields": {
    "bui_erp_artikelnummer": "ERP-12345"
  }
}

Wichtig: Beim Schreiben via API werden nur die angegebenen Custom Fields aktualisiert. Fehlende Felder werden nicht gelöscht. Das ist intuitiver als ein vollständiges Überschreiben des gesamten customFields-Objekts.

Wo Custom Fields an ihre Grenzen stoßen

Custom Fields sind praktisch, aber kein Allheilmittel. Es gibt Situationen, in denen sie mehr Probleme schaffen als lösen.

Performance bei Massenabfragen. Da Custom Fields als JSON gespeichert werden, lassen sie sich nicht nativ indexieren. Filtern oder Sortieren nach einem Custom Field in einer Produktliste mit tausenden Einträgen ist langsam. Wer das braucht, braucht eine eigene Entität mit echten Datenbankfeldern, oft über ein Plugin oder die individuelle Softwareentwicklung.

Keine Validierung auf Datenbankebene. Shopware prüft beim Schreiben nicht, ob der gespeicherte Wert zum definierten Feldtyp passt. Ein Textfeld kann technisch auch eine Zahl aufnehmen. Die Validierung findet nur im Backend-Formular statt, nicht bei API-Zugriffen.

Keine eigenen Relationen. Du kannst in einem Custom Field keine Referenz auf eine andere Entität speichern, zumindest nicht mit nativer Unterstützung. Wenn du eine Produkt-zu-Produkt-Beziehung brauchst (zum Beispiel für Ersatzteile oder Sets), ist das der falsche Ansatz. Das Shopware Plugin-System bietet dafür die technisch sauberere Grundlage.

Übersetzungen. Custom Fields unterstützen Übersetzungen, aber der Mechanismus muss sauber konfiguriert sein. Wer im mehrsprachigen Shop Custom Fields einbaut, ohne auf Translatable-Typen zu achten, hat später Felder, die in der Übersetzung leer bleiben.

Custom Fields und der Rule Builder

Der Shopware Rule Builder kann Custom Fields als Bedingungen verwenden, zumindest über Umwege per Custom Field Rule. In der Praxis nutzen wir das zum Beispiel, um B2B-Kunden mit einem Custom Field zu kennzeichnen und dann im Rule Builder auf diese Gruppe andere Versandoptionen oder Zahlungsarten zuzulassen. Elegant, wenn der Anwendungsfall es hergibt.

Häufige Fragen

Kann ich Custom Fields nachträglich löschen?

Ja, du kannst einzelne Felder oder ganze Sets löschen. Dabei werden aber nur die Felddefinitionen entfernt, nicht die gespeicherten Daten in den Entitäten. Die JSON-Werte bleiben in den customFields-Spalten der Datenbank erhalten, sind aber nicht mehr über die Backend-UI bearbeitbar. Wer wirklich aufräumen will, muss die Daten auch auf Datenbankebene bereinigen oder per API leeren.

Sind Custom Fields auch für Bestellungen und Kunden nutzbar?

Ja, du kannst Custom Fields für fast alle Entitäten anlegen: Produkte, Kategorien, Kunden, Bestellungen, Bestellpositionen, Adressen und Hersteller. Besonders bei Bestellungen sind Custom Fields nützlich, um interne Bearbeitungsstatus, Fulfillment-Hinweise oder Sonderkennzeichen zu speichern, die im Standard nicht vorgesehen sind.

Wie verhalte ich mich bei Shopware-Updates?

Custom Fields sind Teil des offiziellen Erweiterungskonzepts von Shopware und werden durch Updates nicht berührt. Solange du keine Template-Anpassungen hast, die auf Custom Field-Namen referenzieren, sind Updates unkritisch. Wer Custom Fields in Theme-Templates nutzt, sollte nach größeren Updates kurz prüfen, ob die Ausgabe noch korrekt ist.

Ab welcher Shopware-Edition stehen Custom Fields zur Verfügung?

Custom Fields sind in allen Shopware 6 Editionen enthalten, auch in der Community Edition ohne Lizenzkosten. Es gibt keine Einschränkungen auf bestimmte Plan-Stufen. Die erweiterten B2B-Funktionen, also das Kombinieren mit Kundengruppen-Regeln oder komplex verschachtelten Freigabeprozessen, greifen allerdings erst in höheren Editionen vollständig.

Wann du mehr brauchst

Custom Fields lösen viele Probleme schnell und unkompliziert. Für strukturiertere Anforderungen, eigene Entitäten, komplexe ERP-Synchronisation oder performante Filterfunktionen, braucht es mehr. In solchen Fällen planen wir mit dir gemeinsam, ob ein bestehendes Plugin aus unserem Plugin-Portfolio passt oder ob eine individuelle Entwicklung sinnvoller ist. Mehr zu möglichen Ansätzen findest du auf unserer Seite zur Shopware-Betreuung.