Un client commande une tasse personnalisée, tape « Happy Birthday, Sam! » dans un champ de personnalisation et s'attend à ce que ce message parvienne à la personne qui imprimera ou emballera la commande. Le produit lui-même n'a pas changé. Aucune nouvelle variante ou SKU n'a été créée. Le message appartient à cet article acheté spécifique, et Shopify a besoin d'un endroit fiable pour le transporter depuis la page produit jusqu'au panier et à la commande.
Cet endroit est une propriété de ligne de commande Shopify. La fonctionnalité ressemble à un simple champ personnalisé, mais les problèmes de production apparaissent généralement plus tard, lorsqu'une intégration met à jour une ligne de panier, qu'un système de commande lit les données, ou que des métadonnées privées deviennent inopinément visibles par les clients. Comprendre le cycle de vie complet, de la capture au traitement en aval, est plus utile que de traiter les propriétés comme du texte de personnalisation statique.
Table des matières
- Ce que sont vraiment les propriétés de ligne de commande Shopify
- Comment les propriétés de ligne de commande sont capturées dans le panier
- Où les propriétés de ligne de commande apparaissent après le paiement
- Cas d'utilisation courants et clés de propriétés exemples
- Propriétés privées et métadonnées masquées
- Comportement lors des modifications de commande après l'achat
- Notes de développement et pièges d'intégration
- Meilleures pratiques pour les commerçants concernant les données de propriété fiables
- Propriétés de ligne de commande dans un flux de travail après l'achat
- Erreurs courantes et comment les corriger
- Référence rapide pour les propriétés de ligne de commande Shopify
Ce que sont vraiment les propriétés de ligne de commande Shopify
Une propriété de ligne est des métadonnées personnalisées clé-valeur attachées à une ligne de panier ou à une ligne de commande. La clé identifie le champ, tel que Engraving, et la valeur contient les données soumises ou générées, telles que Happy Birthday, Sam!. Shopify documente les propriétés comme un objet de paires clé-valeur associées à un article du panier, et sa documentation de thème décrit la convention de nommage du formulaire de produit utilisée pour les soumettre. La documentation de ligne de Shopify identifie également la personnalisation, la gravure, les monogrammes et les téléchargements de fichiers comme cas d'usage pratiques.
La distinction importante est la propriété. Une propriété appartient à la ligne, non au registre du catalogue de produits et non au panier dans son ensemble. Si un client a deux copies de la même tasse avec des messages différents, chaque ligne a besoin de son propre ensemble de propriétés. Les métadonnées accompagnent le produit acheté plutôt que de devenir une option de produit.
Ce que ne sont pas les propriétés
Les propriétés de ligne ne sont pas des variantes. Une variante représente un choix de catalogue tel qu'une taille ou une couleur officielle et peut affecter l'inventaire, la tarification et la marchandisage. Une propriété capture des informations supplémentaires qui accompagnent un article sélectionné.
Ce ne sont pas non plus des métachamps. Les métachamps sont des champs de données structurées associés aux ressources Shopify telles que les produits, les clients ou les commandes. Une propriété de ligne est plus étroitement liée à l'article individuel de la transaction.
Dans la représentation du panier de Shopify, les données apparaissent via le champ properties. Dans les données de commande, les développeurs travaillent avec les propriétés ou les attributs de la ligne d'article correspondante, selon la surface de l'API. Cette distinction est importante lors de la création de règles d'exécution, d'affichages de commandes ou d'intégrations.
Règle pratique : Si la valeur décrit ce qu'un client souhaite faire avec un article acheté, commencez par évaluer une propriété de ligne. Si elle décrit le registre du produit ou du client de manière plus large, envisagez un autre modèle de données Shopify.
Comment les propriétés de ligne sont capturées sur le panier
Shopify supporte deux modèles de capture courants. Un thème peut soumettre des champs via le formulaire de produit, ou une vitrine personnalisée peut envoyer des données de propriété via une demande de panier. Les deux approches attachent les valeurs soumises à la ligne ajoutée.
Dans un thème, le nom du champ utilise le modèle de crochet de Shopify :
name="properties[Engraving]"
Une entrée de texte, une zone de texte, une case à cocher ou un autre contrôle de formulaire peut utiliser cette convention de nommage. Lorsque le client soumet le formulaire de produit, Shopify interprète Engraving comme la clé de propriété et stocke la valeur soumise sur la nouvelle ligne du panier. La valeur pourrait être un message de gravure, une instruction de cadeau ou une autre information spécifique à l'article.
Une implémentation personnalisée peut envoyer un objet properties lors de l'ajout ou de la mise à jour d'une ligne de panier via l'API Cart AJAX. Le point clé n'est pas l'interface utilisée pour soumettre la valeur. C'est l'endroit où Shopify la stocke, la ligne d'article spécifique en cours de création ou de modification.

Liste de contrôle de capture
- Affichez le champ sur le formulaire de produit pertinent : Une propriété est collectée dans le contexte de l'article que le client ajoute.
- Utilisez une clé stable :
EngravingetGift Messagesont lisibles dans le panier et la commande. Un libellé interne court peut être plus difficile à interpréter pour les équipes opérationnelles. - Soumettez la valeur avec la demande d'ajout au panier : Un champ qui existe visuellement mais qui n'est pas inclus dans la demande ne deviendra pas des données de commande.
- Inspectez la ligne de panier résultante : Confirmez à la fois la clé et la valeur avant le paiement, surtout lorsque JavaScript modifie le panier.
Pour une vue plus large de la façon dont les données de page produit affectent le parcours d'achat, comparez cette implémentation avec les conseils d'optimisation du paiement du commerce électronique. Le meilleur formulaire est celui qui collecte uniquement les informations que le client peut comprendre et que l'équipe d'exécution peut utiliser.
Où les propriétés de ligne d'article apparaissent après le paiement
Après le paiement, les propriétés deviennent partie des données de la ligne de commande plutôt que de rester une entrée temporaire de page produit. La documentation de notification de Shopify expose les champs de ligne d'article, notamment properties, line_price et quantity, tandis que sa documentation pour développeurs continue de décrire les propriétés comme des données disponibles pour les workflows de commande et d'intégration. La référence des variables de notification de Shopify est utile pour vérifier ce qu'un modèle d'e-mail peut afficher.
Différentes surfaces exposent les informations différemment. Un utilisateur opérationnel peut avoir besoin d'une valeur lisible dans l'Admin Shopify, une intégration d'exécution peut avoir besoin d'attributs lisibles par machine, et un client peut avoir besoin de voir la personnalisation qu'il a soumise. Ne supposez pas qu'une méthode de rendu fonctionne partout.
| Surface | Comment les propriétés sont exposées |
|---|---|
| Panier | La ligne porte ses données properties tant que l'article reste dans le panier. |
| Admin Shopify | Les données de ligne de commande peuvent exposer les valeurs aux utilisateurs marchands et opérationnels. |
| Notifications | Les variables de notification Liquid peuvent exposer les propriétés de ligne d'article pour les modèles supportés. |
| Admin GraphQL | Les propriétés sont représentées comme des attributs ou des propriétés de ligne d'article, selon la ressource et le modèle API. |
| Systèmes externes | Une intégration lit les données de propriété de la ligne de commande et mappe les clés dans ses propres champs de l'exécution ou opérationnels. |
Concevoir pour le lecteur des données
Un e-mail face au client doit avoir des étiquettes qui ont du sens pour un acheteur. Un système de production peut avoir besoin de clés stables qui ne changent jamais. Ces besoins peuvent coexister, mais ils ne doivent pas être confondus.
Par exemple, Engraving est compréhensible dans une confirmation de commande. Une application d'exécution peut normaliser ce champ en interne sous la forme engraving.text. L'application doit mapper la valeur délibérément plutôt que de s'appuyer sur une étiquette d'affichage qu'un commerçant peut modifier ultérieurement dans le thème.
Le même principe s'applique aux exports et aux workflows de commande. Testez la surface exacte où la valeur sera utilisée. Une propriété visible dans le panier Liquid peut nécessiter une gestion différente dans une réponse API ou un modèle de notification.
Cas d'usage courants et exemples de clés de propriété
Les propriétés d'article de ligne fonctionnent mieux lorsque l'information appartient à un seul article acheté et n'a pas besoin de devenir une variante de catalogue. La personnalisation est l'exemple le plus clair. Un client peut entrer du texte pour un produit sans créer un enregistrement de produit distinct pour chaque message possible.
Utilisez des clés descriptives qui ont du sens pour le client et pour l'équipe d'exécution. Les exemples ci-dessous sont intentionnellement lisibles plutôt qu'abrégés.
| Cas d'usage | Clé de propriété | Exemple de valeur | Remarques |
|---|---|---|---|
| Gravure | Engraving Text |
Happy Birthday, Sam! |
Utilisez une zone de texte lorsque le message peut contenir plusieurs lignes. |
| Emballage cadeau | Gift Wrap |
Yes |
Un choix simple fonctionne bien pour un service binaire. |
| Message cadeau | Gift Message |
Enjoy your new home. |
Gardez l'étiquette claire dans les vues de commande et les e-mails. |
| Artwork client | Artwork Upload |
Une référence de fichier ou une valeur d'upload soumise | Confirmez que le workflow de réception peut résoudre la référence stockée. |
| Sélection personnalisée | Custom Finish |
Matte black |
Utilisez une variante lorsque le choix affecte l'inventaire du catalogue ou les tarifs. |
| Référence commerciale | Purchase Order Number |
PO-4581 |
Gardez le champ lié à l'article lorsque différents articles ont besoin de références différentes. |
Choisir le bon champ pour la réponse
Une courte gravure peut utiliser une saisie sur une seule ligne. Une note cadeau ou une instruction de production doit utiliser une zone de texte pour que l'interface reflète la réponse attendue. Une case à cocher convient à un choix oui ou non, mais la valeur soumise doit rester compréhensible lorsqu'elle apparaît dans une commande.
N'utilisez pas une propriété d'article de ligne pour imiter une variante que Shopify doit gérer en inventaire ou évaluer indépendamment. Si la sélection d'une option change la gestion des stocks, le merchandising ou l'article vendable réel, une variante peut être un modèle plus approprié. Les propriétés sont plus efficaces pour les instructions, la personnalisation, les références et le contexte opérationnel.
Les clés de propriété forment également une interface pratique entre la vitrine et le back-office. Remplacer Engraving Text par Message peut sembler inoffensif dans un thème, mais une intégration qui lit la clé originale peut cesser de trouver la valeur. Traitez les clés importantes comme faisant partie d'un petit contrat de données.
Propriétés privées et métadonnées masquées
Shopify prend en charge les propriétés d'article de ligne privées en préfixant la clé avec un tiret bas. Par exemple, _vendor_sku et _cost_center indiquent que la valeur est une métadonnée opérationnelle plutôt qu'une réponse visible par le client. La documentation du développeur de Shopify décrit la convention du tiret bas pour maintenir ces valeurs hors de l'affichage visible par le client tout en les conservant pour la logique système. La documentation de l'API Cart Line Item explique également le comportement d'objet complet que les développeurs doivent prendre en compte lorsqu'ils travaillent avec ces attributs.

Utilisez le préfixe délibérément
Une propriété visible doit répondre à une question du client ou aider le client à confirmer une commande. Une propriété privée doit soutenir un processus interne, tel qu'un mappage d'intégration, une instruction d'approvisionnement ou une référence interne.
Le tiret bas fait partie de la clé. Le code en aval doit demander _cost_center exactement. Il ne devrait pas rechercher cost_center et supposer que Shopify traitera les deux noms comme équivalents.
Privé ne signifie pas « sûr de mettre n'importe quoi ici ». Les contrôles d'accès, la gestion des webhooks et les intégrations tierces méritent toujours d'être examinés. Conservez les informations sensibles hors des propriétés sauf si l'ensemble du chemin de données a été évalué. Le préfixe contrôle la visibilité visible par le client, pas tous les chemins d'accès possibles.
Vérification de mise en œuvre : Créez une propriété visible et une propriété avec préfixe tiret bas dans une commande de test. Vérifiez ce que le client voit, ce que l'Admin affiche et ce que votre intégration reçoit avant de déployer le flux de travail.
Comportement lors des modifications de commande après achat
La modification après achat est l'endroit où de nombreux flux de travail de propriété deviennent ambigus. Un commerçant ou une application peut modifier une ligne, remplacer un produit, ajuster une quantité ou créer une nouvelle ligne. Chaque action doit être évaluée par rapport à la charge utile de propriété de l'article de ligne actuelle, et non par rapport à l'hypothèse que la personnalisation originale suivra toujours.
Le comportement de mise à jour documenté de Shopify est particulièrement important ici. Quand une mise à jour envoie properties, l'objet soumis remplace l'objet existant au lieu de fusionner les clés individuelles. Cela signifie qu'une demande destinée à modifier une valeur peut supprimer d'autres valeurs si l'intégration ne les inclut pas dans la charge utile de remplacement.
Traitez chaque mise à jour comme une réconciliation
Avant de modifier une propriété, une intégration doit :
- Lire l'ensemble des propriétés actuel pour la ligne cible.
- Appliquer le changement prévu à une représentation locale.
- Valider les clés et valeurs requises.
- Envoyer l'objet complet résultant, y compris les valeurs qui n'ont pas été modifiées.
- Confirmer que la réponse contient l'ensemble attendu.
Ce modèle est important lorsqu'un client change une gravure mais a toujours besoin du message cadeau et du drapeau de production interne. L'envoi de la seule nouvelle gravure peut accidentellement effacer les autres clés.
Le remplacement d'une ligne par une ligne nouvellement créée mérite également un traitement explicite. Une nouvelle ligne a sa propre charge utile de propriétés. Si le flux de travail doit préserver la personnalisation, l'application doit délibérément copier et valider les valeurs pertinentes plutôt que de supposer que Shopify déduira cette relation.
Pour les marchands évaluant l'édition orientée client, les conseils d'édition de commande Shopify fournissent un contexte opérationnel utile. La question de mise en œuvre reste spécifique : quelle ligne est modifiée, quelles propriétés sont requises, et quelle charge utile complète Shopify recevra-t-il ?
Notes pour les développeurs et pièges d'intégration
Les bugs de propriété les plus dommageux ne sont généralement pas causés par le formulaire initial. Ils surviennent lors des mises à jour, lorsqu'une intégration traite une charge utile partielle comme un correctif même si Shopify traite l'objet properties comme un remplacement.
Supposons qu'une ligne contienne actuellement Engraving, Gift Message et _production_route. Une mise à jour qui envoie uniquement Engraving peut laisser la ligne sans les deux autres valeurs. L'approche sûre est de récupérer l'objet actuel, de fusionner le changement prévu dans le code de l'application et de soumettre le résultat complet.
Construire les mises à jour autour de l'objet entier
Utilisez un petit assistant avec un comportement explicite plutôt que de disperser les mises à jour de propriétés dans les scripts de panier :
- Lire d'abord : Obtenez la ligne actuelle et ses propriétés.
- Normaliser les clés : Appliquez une convention de nommage et préservez le trait de soulignement sur les clés privées.
- Fusionner intentionnellement : Modifiez uniquement la valeur demandée en mémoire.
- Valider avant d'envoyer : Rejetez les champs manquants requis et les valeurs inappropriées.
- Remplacer consciemment : Envoyez l'objet de propriété complet car Shopify ne le fusionnera pas pour vous.
Ne résolvez pas ce problème en copiant aveuglément chaque valeur pour toujours. Une propriété peut être obsolète, contrôlée par le client ou ne plus être appropriée après un changement de produit. L'intégration doit définir quelles clés sont conservées, supprimées ou régénérées.
Pour les implémentations plus importantes, une ressource de développement d'application Shopify peut aider les équipes à réfléchir à l'authentification, aux webhooks, aux contrats de données et à la gestion des mises à jour en tant que système unique. Les agences travaillant sur la couche storefront et commande peuvent également évaluer les services Shopify lorsque le flux de travail nécessite une implémentation personnalisée au-delà des champs de thème.
Valider ce que votre flux de travail supporte réellement
La documentation Shopify fournie confirme la sémantique de remplacement et la gestion des clés privées. Elle n'établit pas une limite universelle de nombre de propriétés ou de longueur de caractères pour chaque surface. N'ajoutez pas de limites non documentées à la validation simplement parce qu'une application, un endpoint ou une implémentation de thème particulière a sa propre contrainte.
À la place, testez le chemin exact de la demande que vous utilisez. Vérifiez les valeurs vides, les mises à jour répétées, les caractères Unicode, les messages longs, les références de fichiers et les clés privées. Enregistrez la demande et la réponse dans un environnement de développement, tout en supprimant les données sensibles des clients des journaux de production.
Bonnes pratiques des commerçants pour des données de propriété fiables
Traitez les clés de propriété comme un petit schéma. Une clé telle que engraving.text ou gift.wrap_message indique aux développeurs ce que le champ représente, tandis qu'un nom machine stable empêche les intégrations de se casser lorsque l'étiquette visible change.
Gardez l'étiquette du client séparée de la clé interne là où votre implémentation le permet. Les clients peuvent voir « Message de gravure », tandis que le code continue d'utiliser un identifiant stable. Si une clé est déjà utilisée dans des commandes en direct ou des mappages en aval, ne la renommez pas à la légère. Ajoutez une nouvelle clé et définissez un plan de migration si le modèle de données doit changer.
Un standard opérationnel pratique
- Valider avant d'ajouter au panier : La personnalisation requise ne doit pas atteindre le paiement avec une valeur vide.
- Gardez les valeurs lisibles : Le personnel d'exécution devrait comprendre la commande sans traduire les abréviations.
- Séparez la visibilité des opérations : Utilisez une clé préfixée par un tiret bas pour les métadonnées qui ne devraient pas apparaître dans la vue du client.
- Affichez le choix soumis dans le message de confirmation : Les clients doivent pouvoir vérifier ce qu'ils ont demandé.
- Préservez la source de vérité : Si un autre système copie la propriété, conservez la valeur originale de l'article et documentez le mapping.
- Testez les modifications, pas seulement le paiement initial : Un flux de propriété n'est complet que s'il survit aux mises à jour que votre équipe d'assistance s'attend à faire.
Les propriétés de l'article sont des données de commande utiles, mais elles ne sont pas automatiquement un substitut pour chaque structure de données Shopify. Si une valeur doit être interrogée, signalée ou maintenue indépendamment d'une ligne achetée particulière, évaluez si un métafield de commande ou une autre ressource serait plus appropriée.
Propriétés d'article dans un flux de travail post-achat
L'utilisation la plus forte des propriétés d'article apparaît après que la commande est placée. Une valeur de personnalisation peut informer l'exécution, un indicateur interne peut router la production, et une valeur orientée vers le client peut supporter un examen de commande. La propriété devient une connexion entre l'instruction de l'acheteur et les équipes ou systèmes qui agissent dessus.
Une application d'édition de commande libre-service peut lire la personnalisation d'une ligne, présenter la valeur existante au client et réécrire la valeur révisée sous la même clé. Ce flux de travail ne fonctionne de manière fiable que lorsque l'application identifie la ligne correcte et soumet l'objet de propriété complet pendant la mise à jour.
Le même principe s'applique aux achats répétés et aux offres post-achat. Une expérience de recommande peut utiliser les valeurs de propriétés précédentes par défaut, mais elle doit distinguer les préférences réutilisables des instructions ponctuelles. Un message d'anniversaire peut être spécifique à une commande, tandis qu'un format de gravure pourrait être utile à nouveau.
Donnez à chaque utilisateur en aval un contrat clair
L'exécution a besoin d'une valeur exploitable. Le service client a besoin d'une valeur lisible. Un système externe a besoin d'une clé prévisible. Définissez ces attentes avant d'ajouter plus de champs au formulaire de produit.
Par exemple, un flux de production pourrait consommer Engraving Text, tandis qu'une propriété privée _production_route indique à un processus interne où l'article doit aller. La vitrine n'a pas besoin d'exposer le détail du routage, et le système d'exécution ne doit pas dépendre uniquement d'une étiquette orientée client.
Erreurs courantes et comment les corriger
La plupart des défaillances peuvent être attribuées à l'un des trois endroits : le formulaire de produit, la demande de mise à jour du panier, ou le modèle ou l'intégration qui lit la commande.
| Symptôme d'erreur | Cause probable | Correctif rapide |
|---|---|---|
| Une propriété disparaît après une mise à jour du panier | La mise à jour a envoyé uniquement la clé modifiée, remplaçant l'objet complet | Lisez les propriétés actuelles, fusionnez la modification et soumettez l'objet complet. |
| Un champ apparaît sur la page mais pas dans le panier | Le nom d'entrée n'utilise pas le modèle properties[...] ou JavaScript l'a omis |
Inspectez la demande d'ajout au panier et confirmez le nom du champ soumis. |
| Une valeur privée apparaît dans une vue orientée client | La clé n'était pas préfixée par _, ou le code d'affichage la rend sans filtrer |
Utilisez le préfixe de tiret bas pour les métadonnées privées et filtrez les clés privées dans le rendu personnalisé. |
| Une intégration ne peut pas trouver une propriété | Elle s'attend à une orthographe de clé différente ou supprime le tiret bas | Définissez des clés stables et référencez _key_name exactement quand la propriété est privée. |
| Une notification affiche une étiquette vide | Le modèle lit le mauvais objet ou suppose qu'une propriété existe sur chaque ligne | Inspectez la variable de ligne du modèle de notification et gérez les valeurs manquantes de manière sûre. |
| Un article de remplacement perd sa personnalisation | La nouvelle ligne a été créée sans copier la charge utile ancienne | Réappliquez uniquement les propriétés requises et validez-les avant que le remplacement soit enregistré. |
Utilisez les outils de développeur du navigateur pour les problèmes de capture du panier. Utilisez les données de commande et la charge utile de webhook pour les problèmes en aval. Le diagnostic le plus rapide provient de la comparaison de la valeur à chaque limite au lieu de déboguer l'e-mail final ou l'écran d'exécution isolément.
Référence rapide pour les propriétés de ligne de Shopify
Utilisez ce tableau comme un examen compact avant de modifier un thème, un script de panier ou une intégration de commande.
| Question | Réponse pratique |
|---|---|
| Qu'est-ce qu'une propriété ? | Métadonnées clé-valeur attachées à un article de panier ou de commande spécifique. |
| Est-ce une variante ? | Non. Elle accompagne l'article acheté et ne représente pas une variante du catalogue. |
| Comment est-elle capturée dans un thème ? | Utilisez un champ de formulaire de produit nommé selon le modèle properties[Key]. |
| Où est-elle stockée dans le panier ? | Dans l'objet properties de l'article. |
| Que se passe-t-il lors d'une mise à jour ? | Un objet propriétés soumis remplace l'objet existant, donc envoyez l'ensemble complet. |
| Comment masquer les métadonnées opérationnelles ? | Préfixez la clé avec _, puis référencez cette clé exacte en aval. |
| Que doivent valider les intégrations ? | Les clés requises, les valeurs attendues, les règles de visibilité et le comportement de l'API exacte ou du chemin du panier utilisé. |
| Que dois-je tester ? | L'ajout initial au panier, les mises à jour du panier, l'affichage du paiement, les notifications, les lectures de commandes et les modifications post-achat. |
L'approche de mise en œuvre durable est simple : capturez les propriétés sur la bonne ligne, préservez l'objet complet lors des mises à jour, et donnez à chaque système en aval un contrat clair. Cette approche prévient la perte de données subtile qu'une démo de personnalisation basique expose rarement.
Mayra Apps offre des outils pour la modification de commandes post-achat et les ventes additionnelles, les modifications visibles par les clients étant gérées via la page de statut de commande et les comptes clients tandis que Shopify reste le système de référence. Si votre flux de propriété d'article de ligne doit se connecter à des modifications de commande contrôlées, visitez Mayra Apps pour examiner l'approche disponible.

