Shopify Metafields: Guida Completa a Setup e Visualizzazione

Un metafield Shopify è un campo chiave-valore personalizzato che alleghi a una risorsa del negozio (prodotto, collezione, ordine, cliente, variante e altro) per memorizzare dati che lo schema nativo di Shopify non fornisce. Definisci il tipo di dato, applica la convalida e poi visualizza il valore ovunque: nella vetrina tramite Liquid, nell'analisi tramite ShopifyQL, al checkout tramite Shopify Functions, o nei tuoi sistemi esterni tramite GraphQL Admin API. Questo ciclo a tre passaggi (definire, compilare, visualizzare) è l'intero modello mentale di cui hai bisogno.

Punti chiave

• Un metafield è identificato da tre cose: risorsa proprietaria, namespace e chiave. Cambia uno di questi e stai facendo riferimento a un campo diverso.
• Le Spring '26 e Summer '26 Editions di Shopify hanno spedito diversi aggiornamenti ai metafield: fissa fino a 50 campi nelle pagine admin, metafield del carrello che si trasferiscono agli ordini, metafield nei trasferimenti di inventario e filtraggio della sintassi con punto ShopifyQL.
• La release candidate dell'Admin GraphQL API 2026-07 ti permette di definire e impostare metafield direttamente sui trasferimenti di inventario senza una chiamata metafieldsSet separata.
• Creare una definizione non visualizza nulla nella tua vetrina. Hai comunque bisogno di collegare il campo tramite un'origine dinamica nell'editor del tema, o scrivere il Liquid tu stesso.
• Le definizioni standard (istruzioni di cura, ingredienti, dimensioni, ISBN, ecc.) sono il percorso più veloce perché sono pre-configurate, compatibili con i temi e interoperabili con le app fin da subito.

Che cos'è esattamente un metafield Shopify?

I metafield ti permettono di allegare informazioni aggiuntive a una risorsa Shopify, come un prodotto o una collezione. I dati possono essere specifiche, tabelle di taglie, documenti scaricabili, date di uscita, immagini o numeri di parte. Ogni metafield memorizza un valore insieme alle informazioni sul tipo ed è identificato dalla sua risorsa proprietaria, namespace e chiave.

Pensa al namespace come a un nome di cartella e alla chiave come al nome del file all'interno di quella cartella. Un metafield di prodotto con namespace: custom e key: material è completamente separato da uno con namespace: specs e key: material, anche se entrambi risiedono sullo stesso prodotto.

I tre modelli di proprietà

Comprendere la proprietà ti impedisce di sovrascrivere accidentalmente dati che non intendevi toccare.

Metafield di proprietà del commerciante utilizzano qualsiasi namespace non riservato (come custom, specs o inventory). Tutte le app installate possono leggerli e scriverli. Sono ideali per i dati condivisi che più app consumano.

Metafield di proprietà dell'app utilizzano il prefisso namespace riservato $app. L'app proprietaria controlla la struttura e i valori, che sono di sola lettura nell'admin per impostazione predefinita. Usali quando un'app è la fonte autorevole di un dato.

Metafield app-data sono legati a un'installazione di app specifica e sono completamente nascosti dall'admin di Shopify. Risiedono sulla risorsa AppInstallation e sono accessibili solo dall'app proprietaria tramite GraphQL o tramite l'oggetto app in Liquid. Questi sono per lo stato interno dell'app che non dovrebbe mai essere visibile ai commercianti.

Shopify mantiene anche namespace riservati da Shopify (con prefisso shopify--) per campi gestiti dalla piattaforma come le definizioni standard.

Tipi di dati metafield: una mappa pratica

Shopify raggruppa i tipi in categorie. Scegliere il tipo giusto è importante perché applica la convalida, controlla come Liquid esegue il rendering del valore e determina quali filtri si applicano.

Testo

• single_line_text_field, badge di prodotto, etichette brevi, codici ISO
• multi_line_text_field, elenchi di ingredienti, istruzioni di cura (newline preservati)
• rich_text, contenuti lunghi formattati (intestazioni, grassetto, elenchi); esegui il rendering con il filtro metafield_tag

Numeri e misurazioni

• number_integer, number_decimal
• dimension, volume, weight, ciascuno memorizza un valore numerico accoppiato a un'unità; ideale per specifiche di prodotto e regole di spedizione

Date e orari

• date, date_time, date di lancio, date di scadenza, calendari di eventi

Riferimenti

• product_reference, collection_reference, page_reference, variant_reference, collega una risorsa a un'altra senza duplicare i dati
• metaobject_reference, collegamento a una voce di metaobject (vedi sotto)
• article_reference e list.article_reference, aggiunti nella release API 2025-10; ti permettono di collegare direttamente i prodotti ai post del blog per il commercio basato su contenuti e la SEO

Altri tipi utili

• boolean, flag di funzionalità, interruttori "nuovo arrivo", marcatori nascondi-dalla-vendita
• color, valori di colore basati su hex con supporto nativo dei campioni
• url, file_reference, PDF scaricabili, schede tecniche, video
• json, dati strutturati arbitrari; utili ma più difficili da convalidare e visualizzare

Per tipi di elenco, aggiungi il prefisso list. a qualsiasi tipo scalare (ad esempio, list.single_line_text_field). Questi vengono visualizzati come array in Liquid e sono la scelta giusta ogni volta che un campo può contenere più valori, come un elenco di materiali o una serie di ubicazioni di ritiro.

Un vincolo importante: quando si utilizza l'API GraphQL Admin, il valore del metafield viene sempre inserito e memorizzato come stringa, indipendentemente dal tipo dichiarato. Shopify gestisce la coercizione del tipo alla lettura.

Definizioni di metafield: perché sono importanti

Puoi scrivere un metafield grezzo (senza definizione) tramite l'API, ma le definizioni sono quasi sempre la scelta giusta. Una definizione di metafield stabilisce uno schema che tutti i valori per quella combinazione namespace-key devono seguire, incluso il tipo di dato e i vincoli di convalida. La definizione controlla anche i permessi di accesso tramite GraphQL Admin API, Storefront API e Customer Account API, e determina se il campo può essere utilizzato per il filtraggio admin o come condizione di collezione.

Costruire con le definizioni significa:

• Supporto UI Admin. I campi definiti vengono visualizzati nella pagina di modifica di ogni risorsa pertinente senza codice personalizzato.
• Convalida. I valori non validi vengono catturati prima di corrompere la tua vetrina.
• Filtraggio. Puoi utilizzare un campo definito come condizione di raccolta intelligente o come filtro admin.
• Scoperta dell'editor del tema. I selettori di origine dinamica mostrano solo i campi definiti.

Le definizioni standard sono schemi pre-costruiti per casi d'uso comuni come numeri ISBN, ingredienti di prodotto e istruzioni di cura. Usarli significa che le app e i temi che fanno riferimento a quegli namespace standard sapranno già come leggere i tuoi dati senza configurazione aggiuntiva.

Passo dopo passo: crea una definizione e compilala

Nell'admin di Shopify (senza codice)

1. Vai a Impostazioni > Dati personalizzati.
2. Scegli il tipo di risorsa (Prodotti, Clienti, Ordini, ecc.).
3. Fai clic su Aggiungi definizione. Assegnagli un nome, scegli un tipo di contenuto e salva.
4. A partire dalla Spring '26 Edition di Shopify, puoi anche creare metafield direttamente dalle pagine dei clienti, degli ordini e delle collezioni senza navigare prima a Impostazioni.
5. Apri qualsiasi prodotto (o altra risorsa) e scorri fino alla sezione Metafield per compilare i valori.

La Spring '26 ha anche introdotto la possibilità di fissare fino a 50 metafield nelle sezioni prodotti, clienti e ordini in modo che il tuo team possa visualizzare e modificare i campi più importanti senza fare clic su una pagina separata.

Tramite GraphQL Admin API

Per operazioni in blocco o pipeline automatizzate, usa metafieldDefinitionCreate (per creare lo schema) seguito da metafieldsSet (per scrivere i valori). La mutazione metafieldsSet consente un massimo di 25 metafield per chiamata, con una dimensione massima del payload della richiesta totale di 10 MB, e l'operazione è atomica: nessuna modifica persiste se si verifica un errore.

Una mutazione di definizione minima ha questo aspetto:

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

Con variabili:

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

Impostare useAsCollectionCondition: true significa che puoi usare immediatamente questo campo per alimentare regole di raccolta intelligente, nessun passaggio aggiuntivo richiesto.

Per gli aggiornamenti del catalogo in blocco, strumenti come Matrixify ti permettono di importare valori di metafield da un CSV senza scrivere alcun codice API.

Visualizzazione dei metafield nella tua vetrina

Questo è il punto in cui la maggior parte dei commercianti rimane bloccata. Creare la definizione non fa apparire il campo nella tua vetrina. Hai bisogno di collegarlo.

Opzione 1: Origine dinamica nell'editor del tema (senza codice)

Se sei su un tema compatibile con Online Store 2.0 (Dawn, Horizon o qualsiasi tema con modello JSON), apri l'editor del tema, aggiungi o fai clic su una sezione o blocco che supporta origini dinamiche e fai clic sull'icona connetti origine dinamica. Puoi aggiungere fino a 20 metafield a un singolo modello in questo modo.

Opzione 2: Liquid (controllo completo)

La sintassi Liquid è:

{{ product.metafields.namespace.key }}

Per un metafield di testo ricco, usa il filtro metafield_tag per eseguire correttamente il rendering della formattazione HTML:

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

Per un riferimento a un file immagine:

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

Un avvertimento: se la chiave del metafield è size, first o last, usa la notazione tra parentesi quadre invece della notazione con punto: product.metafields.namespace["size"]. Queste parole sono anche filtri Liquid incorporati e la notazione con punto applicherà il filtro piuttosto che recuperare il metafield quando manca la chiave.

Per i cinque casi d'uso della pagina prodotto con il massimo impatto (schede di contenuto personalizzate, badge di prodotto, tabelle di specifiche, PDF scaricabili ed elenchi di prodotti correlati), ognuno richiede la sua propria definizione e un blocco Liquid corrispondente nel file sections/main-product.liquid del tuo tema.

Cosa è cambiato nel 2026: gli aggiornamenti che contano

Spring '26 (annunciata a metà 2026):

• I metafield del carrello si trasferiscono agli ordini. Abilita cartToOrderCopyable su una definizione di metafield ordine e qualsiasi valore di metafield del carrello dal checkout viene automaticamente copiato nell'ordine risultante. Questo è uno sblocco importante per la logica post-acquisto in Shopify Flow.
• Crea metafield senza lasciare la pagina della risorsa. Non è più necessario navigare a Impostazioni > Dati personalizzati per aggiungere una nuova definizione; puoi farlo inline da qualsiasi record di cliente, ordine o collezione.
• Fissa fino a 50 metafield sulle pagine admin di prodotti, clienti e ordini.
• Filtraggio della sintassi con punto ShopifyQL. I metafield sono ora supportati come dimensioni e filtri in ShopifyQL con sintassi punto, disponibile tramite l'API Analytics e l'editor online. Ciò significa che puoi segmentare i tuoi report di analisi in base a qualsiasi campo personalizzato che hai definito.
• API GraphQL semplificata. La Spring '26 Edition ha fornito un'interfaccia di lettura/scrittura semplificata per metafield e metaobject, riducendo il boilerplate nel codice dell'app.
• I metafield dell'utente del negozio sono leggibili durante il checkout tramite Shopify Functions, permettendoti di costruire personalizzazioni di checkout specifiche dell'acquirente in base ai dati dei clienti memorizzati.

Admin GraphQL API 2026-07 (release candidate a partire da luglio 2026):

• Metafield sui trasferimenti di inventario. Ora puoi definire e impostare metafield direttamente sui trasferimenti di inventario per memorizzare numeri di lotto, codici fornitore, dettagli di trasporto o ID di riferimento ERP senza una chiamata metafieldsSet separata.

Winter '26:

• I metafield e i metaobject vengono visualizzati più velocemente nelle vetrine, supportano filtri di query più ricchi e consentono limiti di voce più elevati rispetto alle versioni API precedenti.

Ottobre 2025 (API 2025-10):

• Aggiunti i tipi article_reference e list.article_reference, consentendo ai commercianti di creare collegamenti formali prodotto-articolo per flussi di SEO basati su contenuti e commercio editoriale.

Metafield vs. metaobject: quando usare quale

Un metafield memorizza un singolo pezzo di dato su una risorsa esistente. Un metaobject è una voce di contenuto autonoma e riutilizzabile con il suo schema multi-campo e la sua UI admin. Usa i metafield quando i dati appartengono a e hanno senso solo su uno specifico prodotto (o ordine o cliente). Usa i metaobject quando il contenuto viene riutilizzato su più prodotti, come una guida alle taglie condivisa, una storia del marchio o un profilo del fornitore.

Colleghi i due con un metafield metaobject_reference: il campo sul prodotto punta alla voce del metaobject e l'aggiornamento della voce aggiorna automaticamente ogni prodotto che la riferisce.

Metafield e il livello di shopping AI

Questo è l'angolo che la maggior parte dei commercianti sta perdendo nel 2026. La "Everywhere Edition" di Shopify Summer '26 ha reso il Universal Commerce Protocol (UCP) attivo per impostazione predefinita in ogni negozio, permettendo agli agenti di shopping AI di leggere il tuo catalogo. I dati strutturati all'interno dei tuoi metafield (specifiche, ingredienti, certificazioni, materiali) sono esattamente quello che gli agenti AI e i parser dei risultati ricchi di Google consumano quando decidono se far emergere il tuo prodotto.

I metafield di categoria meritano attenzione speciale qui. Questi sono attributi di prodotto che si mappano a una specifica categoria di prodotto e aiutano a rendere i prodotti più individuabili nel tuo sito, nei marketplace e nei motori di ricerca. Quando assegni la giusta categoria di prodotto in Shopify, ottieni voci di metafield di categoria predefinite pre-compilate (ad esempio, una categoria Shirts ti offre campi per dimensione, colletto, lunghezza delle maniche, tessuto, genere e colore). Compilali in modo coerente e stai alimentando dati strutturati a ogni canale downstream simultaneamente.

Se hai diviso le descrizioni dei prodotti in metafield separati per leggibilità, nota che attualmente non puoi mappare più di un campo Shopify a un singolo campo di descrizione del Shopify Catalog. La soluzione alternativa è creare un metafield combinato che concatena la tua descrizione e i dati di metafield chiave, quindi mappare quel singolo campo al catalogo.

Governance: la parte che la maggior parte dei team salta

I metafield sono facili da creare e molto facili da far proliferare. Alcune regole che prevengono la pulizia costosa in seguito:

• Documenta il tuo schema. Mantieni un foglio di riferimento (un semplice foglio di calcolo funziona) che registra ogni namespace, chiave, tipo, risorsa proprietaria e quale app o team possiede la definizione.
• Usa le definizioni standard ogni volta che ne esiste una. Sono interoperabili, convalidate automaticamente e immuni da collisioni di denominazione.
• Non cambiare mai un tipo dopo aver creato dati live. La migrazione da date_time a money, ad esempio, rende tutti i valori esistenti non validi. Pianifica correttamente i tipi in anticipo.
• Disciplina dello namespace. Usa namespace distinti per app o team (logistics, marketing, compliance) in modo da poter controllare e pulire per namespace senza influenzare campi non correlati.
• Testa le scritture come operazioni atomiche. La mutazione metafieldsSet è atomica: o tutti i 25 valori in una singola chiamata hanno successo, o nessuno. Struttura i tuoi importazioni in blocco intorno a questa garanzia.

Se hai bisogno di aiuto nell'architettura di uno schema metafield per un catalogo complesso o nell'integrazione di metafield in una vetrina personalizzata, consulta la pagina servizi di sviluppo Shopify o il lavoro sviluppatore di temi Shopify che faccio con i commercianti.

Riferimento rapido: foglio di aiuto della sintassi Liquid

I metafield sono una di quelle funzionalità in cui spendere due ore per imparare i fondamenti ti fa risparmiare settimane di workaround in seguito. Definisci il tuo schema con attenzione, usa le definizioni standard ovunque esistano, e collega i tuoi campi sia alla tua vetrina che al tuo livello di analisi. Gli aggiornamenti del 2026, in particolare la copia da carrello a ordine e il filtraggio ShopifyQL, significano che i dati del tuo metafield sono più utilizzabili che mai.