Shopify Metavelden: Complete Setup- en Displaygids

Een Shopify metaveld is een aangepast sleutel-waardepaar dat je toevoegt aan een store-resource (product, collectie, bestelling, klant, variant en meer) om gegevens op te slaan die Shopify's core schema niet standaard biedt. Je definieert het gegevenstype, stelt validatie in en toont de waarde vervolgens overal: je storefront via Liquid, je analytics via ShopifyQL, je checkout via Shopify Functions, of je externe systemen via de GraphQL Admin API. Die drie-staps-cyclus (definiëren, vullen, weergeven) is het volledige mentale model dat je nodig hebt.

Belangrijkste punten

• Een metaveld wordt geïdentificeerd door drie dingen: owner resource, namespace en key. Verander er een van en je verwijst naar een ander veld.
• Shopify's Spring '26 en Summer '26 Editions brachten verschillende metaveld-upgrades: pin maximaal 50 velden op admin-pagina's, winkelwagen-metavelden die naar orders worden overgedragen, metavelden op voorraadbijdragen en ShopifyQL dot-syntax filtering.
• De Admin GraphQL API 2026-07 release candidate stelt je in staat metavelden rechtstreeks op voorraadbijdragen te definiëren en in te stellen zonder een aparte metafieldsSet aanroep.
• Het maken van een definitie geeft niets weer op je storefront. Je moet het veld nog steeds verbinden via een dynamische bron in de thema-editor, of zelf de Liquid schrijven.
• Standaarddefinities (verzorginginstructies, ingrediënten, maat, ISBN, enz.) zijn het snelste pad omdat ze vooraf geconfigureerd, theme-compatibel en app-interoperabel zijn uit de box.

Wat is precies een Shopify metaveld?

Metavelden stellen je in staat aanvullende informatie aan een Shopify-resource toe te voegen, zoals een product of collectie. De gegevens kunnen specificaties, matenkaarten, downloadbare documenten, releasedatums, afbeeldingen of onderdeelnummers zijn. Elk metaveld slaat een waarde op samen met typeinformatie en wordt geïdentificeerd door de eigenaar-resource, namespace en key.

Beschouw de namespace als een mapnaam en de key als een bestandsnaam in die map. Een product-metaveld met namespace: custom en key: material is volledig gescheiden van een met namespace: specs en key: material, hoewel beide op hetzelfde product leven.

De drie eigendomsmodellen

Als je eigenaarschap begrijpt, voorkom je onopzettelijk gegevens te overschrijven die je niet wilde aanraken.

Merchant-eigendom metavelden gebruiken een niet-gereserveerde namespace (zoals custom, specs of inventory). Alle geïnstalleerde apps kunnen ze lezen en schrijven. Ze zijn ideaal voor gedeelde gegevens die meerdere apps consumeren.

App-eigendom metavelden gebruiken de gereserveerde $app namespace-prefix. De eigenaar-app controleert de structuur en waarden, die standaard alleen-lezen zijn in de admin. Gebruik deze wanneer een app de gezaghebbende bron voor een stuk gegevens is.

App-data metavelden zijn gebonden aan een specifieke app-installatie en zijn volledig verborgen voor de Shopify admin. Ze leven op de AppInstallation resource en kunnen alleen door de eigenaar-app via GraphQL of via het app object in Liquid worden benaderd. Dit zijn voor interne app-status die nooit naar handelaren mag oppervlakken.

Shopify onderhoudt ook Shopify-gereserveerde namespaces (met prefix shopify--) voor platform-beheerde velden zoals standaarddefinities.

Metaveld gegevenstypes: een praktische kaart

Shopify groepeert types in categorieën. Het kiezen van het juiste type is belangrijk omdat het validatie afdwingt, bepaalt hoe Liquid de waarde weergeeft en bepaalt welke filters van toepassing zijn.

Tekst

• single_line_text_field, product badges, korte labels, ISO-codes
• multi_line_text_field, ingrediëntenlijsten, verzorginginstructies (regeleinden behouden)
• rich_text, geformatteerde langere inhoud (koppelingen, vet, lijsten); render met het metafield_tag filter

Getallen en afmetingen

• number_integer, number_decimal
• dimension, volume, weight, elk slaat een numerieke waarde op gekoppeld aan een eenheid; ideaal voor productspecificaties en verzendregels

Datums en tijden

• date, date_time, lanceringsdata, vervaldatums, event-schema's

Referenties

• product_reference, collection_reference, page_reference, variant_reference, koppel één resource aan een ander zonder gegevens te dupliceren
• metaobject_reference, koppel aan een metaobject-vermelding (zie hieronder)
• article_reference en list.article_reference, toegevoegd in de 2025-10 API-release; laat je producten rechtstreeks aan blogposts koppelen voor content-driven commerce en SEO

Andere nuttige types

• boolean, feature flags, "nieuw" toggles, verbergen-van-verkoop markers
• color, hex-gebaseerde kleurwaarden met native swatch-ondersteuning
• url, file_reference, downloadbare PDF's, spec sheets, video's
• json, willekeurige gestructureerde gegevens; nuttig maar moeilijker te valideren en weer te geven

Voor lijsttypen voeg je elk scalair type vooraf met list. (bijvoorbeeld list.single_line_text_field). Deze worden als arrays in Liquid weergegeven en zijn de juiste keuze wanneer een veld meerdere waarden kan bevatten, zoals een lijst met materialen of een reeks ophaallokaties.

Een belangrijke beperking: bij gebruik van de GraphQL Admin API wordt de metaveld-waarde altijd als string ingevoerd en opgeslagen, ongeacht het gedeclareerde type. Shopify behandelt type-coërcie bij lezen.

Metaveld-definities: waarom ze belangrijk zijn

Je kunt een onbewerkt metaveld (zonder definitie) via de API schrijven, maar definities zijn bijna altijd de juiste keuze. Een metaveld-definitie stelt een schema vast dat alle waarden voor die namespace-key-combinatie moeten volgen, inclusief het gegevenstype en validatiebeperkingen. De definitie bepaalt ook toegangsmachtigingen in de GraphQL Admin API, Storefront API en Customer Account API, en bepaalt of het veld kan worden gebruikt voor admin-filtering of als verzamelingsvoorwaarde.

Bouwen met definities betekent:

• Admin UI-ondersteuning. Gedefinieerde velden verschijnen op elke relevante resource's bewerkingspagina zonder aangepaste code.
• Validatie. Ongeldige waarden worden afgevangen voordat ze je storefront beschadigen.
• Filteren. Je kunt een gedefinieerd veld als slimme verzamelingsvoorwaarde of als admin-filter gebruiken.
• Thema-editor detectie. Dynamische bron-kiezers tonen alleen gedefinieerde velden.

Standaarddefinities zijn vooraf gebouwde schema's voor veelvoorkomende use-cases zoals ISBN-nummers, product-ingrediënten en verzorginginstructies. Door ze te gebruiken weten apps en thema's die naar die standaard-namespaces verwijzen al hoe ze je gegevens zonder extra configuratie moeten lezen.

Stap voor stap: een definitie maken en vullen

In de Shopify admin (geen code)

1. Ga naar Instellingen > Aangepaste gegevens.
2. Kies het resourcetype (Producten, Klanten, Bestellingen, enz.).
3. Klik op Definitie toevoegen. Geef het een naam, kies een inhoudstype en sla op.
4. Vanaf Shopify's Spring '26 Edition kun je metavelden ook rechtstreeks van klanten-, bestellingen- en verzamelspagina's maken zonder eerst naar Instellingen te gaan.
5. Open een product (of ander resource) en scroll naar de sectie Metavelden om waarden in te vullen.

Spring '26 introduceerde ook de mogelijkheid om maximaal 50 metavelden op product-, klanten- en bestellingssecties aan te maken zodat je team kritieke velden kan zien en bewerken zonder op een aparte pagina te klikken.

Via de GraphQL Admin API

Voor bulk-bewerkingen of geautomatiseerde pijplijnen, gebruik je metafieldDefinitionCreate (om het schema te maken) gevolgd door metafieldsSet (om waarden te schrijven). De metafieldsSet mutatie staat maximaal 25 metavelden per aanroep toe, met een maximale totale request payload-grootte van 10 MB, en de bewerking is atomair: geen wijzigingen blijven bestaan als er een fout optreedt.

Een minimale definitie-mutatie ziet er als volgt uit:

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

Met variabelen:

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

Als je useAsCollectionCondition: true instelt, kun je dit veld onmiddellijk gebruiken om slimme verzamelingsregels uit te voeren, geen extra stap vereist.

Voor bulk-catalogusupdates kunnen hulpmiddelen zoals Matrixify je metaveld-waarden uit een CSV importeren zonder API-code te schrijven.

Metavelden op je storefront weergeven

Dit is waar de meeste handelaren vast lopen. Het maken van de definitie betekent niet dat het veld op je storefront verschijnt. Je moet het verbinden.

Optie 1: Dynamische bronnen in de thema-editor (geen code)

Als je gebruik maakt van een Online Store 2.0 compatibel thema (Dawn, Horizon of elk JSON-template thema), open je de thema-editor, voeg je een sectie of blok toe dat dynamische bronnen ondersteunt of klikt je op het pictogram dynamische bron verbinden. Je kunt op deze manier maximaal 20 metavelden aan één sjabloon toevoegen.

Optie 2: Liquid (volledige controle)

De Liquid-syntaxis is:

{{ product.metafields.namespace.key }}

Voor een rich text metaveld, gebruik je het metafield_tag filter om HTML-opmaak correct weer te geven:

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

Voor een afbeelding-bestandsreferentie:

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

Eén valkuil: als je metaveld-key size, first of last is, gebruik je in plaats daarvan vierkante haken notatie: product.metafields.namespace["size"]. Deze woorden zijn ook ingebouwde Liquid-filters en dot-notatie past het filter toe in plaats van het metaveld op te halen wanneer de key ontbreekt.

Voor de vijf meest impactvolle product-pagina use-cases (aangepaste content tabs, product badges, spec tables, downloadbare PDF's en gerelateerde productlijsten) heeft elk zijn eigen definitie en een overeenkomstig Liquid-blok nodig in je thema's sections/main-product.liquid.

Wat veranderde in 2026: de updates die belangrijk zijn

Spring '26 (aangekondigd medio 2026):

• Winkelwagen-metavelden worden overgedragen naar orders. Schakel cartToOrderCopyable in op een order metaveld-definitie en elke winkelwagen metaveld-waarde uit checkout wordt automatisch naar de resulterende order gekopieerd. Dit is een grote unlock voor post-purchase logic in Shopify Flow.
• Maak metavelden zonder de resource-pagina te verlaten. Je hoeft niet meer naar Instellingen > Aangepaste gegevens te gaan om een nieuwe definitie toe te voegen; je kunt het inline doen van elke klanten-, bestellingen- of verzamelingsrecord.
• Pin maximaal 50 metavelden op product-, klanten- en bestellingen admin-pagina's.
• ShopifyQL dot-syntax filtering. Metavelden worden nu ondersteund als dimensies en filters in ShopifyQL met dot-syntax, beschikbaar via de Analytics API en de online editor. Dit betekent dat je je analytics-rapporten kunt segmenteren op elk aangepast veld dat je hebt gedefinieerd.
• Vereenvoudigde GraphQL API. De Spring '26 editie bracht een vereenvoudigd lees-schrijf interface voor metavelden en metaobjects, waardoor boilerplate in app-code afneemt.
• Shop User metavelden zijn leesbaar tijdens checkout via Shopify Functions, zodat je checkout-aanpassingen die specifiek zijn voor koper kunnen bouwen op basis van opgeslagen klantgegevens.

Admin GraphQL API 2026-07 (release candidate per juli 2026):

• Metavelden op voorraadbijdragen. Je kunt nu metavelden rechtstreeks op voorraadbijdragen definiëren en instellen om lot-nummers, leverancierscodes, vrachtdetails of ERP-referentie-ID's op te slaan zonder een aparte metafieldsSet aanroep.

Winter '26:

• Metavelden en metaobjects renderen sneller op storefronts, ondersteunen rijkere query-filtering en maken hogere entrylimieten mogelijk dan vorige API-versies.

Oktober 2025 (API 2025-10):

• Added article_reference en list.article_reference types, waardoor handelaren formele product-naar-artikel links kunnen maken voor content-driven SEO en redactionele commerce-flows.

Metavelden vs. metaobjects: wanneer elk te gebruiken

Een metaveld slaat een enkel stukje gegevens op een bestaande resource op. Een metaobject is een herbruikbare, zelfstandige content-vermelding met zijn eigen schema, meerdere velden en zijn eigen admin UI. Gebruik metavelden wanneer de gegevens bij en alleen op een specifiek product (of bestelling, of klant) horen. Gebruik metaobjects wanneer de inhoud herbruikbaar is op meerdere producten, zoals een gedeelde matenkaart, een merk verhaal of een leveranciersprofiel.

Je verbindt de twee met een metaobject_reference metaveld: het veld op het product wijst naar de metaobject-vermelding en het bijwerken van de vermelding werkt automatisch elk product dat ernaar verwijst bij.

Metavelden en de AI-winkellaag

Dit is de hoek die de meeste handelaren in 2026 missen. Shopify's Summer '26 "Everywhere Edition" maakte het Universal Commerce Protocol (UCP) standaard actief op elke store, waardoor AI-winkelagenten je catalogus kunnen lezen. De gestructureerde gegevens in je metavelden (specs, ingrediënten, certificeringen, materialen) is precies wat AI-agenten en Google's rich-result parsers consumeren wanneer ze bepalen of je product wordt weergegeven.

Categoriemetavelden verdienen hier speciale aandacht. Dit zijn product-attributen die kaart naar een specifieke productcategorie en helpen producten beter detecteerbaar te maken op je site, op marktplaatsen en op zoekmachines. Wanneer je de juiste productcategorie in Shopify toewijst, krijg je standaard categoriemetaveld-vermeldingen vooraf ingevuld (bijvoorbeeld een Shirts-categorie geeft je maat, halsuitsnijding, mouwlengte, stof, geslacht en kleurvelden). Vul ze consistent in en je voert gestructureerde gegevens naar elk downstream kanaal tegelijk.

Als je gebroken product-beschrijvingen in afzonderlijke metavelden hebt verdeeld voor leesbaarheid, let op dat je momenteel niet meer dan één Shopify-veld aan een enkel Shopify Catalog beschrijvingsveld kunt toewijzen. De workaround is het maken van een gecombineerd metaveld dat je beschrijving en key-metaveld-gegevens samenvoegt, en dan dat enige veld aan de catalogus toe te wijzen.

Governance: het onderdeel dat de meeste teams overslaan

Metavelden zijn eenvoudig te maken en erg eenvoudig om te laten verspreiden. Een paar regels die dure opschoning later voorkomen:

• Documenteer je schema. Behoud een referentieblad (een eenvoudig spreadsheet werkt) dat elke namespace, key, type, eigenaar-resource en welke app of team de definitie bezit opneemt.
• Gebruik standaarddefinities wanneer er één bestaat. Ze zijn interoperabel, auto-gevalideerd en immuun voor naamconflicten.
• Verander nooit een type nadat je live gegevens hebt. Migratie van date_time naar money maakt bijvoorbeeld alle bestaande waarden ongeldig. Plan types correct vooraf.
• Namespace discipline. Gebruik verschillende namespaces per app of team (logistics, marketing, compliance) zodat je op namespace kunt controleren en opschonen zonder gerelateerde velden te beïnvloeden.
• Test schrijven als atomaire bewerkingen. De metafieldsSet mutatie is atomair: ofwel slagen alle 25 waarden in een enkele aanroep, ofwel geen. Structureer je bulk imports rond deze garantie.

Als je hulp nodig hebt bij het ontwerpen van een metaveld-schema voor een complexe catalogus of het integreren van metavelden in een aangepaste storefront, zie de Shopify developer services pagina of het Shopify theme developer werk dat ik met handelaren doe.

Snelle referentie: Liquid-syntaxis spiekbrief

Metavelden zijn een van die functies waarbij twee uur de fundamentals leren weken omzeilen bespaard. Definieer je schema zorgvuldig, gebruik standaarddefinities waar ze bestaan, en verbind je velden zowel met je storefront als je analytics-laag. De 2026 updates, vooral cart-to-order copying en ShopifyQL filtering, betekenen dat je metaveld-gegevens meer actiebaar zijn dan ooit.