Un cliente ordina una tazza regalo, digita "Happy Birthday, Sam!" in un campo di personalizzazione e si aspetta che quel messaggio arrivi alla persona che stamperà o confezionerà l'ordine. Il prodotto stesso non è cambiato. Non è stata creata alcuna nuova variante o SKU. Il messaggio appartiene a quel specifico articolo acquistato, e Shopify ha bisogno di un posto affidabile per trasportarlo dalla pagina del prodotto al carrello e all'ordine.

Quel posto è una proprietà della voce Shopify. La funzione assomiglia a un semplice campo personalizzato, ma i problemi di produzione di solito compaiono più tardi, quando un'integrazione aggiorna una riga del carrello, un sistema di ordini legge i dati, o i metadati privati diventano inaspettatamente visibili ai clienti. Comprendere l'intero ciclo di vita, dalla cattura all'elaborazione downstream, è più utile che trattare le proprietà come testo di personalizzazione statico.

Indice dei contenuti

Che cosa sono realmente le proprietà della voce Shopify

Una proprietà di articolo è metadati personalizzati in coppia chiave-valore allegati a una riga di carrello o a un articolo di ordine. La chiave identifica il campo, ad esempio Engraving, e il valore contiene i dati inviati o generati, ad esempio Happy Birthday, Sam!. Shopify documenta le proprietà come un oggetto di coppie chiave-valore associate a un articolo del carrello, e la sua documentazione del tema descrive la convenzione di denominazione del modulo prodotto utilizzata per inviarle. La documentazione della riga articolo di Shopify identifica anche la personalizzazione, l'incisione, i monogrammi e i caricamenti di file come usi pratici.

La distinzione importante è la proprietà. Una proprietà appartiene alla riga, non al record del catalogo prodotti e non al carrello nel suo insieme. Se un cliente ha due copie della stessa tazza con messaggi diversi, ogni riga ha bisogno della propria serie di proprietà. I metadati viaggiano insieme al prodotto acquistato piuttosto che diventare un'opzione del prodotto.

Cosa le proprietà non sono

Le proprietà degli articoli di riga non sono varianti. Una variante rappresenta una scelta di catalogo come una dimensione o un colore ufficiale e può influenzare l'inventario, i prezzi e il merchandising. Una proprietà acquisisce informazioni aggiuntive che accompagnano un articolo selezionato.

Non sono neppure metafield. I metafield sono campi di dati strutturati associati alle risorse di Shopify come prodotti, clienti o ordini. Una proprietà di articolo è più strettamente legata al singolo articolo nella transazione.

Nella rappresentazione del carrello di Shopify, i dati appaiono attraverso il campo properties. Nei dati dell'ordine, gli sviluppatori lavorano con le proprietà o gli attributi della riga articolo corrispondente, a seconda della superficie API. Questa distinzione è importante quando si creano regole di evasione, visualizzazioni di ordini o integrazioni.

Regola pratica: Se il valore descrive cosa un cliente desidera fare con un articolo acquistato, inizia valutando una proprietà di articolo di riga. Se descrive il record del prodotto o del cliente più ampiamente, considera un modello di dati diverso di Shopify.

Come le proprietà degli articoli di riga vengono acquisite nel carrello

Shopify supporta due modelli di acquisizione comuni. Un tema può inviare campi attraverso il modulo prodotto, oppure una vetrina personalizzata può inviare dati di proprietà attraverso una richiesta di carrello. Entrambi gli approcci allegano i valori inviati alla riga aggiunta.

In un tema, il nome del campo utilizza il modello di parentesi di Shopify:

name="properties[Engraving]"

Un input di testo, un'area di testo, una casella di controllo o un altro controllo modulo può utilizzare questa convenzione di denominazione. Quando il cliente invia il modulo prodotto, Shopify interpreta Engraving come la chiave di proprietà e archivia il valore inviato sulla nuova riga di carrello. Il valore potrebbe essere un messaggio di incisione, un'istruzione regalo o un'altra informazione specifica dell'articolo.

Un'implementazione personalizzata può inviare un oggetto properties quando si aggiunge o si aggiorna una riga di carrello attraverso l'AJAX Cart API. Il punto chiave non è l'interfaccia utilizzata per inviare il valore. È la posizione in cui Shopify lo archivia, la riga articolo specifica che viene creata o modificata.

Screenshot da https://help.shopify.com/assets/manual/products/product-options/line-item-properties-product-page.png

La lista di controllo per l'acquisizione

  • Visualizza il campo nel modulo prodotto pertinente: Una proprietà viene raccolta nel contesto dell'elemento che il cliente sta aggiungendo.
  • Utilizza una chiave stabile: Engraving e Gift Message sono leggibili nel carrello e nell'ordine. Un'etichetta interna breve potrebbe essere più difficile da interpretare per i team operativi.
  • Invia il valore con la richiesta di aggiunta al carrello: Un campo che esiste visivamente ma non è incluso nella richiesta non diventerà dati dell'ordine.
  • Ispeziona la riga del carrello risultante: Conferma sia la chiave che il valore prima del checkout, soprattutto quando JavaScript modifica il carrello.

Per una visione più ampia di come i dati della pagina del prodotto influiscono sul percorso di acquisto, confronta questa implementazione con le indicazioni sull'ottimizzazione del checkout dell'e-commerce. Il miglior modulo è quello che raccoglie solo le informazioni che il cliente può comprendere e il team di evasione può utilizzare.

Dove appaiono le proprietà della riga dell'articolo dopo il checkout

Dopo il checkout, le proprietà diventano parte dei dati della riga dell'ordine piuttosto che rimanere un input temporaneo della pagina del prodotto. La documentazione di notifica di Shopify espone i campi della riga dell'articolo inclusi properties, line_price e quantity, mentre la sua documentazione per sviluppatori continua a descrivere le proprietà come dati disponibili per flussi di lavoro di ordine e integrazione. Il riferimento delle variabili di notifica di Shopify è utile quando si controlla cosa un modello di email può visualizzare.

Diverse superfici espongono le informazioni in modo diverso. Un utente operativo potrebbe aver bisogno di un valore leggibile nell'Admin Shopify, un'integrazione di evasione potrebbe aver bisogno di attributi leggibili da macchina, e un cliente potrebbe aver bisogno di vedere la personalizzazione che ha inviato. Non dare per scontato che un metodo di rendering funzioni ovunque.

Superficie Come vengono esposte le proprietà
Carrello La riga trasporta i suoi dati properties mentre l'elemento rimane nel carrello.
Admin Shopify I dati della riga dell'articolo dell'ordine possono esporre i valori agli utenti merchant e operativi.
Notifiche Le variabili di notifica Liquid possono esporre le proprietà della riga dell'articolo per i modelli supportati.
Admin GraphQL Le proprietà sono rappresentate come attributi o proprietà della riga dell'articolo, a seconda della risorsa e del modello API.
Sistemi esterni Un'integrazione legge i dati della proprietà della riga dell'ordine e mappa le chiavi nei suoi propri campi di evasione o operativi.

Progetta per il lettore dei dati

Un'email rivolta ai clienti ha bisogno di etichette che abbiano senso per un acquirente. Un sistema di produzione potrebbe aver bisogno di chiavi stabili che non cambino mai. Queste esigenze possono coesistere, ma non dovrebbero essere confuse.

Ad esempio, Incisione è comprensibile in una conferma d'ordine. Un'applicazione di fulfillment potrebbe normalizzare quel campo internamente come incisione.testo. L'applicazione dovrebbe mappare il valore deliberatamente invece di affidarsi a un'etichetta di visualizzazione che un commerciante potrebbe modificare in seguito nel tema.

Lo stesso principio si applica alle esportazioni e ai flussi di lavoro degli ordini. Testa la superficie esatta dove verrà utilizzato il valore. Una proprietà visibile in Liquid del carrello potrebbe richiedere una gestione diversa in una risposta API o in un modello di notifica.

Casi di utilizzo comuni e chiavi di proprietà di esempio

Le proprietà degli articoli di riga funzionano meglio quando le informazioni appartengono a un singolo articolo acquistato e non devono diventare una variante di catalogo. La personalizzazione è l'esempio più chiaro. Un cliente può inserire testo per un prodotto senza creare un record di prodotto separato per ogni possibile messaggio.

Usa chiavi descrittive che abbiano senso sia per il cliente che per il team di fulfillment. Gli esempi di seguito sono intenzionalmente leggibili piuttosto che abbreviati.

Caso d'uso Chiave proprietà Valore di esempio Note
Incisione Testo incisione Buon compleanno, Sam! Usa un'area di testo quando il messaggio potrebbe contenere più righe.
Confezionamento regalo Confezionamento regalo Sì Una scelta semplice funziona bene per un servizio binario.
Messaggio regalo Messaggio regalo Goditi la tua nuova casa. Mantieni l'etichetta chiara nelle visualizzazioni ordini e nelle email.
Artwork del cliente Caricamento artwork Un riferimento file o valore di caricamento inviato Conferma che il flusso di lavoro ricevente possa risolvere il riferimento archiviato.
Selezione personalizzata Finitura personalizzata Nero opaco Usa una variante quando la scelta influenza l'inventario del catalogo o i prezzi.
Riferimento commerciale Numero ordine di acquisto PO-4581 Mantieni il campo legato alla riga quando articoli diversi hanno bisogno di riferimenti diversi.

Scegli il campo giusto per la risposta

Un'incisione breve può utilizzare un input a riga singola. Una nota regalo o un'istruzione di produzione dovrebbe utilizzare un'area di testo in modo che l'interfaccia rifletta la risposta prevista. Una casella di controllo è appropriata per una scelta sì o no, ma il valore inviato dovrebbe rimanere comprensibile quando appare in un ordine.

Non usare una proprietà articolo di riga per imitare una variante che Shopify deve inventariare o quotare in modo indipendente. Se la selezione di un'opzione modifica la gestione delle scorte, il merchandising o l'articolo effettivamente vendibile, una variante potrebbe essere il modello più appropriato. Le proprietà sono più forti per istruzioni, personalizzazione, riferimenti e contesto operativo.

Le chiavi delle proprietà formano anche un'interfaccia pratica tra la vetrina e l'ufficio centrale. Cambiare Engraving Text in Message può sembrare innocuo in un tema, ma un'integrazione che legge la chiave originale potrebbe smettere di trovare il valore. Tratta le chiavi importanti come parte di un piccolo contratto sui dati.

Proprietà Private e Metadati Nascosti

Shopify supporta proprietà private degli articoli di riga anteponendo un trattino basso alla chiave. Ad esempio, _vendor_sku e _cost_center comunicano che il valore è metadato operativo piuttosto che una risposta rivolta al cliente. La documentazione per gli sviluppatori di Shopify descrive la convenzione del trattino basso per mantenere tali valori fuori dalla visualizzazione rivolta al cliente, pur conservandoli per la logica di sistema. La documentazione dell'API Cart Line Item spiega anche il comportamento dell'oggetto completo che gli sviluppatori devono considerare quando lavorano con questi attributi.

Un'infografica che confronta le proprietà dei file visibili con i metadati nascosti incorporati nei file immagini digitali e nelle foto.

Usa il prefisso deliberatamente

Una proprietà visibile deve rispondere a una domanda del cliente o aiutare il cliente a confermare un ordine. Una proprietà privata deve supportare un processo interno, come un mapping di integrazione, un'istruzione di approvvigionamento o un riferimento interno.

Il trattino basso fa parte della chiave. Il codice a valle deve richiedere esattamente _cost_center. Non dovrebbe cercare cost_center e presumere che Shopify tratti i due nomi come equivalenti.

Privato non significa "sicuro per mettere qualsiasi cosa qui". Controlli di accesso, gestione dei webhook e integrazioni di terze parti meritano comunque una revisione. Mantieni le informazioni sensibili fuori dalle proprietà a meno che l'intero percorso dei dati non sia stato valutato. Il prefisso controlla la visibilità rivolta al cliente, non ogni possibile percorso di accesso.

Controllo dell'implementazione: Crea una proprietà visibile e una proprietà con prefisso trattino basso in un ordine di test. Verifica cosa vede il cliente, cosa mostra l'Admin e cosa riceve la tua integrazione prima di rilasciare il flusso di lavoro.

Comportamento Durante le Modifiche degli Ordini Post-Acquisto

La modifica post-acquisto è il luogo in cui molti flussi di lavoro delle proprietà diventano ambigui. Un commerciante o un'applicazione può modificare una riga, sostituire un prodotto, regolare una quantità o creare una nuova riga. Ogni azione deve essere valutata rispetto al payload delle proprietà della riga articolo corrente, non rispetto al presupposto che la personalizzazione originale seguirà sempre.

Il comportamento di aggiornamento documentato di Shopify è particolarmente importante qui. Quando un aggiornamento invia properties, l'oggetto inviato sostituisce l'oggetto esistente piuttosto che unire singole chiavi. Ciò significa che una richiesta destinata a modificare un valore può rimuovere altri valori se l'integrazione non li include nel payload di sostituzione.

Tratta ogni aggiornamento come una riconciliazione

Prima di modificare una proprietà, un'integrazione dovrebbe:

  1. Leggi l'insieme di proprietà corrente per la riga di destinazione.
  2. Applica la modifica prevista a una rappresentazione locale.
  3. Convalida le chiavi e i valori obbligatori.
  4. Invia l'oggetto risultante completo, includendo i valori che non sono stati modificati.
  5. Conferma che la risposta contiene l'insieme previsto.

Questo modello è importante quando un cliente cambia un'incisione ma ha comunque bisogno del messaggio regalo e del flag di produzione interno. L'invio della sola nuova incisione può cancellare accidentalmente le altre chiavi.

La sostituzione di una riga con una riga appena creata merita anche una gestione esplicita. Una nuova riga ha il proprio payload di proprietà. Se il flusso di lavoro deve preservare la personalizzazione, l'applicazione deve deliberatamente copiare e convalidare i valori pertinenti piuttosto che assumere che Shopify dedurrà quella relazione.

Per i commercianti che valutano la modifica rivolta ai clienti, la guida alla modifica degli ordini Shopify fornisce un utile contesto operativo. La domanda di implementazione rimane specifica: quale riga viene modificata, quali proprietà sono obbligatorie e quale payload completo riceverà Shopify?

Note per sviluppatori e insidie dell'integrazione

I bug di proprietà più dannosi di solito non sono causati dal modulo iniziale. Accadono durante gli aggiornamenti, quando un'integrazione tratta un payload parziale come una patch anche se Shopify tratta l'oggetto properties come una sostituzione.

Supponiamo che una riga attualmente contenga Engraving, Gift Message e _production_route. Un aggiornamento che invia solo Engraving potrebbe lasciare la riga priva degli altri due valori. L'approccio sicuro è recuperare l'oggetto corrente, unire la modifica prevista nel codice dell'applicazione e inviare il risultato completo.

Costruisci gli aggiornamenti attorno all'oggetto completo

Usa un piccolo helper con comportamento esplicito piuttosto che distribuire gli aggiornamenti delle proprietà in vari script del carrello:

  • Leggi prima: Ottieni la riga corrente e le sue proprietà.
  • Normalizza le chiavi: Applica una convenzione di denominazione e preserva il trattino basso sulle chiavi private.
  • Unisci intenzionalmente: Modifica solo il valore richiesto in memoria.
  • Convalida prima di inviare: Rifiuta i campi obbligatori mancanti e i valori inadatti.
  • Sostituisci consapevolmente: Invia l'oggetto proprietà completo perché Shopify non lo unirà per te.

Non risolvere questo problem copiando ciecamente ogni valore per sempre. Una proprietà potrebbe essere obsoleta, controllata dal cliente o non più appropriata dopo una modifica del prodotto. L'integrazione dovrebbe definire quali chiavi vengono conservate, rimosse o rigenerate.

Per implementazioni più grandi, una risorsa per lo sviluppo di app Shopify può aiutare i team a pensare attraverso l'autenticazione, i webhook, i contratti dati e la gestione degli aggiornamenti come un sistema. Le agenzie che lavorano sul livello della vetrina e dell'ordine possono anche valutare i servizi Shopify quando il flusso di lavoro necessita un'implementazione personalizzata oltre i campi del tema.

Convalida quello che il tuo workflow effettivamente supporta

La documentazione Shopify fornita conferma la semantica di sostituzione e la gestione delle chiavi private. Non stabilisce un limite universale di conteggio proprietà o lunghezza caratteri per ogni superficie. Non aggiungere limiti non documentati alla convalida solo perché una particolare app, endpoint o implementazione del tema ha i propri vincoli.

Invece, testa il percorso di richiesta esatto che usi. Controlla valori vuoti, aggiornamenti ripetuti, caratteri Unicode, messaggi lunghi, riferimenti di file e chiavi private. Registra la richiesta e la risposta in un ambiente di sviluppo, mentre rimuovi i dati sensibili dei clienti dai log di produzione.

Migliori pratiche per commercianti per dati di proprietà affidabili

Tratta le chiavi di proprietà come uno schema piccolo. Una chiave come engraving.text o gift.wrap_message comunica ai sviluppatori cosa rappresenta il campo, mentre un nome machine stabile previene il breaking delle integrazioni quando l'etichetta visibile cambia.

Mantieni separata l'etichetta del cliente dalla chiave interna dove la tua implementazione lo consente. I clienti possono vedere "Messaggio di incisione", mentre il codice continua a utilizzare un identificatore stabile. Se una chiave è già utilizzata negli ordini attivi o nelle mappature downstream, non rinominarla casualmente. Aggiungi una nuova chiave e definisci un piano di migrazione se il modello di dati ha bisogno di cambiare.

Uno standard operativo pratico

  • Convalida prima di aggiungere al carrello: La personalizzazione obbligatoria non dovrebbe raggiungere il checkout con un valore vuoto.
  • Mantieni i valori leggibili: Lo staff di spedizione dovrebbe capire l'ordine senza tradurre abbreviazioni.
  • Separa la visibilità dalle operazioni: Usa una chiave con prefisso underscore per i metadati che non dovrebbero apparire nella vista del cliente.
  • Mostra la scelta inviata nei messaggi di conferma: I clienti dovrebbero essere in grado di verificare ciò che hanno richiesto.
  • Preserva la fonte di verità: Se un altro sistema copia la proprietà, conserva il valore originale della riga e documenta la mappatura.
  • Testa le modifiche, non solo il checkout iniziale: Un workflow di proprietà non è completo finché non sopravvive agli aggiornamenti che il tuo team di supporto prevede di fare.

Le proprietà degli articoli sono dati di ordine utili, ma non sono automaticamente un sostituto per ogni struttura dati Shopify. Se un valore deve essere interrogato, segnalato o mantenuto indipendentemente da una particolare riga acquistata, valuta se un metafield ordine o un'altra risorsa è più appropriata.

Proprietà articoli in un workflow post-acquisto

L'uso più forte delle proprietà articoli appare dopo che l'ordine è stato effettuato. Un valore di personalizzazione può informare la spedizione, un flag interno può instradare la produzione e un valore rivolto al cliente può supportare una revisione dell'ordine. La proprietà diventa una connessione tra l'istruzione dell'acquirente e i team o i sistemi che agiscono su di essa.

Un'applicazione self-serve di modifica dell'ordine può leggere la personalizzazione di una riga, presentare il valore esistente al cliente e riscrivere il valore rivisto con la stessa chiave. Quel workflow funziona in modo affidabile solo quando l'applicazione identifica la riga corretta e invia l'oggetto di proprietà completo durante l'aggiornamento.

Lo stesso principio si applica agli acquisti ripetuti e alle offerte post-acquisto. Un'esperienza di riordino può utilizzare i valori di proprietà precedenti come impostazioni predefinite, ma deve distinguere le preferenze riutilizzabili dalle istruzioni una tantum. Un messaggio di compleanno può essere specifico per un ordine, mentre un formato di incisione potrebbe essere utile di nuovo.

Dai a ogni utente a valle un contratto chiaro

L'evasione necessita di un valore utilizzabile. L'assistenza clienti necessita di un valore leggibile. Un sistema esterno necessita di una chiave prevedibile. Definisci quelle aspettative prima di aggiungere altri campi al modulo del prodotto.

Ad esempio, un flusso di lavoro produttivo potrebbe consumare Engraving Text, mentre una proprietà privata _production_route comunica a un processo interno dove l'articolo dovrebbe andare. La vetrina non ha bisogno di esporre il dettaglio di instradamento, e il sistema di evasione non dovrebbe dipendere solo da un'etichetta rivolta al cliente.

Errori comuni e come correggerli

La maggior parte degli errori può essere ricondotta a uno di tre luoghi: il modulo del prodotto, la richiesta di aggiornamento del carrello, o il modello o l'integrazione che legge l'ordine.

Sintomo dell'errore Causa probabile Correzione rapida
Una proprietà scompare dopo un aggiornamento del carrello L'aggiornamento ha inviato solo la chiave modificata, sostituendo l'oggetto completo Leggi le proprietà attuali, unisci il cambiamento e invia l'oggetto completo.
Un campo appare sulla pagina ma non nel carrello Il nome dell'input non utilizza il pattern properties[...] o JavaScript l'ha omesso Ispeziona la richiesta di aggiunta al carrello e conferma il nome del campo inviato.
Un valore privato appare in una visualizzazione rivolta al cliente La chiave non era prefissata con _, o il codice di visualizzazione la renderizza senza filtrare Utilizza il prefisso di sottolineatura per i metadati privati e filtra le chiavi private nel rendering personalizzato.
Un'integrazione non riesce a trovare una proprietà Si aspetta un'ortografia di chiave diversa o rimuove il sottolineatura Definisci chiavi stabili e fai riferimento a _key_name esattamente quando la proprietà è privata.
Una notifica mostra un'etichetta vuota Il modello legge l'oggetto sbagliato o presume che una proprietà esista su ogni riga Ispeziona la variabile della riga dell'articolo della notifica e gestisci i valori mancanti in modo sicuro.
Un articolo sostitutivo perde la personalizzazione La nuova riga è stata creata senza copiare il payload vecchio Riapplica solo le proprietà richieste e convalida prima che la sostituzione sia salvata.

Utilizza gli strumenti per sviluppatori del browser per i problemi di acquisizione del carrello. Utilizza i dati dell'ordine e il payload webhook per i problemi a valle. La diagnosi più veloce proviene dal confronto del valore a ogni confine invece di eseguire il debug dell'email finale o della schermata di evasione in isolamento.

Riferimento rapido per le proprietà della riga dell'articolo di Shopify

Utilizza questa tabella come una revisione compatta prima di modificare un tema, uno script del carrello o un'integrazione di ordine.

Domanda Risposta pratica
Che cosa è una proprietà? Metadati chiave-valore allegati a uno specifico articolo del carrello o dell'ordine.
È una variante? No. Accompagna l'articolo acquistato e non rappresenta una variante del catalogo.
Come viene acquisita in un tema? Usa un campo del modulo prodotto denominato con il pattern properties[Key].
Dove è archiviata nel carrello? Nell'oggetto properties dell'articolo.
Cosa accade durante un aggiornamento? Un oggetto properties inviato sostituisce l'oggetto esistente, quindi invia il set completo.
Come nascondo i metadati operativi? Aggiungi un prefisso alla chiave con _, quindi fai riferimento a quella chiave esatta in seguito.
Cosa devono convalidare le integrazioni? Chiavi obbligatorie, valori previsti, regole di visibilità e il comportamento dell'API esatta o del percorso del carrello in uso.
Cosa dovrei testare? Aggiunta iniziale al carrello, aggiornamenti del carrello, visualizzazione del checkout, notifiche, letture degli ordini e modifiche post-acquisto.

La mentalità dell'implementazione duratura è semplice: acquisisci le proprietà sulla riga corretta, preserva l'oggetto completo durante gli aggiornamenti e dai a ogni sistema a valle un contratto chiaro. Questo approccio previene la perdita di dati sottile che una demo di personalizzazione di base raramente espone.


Mayra Apps offre strumenti per la modifica degli ordini post-acquisto e gli upsell, con le modifiche rivolte ai clienti gestite tramite la pagina di stato dell'ordine e gli account dei clienti mentre Shopify rimane il sistema di registrazione. Se il tuo flusso di lavoro sulla proprietà dell'articolo deve connettersi con modifiche ordine controllate, visita Mayra Apps per esaminare l'approccio disponibile.