Shopify Metafields: Komplette Anleitung zu Setup und Anzeige

Ein Shopify Metafield ist ein benutzerdefiniertes Schlüssel-Wert-Feld, das du an eine Store-Ressource (Produkt, Kollektion, Bestellung, Kunde, Variante und mehr) anhängst, um Daten zu speichern, die Shopifys Kernschema nicht nativ bereitstellt. Du definierst den Datentyp, erzwingst Validierung und präsentierst den Wert dann überall: dein Storefront über Liquid, deine Analysen über ShopifyQL, dein Checkout über Shopify Functions oder deine externen Systeme über die GraphQL Admin API. Diese dreistufige Schleife (definieren, füllen, anzeigen) ist das gesamte mentale Modell, das du brauchst.

Wichtigste Erkenntnisse

• Ein Metafield wird durch drei Dinge identifiziert: Owner-Ressource, Namespace und Schlüssel. Wenn du eines dieser Elemente änderst, referenzierst du ein anderes Feld.
• Shopifys Spring '26 und Summer '26 Editionen brachten mehrere Metafield-Verbesserungen: Fixiere bis zu 50 Felder auf Admin-Seiten, Cart-Metafields, die zu Bestellungen übergehen, Metafields bei Bestandsübertragungen und ShopifyQL Dot-Syntax-Filterung.
• Die Admin GraphQL API 2026-07 Release Candidate ermöglicht es dir, Metafields direkt auf Bestandsübertragungen zu definieren und zu setzen, ohne einen separaten metafieldsSet Aufruf zu benötigen.
• Das Erstellen einer Definition zeigt nichts auf deinem Storefront an. Du musst das Feld immer noch über eine dynamische Quelle im Theme-Editor verbinden oder das Liquid selbst schreiben.
• Standard-Definitionen (Pflegeanweisungen, Zutaten, Größe, ISBN usw.) sind der schnellste Weg, da sie vorkonfiguriert, Theme-kompatibel und app-interoperabel sind.

Was genau ist ein Shopify Metafield?

Metafields ermöglichen es dir, zusätzliche Informationen an eine Shopify-Ressource anzuhängen, wie z.B. ein Produkt oder eine Kollektion. Die Daten können Spezifikationen, Größentabellen, herunterladbare Dokumente, Veröffentlichungsdaten, Bilder oder Teilenummern sein. Jedes Metafield speichert einen Wert zusammen mit Typinformationen und wird durch seine Owner-Ressource, seinen Namespace und seinen Schlüssel identifiziert.

Stelle dir den Namespace als Ordnernamen und den Schlüssel als Dateinamen in diesem Ordner vor. Ein Produkt-Metafield mit namespace: custom und key: material ist völlig unabhängig von einem mit namespace: specs und key: material, obwohl beide auf demselben Produkt existieren.

Die drei Ownership-Modelle

Das Verständnis der Ownership-Struktur verhindert, dass du versehentlich Daten überschreibst, die du nicht ändern wolltest.

Merchant-owned Metafields verwenden einen beliebigen nicht reservierten Namespace (wie custom, specs oder inventory). Alle installierten Apps können sie lesen und schreiben. Sie sind ideal für gemeinsame Daten, die mehrere Apps nutzen.

App-owned Metafields verwenden das reservierte $app Namespace-Präfix. Die besitzende App kontrolliert die Struktur und Werte, die im Admin standardmäßig schreibgeschützt sind. Verwende diese, wenn eine App die autoritative Quelle für ein Datenelement ist.

App-data Metafields sind an eine bestimmte App-Installation gebunden und sind vollständig vor dem Shopify Admin verborgen. Sie existieren auf der AppInstallation Ressource und können nur von der besitzenden App über GraphQL oder das app Objekt in Liquid aufgerufen werden. Diese sind für internen App-Status gedacht, der niemals für Merchants sichtbar sein sollte.

Shopify verwaltet auch Shopify-reservierte Namespaces (mit Präfix shopify--) für von der Plattform verwaltete Felder wie Standard-Definitionen.

Metafield-Datentypen: eine praktische Übersicht

Shopify gruppiert Typen in Kategorien. Die Wahl des richtigen Typs ist wichtig, da er Validierung erzwingt, steuert, wie Liquid den Wert rendert, und bestimmt, welche Filter angewendet werden.

Text

• single_line_text_field, Produkt-Badges, kurze Labels, ISO-Codes
• multi_line_text_field, Zutatenlisten, Pflegeanweisungen (Zeilenumbrüche bleiben erhalten)
• rich_text, formatierter längerer Text (Überschriften, fett, Listen); mit dem metafield_tag Filter rendern

Zahlen und Messungen

• number_integer, number_decimal
• dimension, volume, weight, speichern jeweils einen numerischen Wert zusammen mit einer Einheit; ideal für Produktspezifikationen und Versandregeln

Daten und Uhrzeiten

• date, date_time, Startdaten, Ablaufdaten, Event-Zeitpläne

Referenzen

• product_reference, collection_reference, page_reference, variant_reference, verlinke eine Ressource mit einer anderen ohne Daten zu duplizieren
• metaobject_reference, verlinke zu einem Metaobject-Eintrag (siehe unten)
• article_reference und list.article_reference, hinzugefügt in der 2025-10 API-Version; ermögliche es dir, Produkte direkt mit Blog-Posts zu verknüpfen für Content-getriebene Commerce und SEO

Andere nützliche Typen

• boolean, Feature-Flags, "Neuankunft"-Toggle, Ausverkauft-Marker
• color, hex-basierte Farbwerte mit nativer Farbfeld-Unterstützung
• url, file_reference, herunterladbare PDFs, Datenblätter, Videos
• json, beliebige strukturierte Daten; nützlich aber schwieriger zu validieren und zu rendern

Für List-Typen stelle jedem Skalartyp list. voran (zum Beispiel list.single_line_text_field). Diese werden als Arrays in Liquid gerendert und sind die richtige Wahl, wenn ein Feld mehrere Werte halten kann, wie eine Liste von Materialien oder eine Reihe von Abhol-Standorten.

Eine wichtige Einschränkung: Wenn du die GraphQL Admin API verwendest, wird der Metafield-Wert immer als String eingegeben und gespeichert, unabhängig vom deklarierten Typ. Shopify kümmert sich bei der Abfrage um die Typkonvertierung.

Metafield-Definitionen: warum sie wichtig sind

Du kannst ein rohes Metafield (ohne Definition) über die API schreiben, aber Definitionen sind fast immer die richtige Wahl. Eine Metafield-Definition etabliert ein Schema, das alle Werte für diese Namespace-Key-Kombination befolgen müssen, einschließlich des Datentyps und Validierungsbeschränkungen. Die Definition steuert auch die Zugriffsgenehmigungen über die GraphQL Admin API, Storefront API und Customer Account API und bestimmt, ob das Feld für Admin-Filterung oder als Sammlungsbedingung verwendet werden kann.

Das Bauen mit Definitionen bedeutet:

• Admin-UI-Unterstützung. Definierte Felder erscheinen auf jeder relevanten Ressourcen-Bearbeitungsseite ohne benutzerdefinierten Code.
• Validierung. Ungültige Werte werden abgefangen, bevor sie dein Storefront beschädigen.
• Filterung. Du kannst ein definiertes Feld als Smart-Collection-Bedingung oder als Admin-Filter verwenden.
• Theme-Editor-Erkennung. Dynamische Quellen-Picker zeigen nur definierte Felder an.

Standard-Definitionen sind vorgefertigte Schemas für häufige Anwendungsfälle wie ISBN-Nummern, Produktzutaten und Pflegeanweisungen. Ihre Verwendung bedeutet, dass Apps und Themes, die auf diese Standard-Namespaces verweisen, bereits wissen, wie sie deine Daten ohne zusätzliche Konfiguration lesen.

Schritt für Schritt: Erstelle eine Definition und fülle sie aus

Im Shopify Admin (ohne Code)

1. Gehe zu Einstellungen > Benutzerdefinierte Daten.
2. Wähle den Ressourcentyp (Produkte, Kunden, Bestellungen usw.).
3. Klicke auf Definition hinzufügen. Gib einen Namen ein, wähle einen Inhaltstyp und speichere.
4. Ab Shopifys Spring '26 Edition kannst du auch Metafields direkt von Kunden-, Bestell- und Sammlungsseiten aus erstellen, ohne zuerst zu Einstellungen zu navigieren.
5. Öffne ein beliebiges Produkt (oder eine andere Ressource) und scrolle zum Abschnitt Metafields, um Werte einzugeben.

Spring '26 führte auch die Möglichkeit ein, bis zu 50 Metafields direkt auf Produkt-, Kunden- und Bestellungsseiten zu fixieren, damit dein Team kritische Daten sehen und bearbeiten kann, ohne auf eine separate Seite zu klicken.

Über die GraphQL Admin API

Für Massen-Operationen oder automatisierte Pipelines verwende metafieldDefinitionCreate (um das Schema zu erstellen) gefolgt von metafieldsSet (um Werte zu schreiben). Die metafieldsSet Mutation ermöglicht maximal 25 Metafields pro Aufruf, mit maximaler Gesamtgröße des Request-Payload von 10 MB, und die Operation ist atomar: Keine Änderungen bleiben bestehen, wenn ein Fehler auftritt.

Eine minimale Definition-Mutation sieht so aus:

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      namespace
    }
    userErrors {
      field
      message
    }
  }
}

Mit Variablen:

{
  "definition": {
    "name": "Material",
    "namespace": "custom",
    "key": "material",
    "type": "list.single_line_text_field",
    "ownerType": "PRODUCT",
    "useAsCollectionCondition": true
  }
}

Das Setzen von useAsCollectionCondition: true bedeutet, dass du dieses Feld sofort verwenden kannst, um Smart-Collection-Regeln zu steuern, ohne zusätzliche Schritte erforderlich.

Für Massen-Katalog-Updates ermöglichen Tools wie Matrixify dir, Metafield-Werte aus einer CSV zu importieren, ohne API-Code zu schreiben.

Metafields auf deinem Storefront anzeigen

Hier bleiben die meisten Merchants stecken. Das Erstellen der Definition führt nicht dazu, dass das Feld auf deinem Storefront angezeigt wird. Du musst es verbinden.

Option 1: Dynamische Quellen im Theme-Editor (ohne Code)

Wenn du mit einem Online Store 2.0-kompatiblen Theme (Dawn, Horizon oder einem JSON-Template-Theme) arbeitest, öffne den Theme-Editor, füge einen Abschnitt oder Block hinzu oder klicke auf einen, der dynamische Quellen unterstützt, und klicke auf das Symbol Dynamische Quelle verbinden. Du kannst auf diese Weise bis zu 20 Metafields zu einem einzigen Template hinzufügen.

Option 2: Liquid (vollständige Kontrolle)

Die Liquid-Syntax ist:

{{ product.metafields.namespace.key }}

Für ein Rich-Text-Metafield verwende den metafield_tag Filter, um HTML-Formatierung korrekt zu rendern:

{{ product.metafields.custom.care_instructions | metafield_tag }}

Für eine Image-Datei-Referenz:

{{ product.metafields.custom.hero_image.value | image_url: width: 800 | image_tag }}

Ein wichtiger Hinweis: Wenn dein Metafield-Schlüssel size, first oder last ist, verwende stattdessen Square-Bracket-Notation: product.metafields.namespace["size"]. Diese Wörter sind auch eingebaute Liquid-Filter, und Punkt-Notation wendet den Filter an, anstatt das Metafield zu holen, wenn der Schlüssel fehlt.

Für die fünf Anwendungsfälle mit höchster Wirkung auf Produktseiten (benutzerdefinierte Inhalts-Tabs, Produkt-Badges, Spezifikationstabellen, herunterladbare PDFs und verwandte Produktlisten) benötigt jeder eine eigene Definition und einen entsprechenden Liquid-Block in deinem Theme's sections/main-product.liquid.

Was sich 2026 geändert hat: Die Updates, die wichtig sind

Spring '26 (angekündigt Mitte 2026):

• Cart-Metafields werden zu Bestellungen übertragen. Aktiviere cartToOrderCopyable auf einer Order-Metafield-Definition und jeden Cart-Metafield-Wert aus dem Checkout wird automatisch in die resultierende Order kopiert. Dies ist ein großer Schritt für Post-Purchase-Logik in Shopify Flow.
• Erstelle Metafields ohne die Ressourcenseite zu verlassen. Du musst nicht mehr zu Einstellungen > Benutzerdefinierte Daten navigieren, um eine neue Definition hinzuzufügen; du kannst es direkt von jedem Kunden-, Bestell- oder Sammlungsdatensatz aus tun.
• Fixiere bis zu 50 Metafields auf Produkt-, Kunden- und Bestell-Admin-Seiten.
• ShopifyQL Dot-Syntax-Filterung. Metafields werden jetzt in ShopifyQL mit Dot-Syntax als Dimensionen und Filter unterstützt, verfügbar über die Analytics API und den Online-Editor. Das bedeutet, du kannst deine Analysberichte nach jedem benutzerdefinierten Feld segmentieren, das du definiert hast.
• Einfachere GraphQL API. Die Spring '26 Edition brachte eine vereinfachte Read/Write-Schnittstelle für Metafields und Metaobjects, reduziert Boilerplate in App-Code.
• Shop User-Metafields sind während des Checkouts lesbar über Shopify Functions, ermögliche es dir, Käufer-spezifische Checkout-Anpassungen basierend auf gespeicherten Kundendaten zu erstellen.

Admin GraphQL API 2026-07 (Release Candidate ab Juli 2026):

• Metafields auf Bestandsübertragungen. Du kannst jetzt Metafields direkt auf Bestandsübertragungen definieren und setzen, um Chargennummern, Lieferantencodes, Frachtdetails oder ERP-Referenz-IDs zu speichern, ohne einen separaten metafieldsSet Aufruf zu benötigen.

Winter '26:

• Metafields und Metaobjects werden schneller auf Storefronts gerendert, unterstützen umfangreichere Query-Filterung und ermöglichen höhere Eintragslimits als frühere API-Versionen.

Oktober 2025 (API 2025-10):

• Added article_reference und list.article_reference Typen, die es Merchants ermöglichen, formale Produkt-zu-Artikel-Links für Content-getriebene SEO und Editorial-Commerce-Workflows zu erstellen.

Metafields vs. Metaobjects: Wann verwendet man welche

Ein Metafield speichert ein einzelnes Datenelement auf einer existierenden Ressource. Ein Metaobject ist ein wiederverwendbarer, eigenständiger Content-Eintrag mit eigenem Multi-Field-Schema und eigenem Admin-UI. Verwende Metafields, wenn die Daten zu einem bestimmten Produkt (oder Bestellung, oder Kunde) gehören und nur dort Sinn machen. Verwende Metaobjects, wenn der Inhalt über mehrere Produkte wiederverwendet wird, wie ein gemeinsamer Größenleitfaden, eine Markengeschichte oder ein Lieferantenprofil.

Du verbindest die beiden mit einem metaobject_reference Metafield: Das Feld auf dem Produkt zeigt auf den Metaobject-Eintrag, und das Aktualisieren des Eintrags aktualisiert automatisch jedes Produkt, das auf ihn verweist.

Metafields und die AI Shopping Layer

Dies ist der Winkel, den die meisten Merchants 2026 verpassen. Shopifys Summer '26 "Everywhere Edition" machte das Universal Commerce Protocol (UCP) standardmäßig auf jedem Store aktiv und ermöglichte es AI Shopping Agents, deinen Katalog zu lesen. Die strukturierten Daten in deinen Metafields (Specs, Zutaten, Zertifizierungen, Materialien) sind genau das, was AI-Agenten und Googles Rich-Result-Parser konsumieren, um zu entscheiden, ob sie dein Produkt anzeigen.

Kategorie-Metafields verdienen hier besondere Aufmerksamkeit. Dies sind Produktattribute, die zu einer bestimmten Produktkategorie abgebildet werden und Produkte auf deiner Website, auf Marktplätzen und in Suchmaschinen auffindbar machen. Wenn du die richtige Produktkategorie in Shopify zuweist, werden standardmäßig Kategorie-Metafield-Einträge vorausgefüllt (zum Beispiel gibt dir eine Shirts-Kategorie Größe, Ausschnitt, Ärmellänge, Stoff, Geschlecht und Farbfelder). Fülle sie konsistent aus und du versorgst strukturierte Daten gleichzeitig an jeden nachgelagerten Channel.

Wenn du Produktbeschreibungen zur besseren Lesbarkeit in separate Metafields aufgeteilt hast, beachte, dass du derzeit nicht mehr als ein Shopify-Feld zu einem einzigen Shopify Catalog Beschreibungsfeld abbilden kannst. Der Workaround ist, ein kombiniertes Metafield zu erstellen, das deine Beschreibung und wichtige Metafield-Daten verkettet, und dann dieses einzelne Feld dem Katalog abbilden.

Governance: Der Teil, den die meisten Teams überspringen

Metafields sind einfach zu erstellen und sehr leicht ausarten zu lassen. Ein paar Regeln, die teure Aufräumarbeiten später verhindern:

• Dokumentiere dein Schema. Verwalte ein Referenzblatt (eine einfache Tabelle funktioniert), das jeden Namespace, Schlüssel, Typ, Owner-Ressource und welche App oder welches Team die Definition besitzt, aufzeichnet.
• Verwende Standard-Definitionen, wenn eine existiert. Sie sind interoperabel, auto-validiert und immun gegen Benennungskollisionen.
• Ändere nie einen Typ, nachdem du Live-Daten hast. Eine Migration von date_time zu money zum Beispiel macht alle existierenden Werte ungültig. Plane Typen korrekt von vornherein.
• Namespace-Disziplin. Verwende unterschiedliche Namespaces pro App oder Team (logistics, marketing, compliance) damit du auditieren und per Namespace bereinigen kannst, ohne unabhängige Felder zu beeinflussen.
• Schreib-Operationen als atomar testen. Die metafieldsSet Mutation ist atomar: Entweder alle 25 Werte in einem einzigen Aufruf erfolgreich, oder keiner. Strukturiere deine Massen-Importe um diese Garantie herum.

Wenn du Hilfe bei der Strukturierung eines Metafield-Schemas für einen komplexen Katalog oder der Integration von Metafields in einen benutzerdefinierten Storefront benötigst, siehe die Shopify Developer Services Seite oder die Shopify Theme Developer Arbeit, die ich mit Merchants mache.

Schnellreferenz: Liquid-Syntax Spickzettel

Metafields sind eines jener Features, bei dem zwei Stunden, die Grundlagen zu lernen, Wochen Workarounds später sparen. Definiere dein Schema sorgfältig, verwende Standard-Definitionen überall dort, wo sie existieren, und verbinde deine Felder mit deinem Storefront und deiner Analyseschicht. Die 2026-Updates, besonders Cart-zu-Order-Kopieren und ShopifyQL-Filterung, bedeuten, dass deine Metafield-Daten actionabler sind als je zuvor.