顧客がギフト用マグカップを注文し、パーソナライズフィールドに「Happy Birthday, Sam!」と入力すると、そのメッセージは製品の印刷または梱包担当者に届くことが期待されます。製品自体は変わっていません。新しいバリアントまたはSKUは作成されていません。メッセージはその特定の購入アイテムに属しており、Shopifyは製品ページからカートを通じて注文まで、それを確実に運ぶ信頼できる場所が必要です。

その場所がShopifyラインアイテムプロパティです。この機能は単純なカスタムフィールドのように見えますが、本番環境の問題は通常後で、統合がカートラインを更新したり、注文システムがデータを読み取ったり、プライベートメタデータが予期せず顧客に見えるようになったりするときに現れます。プロパティを静的なパーソナライズテキストとして扱うのではなく、キャプチャからダウンストリーム処理までの完全なライフサイクルを理解することが、より有用です。

目次

Shopifyラインアイテムプロパティの実際の内容

行アイテムプロパティは1つのカートラインまたは注文ラインアイテムに添付されるカスタムキーと値のメタデータです。キーはEngravingなどのフィールドを識別し、値はHappy Birthday, Sam!などの送信または生成されたデータを含みます。Shopifyはプロパティをカートアイテムに関連付けられたキーと値のペアのオブジェクトとしてドキュメント化し、テーマドキュメントではそれらを送信するための使用される製品フォームの命名規則について説明します。Shopifyのラインアイテムドキュメントは、個人化、刻印、モノグラム、ファイルアップロードを実用的な用途として識別しています。

重要な区別は所有権です。プロパティはラインに属し、製品カタログレコードにもカート全体にも属しません。顧客が異なるメッセージを持つ同じマグカップの2つのコピーを持っている場合、各ラインは独自のプロパティセットが必要です。メタデータは購入した製品とともに移動し、製品オプションになるわけではありません。

プロパティではないもの

ラインアイテムプロパティはバリアントではありません。バリアントは公式なサイズや色などのカタログ選択を表し、在庫、価格設定、マーチャンダイジングに影響を与える可能性があります。プロパティは、選択されたアイテムに付随する追加情報を取得します。

これらはメタフィールドでもありません。メタフィールドは、製品、顧客、注文などのShopifyリソースに関連付けられた構造化データフィールドです。ラインアイテムプロパティは、トランザクション内の個別アイテムにより狭く関連付けられています。

Shopifyのカート表現では、データはpropertiesフィールドを通じて表示されます。注文データでは、開発者は対応するラインアイテムのプロパティまたは属性を操作します。これはAPIサーフェスに応じて異なります。この区別は、フルフィルメントルール、注文表示、または統合を構築する場合に重要です。

実用的なルール:値が購入したアイテムに対して顧客が何をしたいのかを説明する場合は、ラインアイテムプロパティを評価することから始めてください。製品または顧客レコードをより広く説明する場合は、別のShopifyデータモデルを検討してください。

ラインアイテムプロパティがカートにキャプチャされる方法

Shopifyは2つの一般的なキャプチャパターンをサポートしています。テーマは製品フォームを通じてフィールドを送信するか、カスタムストアフロントはカートリクエストを通じてプロパティデータを送信できます。どちらのアプローチも、送信された値を追加されているラインに添付します。

テーマでは、フィールド名はShopifyのブラケットパターンを使用します:

name="properties[Engraving]"

テキスト入力、テキストエリア、チェックボックス、または他のフォームコントロールはその命名規則を使用できます。顧客が製品フォームを送信すると、ShopifyはEngravingをプロパティキーとして解釈し、送信された値を新しいカートラインに保存します。値は刻印メッセージ、ギフト指示、またはアイテムに固有の別の情報である可能性があります。

カスタム実装は、AJAX Cart APIを通じてカートラインを追加または更新するときにpropertiesオブジェクトを送信できます。重要な点は、値を送信するために使用されるインターフェイスではありません。Shopifyがそれを保存する場所、作成または変更されている特定のラインアイテムです。

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

キャプチャチェックリスト

  • 関連する商品フォームにフィールドをレンダリングする:プロパティは、顧客が追加する品目のコンテキストで収集されます。
  • 安定したキーを使用する:EngravingとGift Messageはカートと注文で読み取り可能です。短い内部ラベルはオペレーションチームが解釈しづらい場合があります。
  • カートへの追加リクエストで値を送信する:視覚的には存在するがリクエストに含まれていないフィールドは、注文データにはなりません。
  • 結果のカート行を確認する:特にJavaScriptがカートを変更する場合は、チェックアウト前にキーと値の両方を確認します。

商品ページのデータが購買ジャーニーに与える影響についてより幅広く理解するには、この実装をEコマースチェックアウト最適化ガイダンスと比較してください。最良のフォームは、顧客が理解でき、フルフィルメントチームが使用できる情報のみを収集するものです。

チェックアウト後のラインアイテムプロパティの表示場所

チェックアウト後、プロパティは注文行のデータの一部になり、一時的な商品ページの入力として残りません。Shopifyの通知ドキュメントは、properties、line_price、quantityを含むラインアイテムフィールドを公開し、開発者ドキュメントはプロパティを注文および統合ワークフローで利用可能なデータとして引き続き説明しています。Shopifyの通知変数リファレンスは、メールテンプレートが何をレンダリングできるかを確認する際に有用です。

異なるサーフェスは情報をさまざまな方法で公開します。オペレーションユーザーはShopify管理画面で読み取り可能な値が必要な場合があり、フルフィルメント統合はマシンが読み取り可能な属性が必要な場合があり、顧客は提出したパーソナライズを確認する必要がある場合があります。1つのレンダリング方法がすべての場所で機能すると想定しないでください。

サーフェス プロパティの公開方法
カート 行は、アイテムがカート内に残っている間、そのpropertiesデータを保持します。
Shopify管理画面 注文ラインアイテムデータは、マーチャントおよびオペレーションユーザーに値を公開できます。
通知 Liquid通知変数は、サポートされているテンプレート用のラインアイテムプロパティを公開できます。
Admin GraphQL プロパティは、リソースとAPIモデルに応じて、ラインアイテム属性またはプロパティとして表されます。
外部システム 統合は注文行のプロパティデータを読み取り、キーを独自のフルフィルメントまたはオペレーショナルフィールドにマップします。

データの読み手を想定した設計

顧客向けのメールには、購入者にとって意味のあるラベルが必要です。本番システムでは、決して変わらない安定したキーが必要な場合があります。これらのニーズは共存できますが、混同されるべきではありません。

例えば、Engravingは注文確認で理解しやすいものです。フルフィルメント・アプリケーションは、そのフィールドを内部的にengraving.textとして正規化する可能性があります。アプリケーションは、マーチャントが後でテーマで編集する可能性のある表示ラベルに依存するのではなく、意図的に値をマップする必要があります。

同じ原則がエクスポートと注文ワークフローに適用されます。値が使用される正確な場所でテストしてください。カートLiquidで表示されるプロパティは、APIレスポンスまたは通知テンプレートで異なる処理が必要な場合があります。

一般的な使用例とプロパティキーの例

ラインアイテムのプロパティは、情報が購入された1つのアイテムに属し、カタログバリアントになる必要がない場合に最も効果的です。パーソナライゼーションが最も明確な例です。顧客は、可能なすべてのメッセージに対して個別の製品レコードを作成することなく、1つの製品のテキストを入力できます。

顧客とフルフィルメント・チームの両方にとって意味のある説明的なキーを使用してください。以下の例は、意図的に読みやすくなっており、略語ではありません。

使用例 プロパティキー 値の例 注記
刻印 Engraving Text Happy Birthday, Sam! メッセージが複数行になる可能性がある場合は、テキストエリアを使用してください。
ギフトラッピング Gift Wrap Yes シンプルな選択肢はバイナリサービスに適しています。
ギフトメッセージ Gift Message Enjoy your new home. 注文ビューとメールでラベルを明確に保ちます。
顧客アートワーク Artwork Upload ファイル参照または送信されたアップロード値 受信ワークフローが保存された参照を解決できることを確認してください。
カスタム選択 Custom Finish Matte black 選択がカタログ在庫または価格に影響する場合は、バリアントを使用してください。
ビジネスリファレンス Purchase Order Number PO-4581 異なるアイテムが異なるリファレンスを必要とする場合、フィールドをラインに結び付けてください。

答えに適切なフィールドを選択する

短い刻印には、単一行の入力を使用できます。ギフトノートまたは製造指示には、インターフェイスが予想される答えを反映するようにテキストエリアを使用する必要があります。チェックボックスは「はい」または「いいえ」の選択肢に適していますが、送信された値は注文に表示される場合、理解可能なままである必要があります。

ラインアイテムプロパティを使用して、Shopifyが在庫管理または価格を個別に設定する必要があるバリアントを模倣しないでください。オプションの選択が在庫管理、マーチャンダイジング、または実際の販売可能アイテムを変更する場合、バリアントがより適切なモデルである可能性があります。プロパティは指示、パーソナライゼーション、リファレンス、および運用コンテキストに最も強力です。

プロパティキーはまた、ストアフロントとバックオフィス間の実用的なインターフェースを形成します。テーマでEngraving TextをMessageに変更することは無害に見えるかもしれませんが、元のキーを読む統合は値の検出に失敗する可能性があります。重要なキーをデータコントラクトの一部として扱います。

プライベートプロパティと隠しメタデータ

Shopifyはキーにアンダースコアを前置して、プライベートラインアイテムプロパティをサポートしています。例えば、_vendor_skuと_cost_centerは、その値が顧客向けの回答ではなく、運用メタデータであることを示します。Shopifyの開発者向けドキュメントでは、そのような値を顧客向けディスプレイから除外しながらシステムロジックのために保持するアンダースコア規則について説明しています。カートラインアイテムAPIドキュメントは、これらの属性を操作する際に開発者が考慮する必要があるフル オブジェクト動作についても説明しています。

デジタル画像ファイルおよび写真内に埋め込まれた表示ファイルプロパティと隠しメタデータを比較するインフォグラフィック。

プレフィックスを意図的に使用する

表示されるプロパティは、顧客の質問に答えるか、顧客が注文を確認するのに役立つものである必要があります。プライベートプロパティは、統合マッピング、ソーシング命令、または内部参照などの内部プロセスをサポートする必要があります。

アンダースコアはキーの一部です。ダウンストリームコードは_cost_centerを正確にリクエストする必要があります。cost_centerを探して、Shopifyが2つの名前を同等に扱うと仮定してはいけません。

プライベートは「ここに何でも入れても安全」という意味ではありません。アクセス制御、Webhook処理、サードパーティ統合も確認が必要です。データパス全体が評価されている場合を除き、プロパティから機密情報を除外してください。プレフィックスは顧客向けの可視性を制御するもので、すべての可能なアクセスパスではありません。

実装チェック:テスト注文で1つの表示プロパティと1つのアンダースコア前置プロパティを作成します。顧客が何を見るか、管理画面が何を表示するか、統合が何を受け取るかをワークフローをリリースする前に確認してください。

購入後の注文編集中の動作

購入後の編集は、多くのプロパティワークフローがあいまいになる場所です。マーチャントまたはアプリケーションは、ラインを変更したり、製品を置き換えたり、数量を調整したり、新しいラインを作成したりできます。各アクションは、元のパーソナライゼーションが常に従うという仮定ではなく、現在のラインアイテムのプロパティペイロードに対して評価される必要があります。

Shopifyのドキュメント化されたアップデート動作はここで特に重要です。アップデートがpropertiesを送信する場合、送信されたオブジェクトは個々のキーをマージするのではなく、既存のオブジェクトを置き換えます。つまり、1つの値を変更することを意図したリクエストは、統合が置き換えペイロードに含めない場合、他の値を削除することができます。

各アップデートを調整として扱う

プロパティを変更する前に、統合は以下を実行する必要があります:

  1. 現在のプロパティセットを読むターゲットラインの場合。
  2. 意図された変更を適用するローカル表現に。
  3. 必須キーと値を検証します。
  4. 完全な結果のオブジェクトを送信する変更されなかった値を含めて。
  5. レスポンスを確認するには、期待されたセットが含まれています。

このパターンは、顧客が彫刻を変更した場合に重要ですが、ギフトメッセージと内部製造フラグが必要です。新しい彫刻のみを送信すると、他のキーが意図せずにクリアされる可能性があります。

行を新しく作成された行に置き換えることも、明示的な処理が必要です。新しい行には独自のプロパティペイロードがあります。ワークフローが個人化を保持する必要がある場合、アプリケーションは関連する値を意図的にコピーして検証する必要があり、Shopifyがその関係を推測することを想定してはいけません。

顧客対応の編集を評価しているマーチャント向けに、Shopify注文編集ガイダンスは有用な運用コンテキストを提供します。実装の問題は依然として具体的です:どの行が変更されているか、どのプロパティが必須か、そしてShopifyがどの完全なペイロードを受け取るのか?

開発者向けメモと統合の落とし穴

最も破壊的なプロパティバグは、通常、初期フォームによって引き起こされるわけではありません。これらは更新中に発生します。統合が部分的なペイロードをパッチとして扱う場合でも、Shopifyはpropertiesオブジェクトを置換として扱うためです。

行に現在Engraving、Gift Message、および_production_routeが含まれていると仮定します。Engravingのみを送信する更新では、行に他の2つの値がない場合があります。安全なアプローチは、現在のオブジェクトを取得し、アプリケーションコードで意図された変更をマージして、完全な結果を送信することです。

全体のオブジェクトの周りに更新を構築する

カートスクリプト全体に散らばっているプロパティ更新の代わりに、明示的な動作を持つ小さなヘルパーを使用してください:

  • 最初に読む:現在の行とそのプロパティを取得します。
  • キーを正規化する:1つの命名規則を適用し、プライベートキーのアンダースコアを保持します。
  • 意図的にマージする:メモリ内で要求された値のみを変更します。
  • 送信前に検証する:必須フィールドの欠落と不適切な値を拒否します。
  • 意識的に置換する:Shopifyがそれをマージしないため、完全なプロパティオブジェクトを送信します。

すべての値を永遠に盲目的にコピーすることでこれを解決しないでください。プロパティは廃止されている可能性があり、顧客が管理している可能性があり、または製品の変更後に適切でなくなる可能性があります。統合は、どのキーが保持される、削除される、または再生成されるかを定義する必要があります。

より大規模な実装の場合、Shopifyアプリ開発リソースは、認証、Webhook、データコントラクト、および更新処理を1つのシステムとして検討するのに役立ちます。ストアフロントと注文レイヤーで作業しているエージェンシーは、ワークフローがテーマフィールドを超えたカスタム実装が必要な場合、Shopifyサービスも評価できます。

ワークフローが実際にサポートしている内容を検証する

提供されているShopifyドキュメントは、置換セマンティクスと秘密鍵の処理を確認しています。すべてのサーフェスに対してユニバーサルなプロパティ数または文字長制限を確立していません。特定のアプリ、エンドポイント、またはテーマの実装が独自の制約を持っているという理由だけで、ドキュメントに記載されていない制限を検証に追加しないでください。

代わりに、使用する正確なリクエストパスをテストしてください。空の値、繰り返される更新、Unicode文字、長いメッセージ、ファイル参照、および秘密鍵を確認してください。開発環境でリクエストとレスポンスをログに記録し、本番環境のログから機密の顧客データを削除してください。

信頼できるプロパティデータに関するマーチャントのベストプラクティス

プロパティキーを小さなスキーマとして扱ってください。engraving.textやgift.wrap_messageなどのキーは開発者に対してフィールドが何を表しているかを示し、安定した機械名により、表示ラベルが変更されても統合が破損しません。

実装がそれを許可している場合は、顧客ラベルを内部キーから分離してください。顧客は「Engraving message」を見ることができますが、コードは安定した識別子を使い続けます。キーが既にライブオーダーまたはダウンストリームマッピングで使用されている場合は、軽率に名前を変更しないでください。新しいキーを追加し、データモデルを変更する必要がある場合は移行計画を定義してください。

実用的な運用基準

  • カートに追加する前に検証:必須のパーソナライゼーションは、空の値としてチェックアウトに到達してはいけません。
  • 値を読みやすく保つ:フルフィルメントスタッフは、省略形を翻訳することなく注文を理解する必要があります。
  • 可視性と操作を分離:顧客ビューに表示されないようなメタデータには、アンダースコアが前に付いたキーを使用してください。
  • 確認メッセージで送信された選択肢を表示:顧客は自分がリクエストしたことを確認できる必要があります。
  • 情報源を保持:別のシステムがプロパティをコピーする場合は、元のラインアイテム値を保持し、マッピングを文書化してください。
  • 初期チェックアウトだけでなく、編集もテスト:プロパティフロー は、サポートチームが行うことを期待する更新に耐えるまで完全ではありません。

ラインアイテムプロパティは有用な注文データですが、自動的にすべてのShopifyデータ構造の代替にはなりません。値をクエリ、レポート、または特定の購入ラインから独立して保守する必要がある場合は、注文メタフィールドまたは別のリソースがより適切かどうかを評価してください。

購入後ワークフローにおけるラインアイテムプロパティ

ラインアイテムプロパティの最も強力な使用は、注文が配置された後に表示されます。パーソナライゼーション値はフルフィルメントに通知を与え、内部フラグは生産をルーティングし、顧客向けの値は注文レビューをサポートできます。プロパティは、買い手の指示と、それに対応するチームまたはシステム間の接続になります。

セルフサービスの注文編集アプリケーションは、ラインのパーソナライゼーションを読み取り、既存の値を顧客に提示し、同じキーの下で改訂された値を書き戻すことができます。そのワークフローは、アプリケーションが正しいラインを特定し、更新中に完全なプロパティオブジェクトを送信する場合にのみ確実に機能します。

同じ原則は再購入とご購入後のオファーにも適用されます。リオーダーエクスペリエンスは前回のプロパティ値をデフォルトとして使用できますが、再利用可能な設定と一回限りの指示を区別する必要があります。誕生日メッセージは特定の注文に固有かもしれませんが、刻印形式は再度役立つかもしれません。

各ダウンストリームユーザーに明確な契約を提供する

フルフィルメントは実行可能な値が必要です。カスタマーサポートは読みやすい値が必要です。外部システムは予測可能なキーが必要です。製品フォームにさらに多くのフィールドを追加する前に、これらの期待値を定義してください。

たとえば、本番ワークフローはEngraving Textを消費する一方で、プライベートな_production_routeプロパティは内部プロセスにアイテムが どこへ行くべきかを伝えます。ストアフロントはルーティングの詳細を公開する必要はなく、フルフィルメントシステムは顧客向けのラベルだけに依存するべきではありません。

よくあるエラーと修正方法

ほとんどの失敗は3つの場所のいずれかに遡ることができます。製品フォーム、カート更新リクエスト、または注文を読むテンプレートまたは統合です。

エラーの症状 考えられる原因 クイック修正
カート更新後にプロパティが消える 更新は変更されたキーのみを送信し、完全なオブジェクトを置き換えた 現在のプロパティを読み取り、変更をマージし、完全なオブジェクトを送信します。
フィールドはページに表示されるがカートには表示されない 入力名がproperties[...]パターンを使用していないか、JavaScriptが省略した カートへの追加リクエストを検査し、送信されたフィールド名を確認します。
プライベート値が顧客向けビューに表示される キーが_でプレフィックスされていないか、表示コードがフィルタリングなしで表示している プライベートメタデータに下線プレフィックスを使用し、カスタムレンダリングでプライベートキーをフィルタリングします。
統合がプロパティを見つけられない 異なるキーのスペリングを期待するか、下線を削除している 安定したキーを定義し、プロパティがプライベートの場合は_key_nameを正確に参照します。
通知に空白のラベルが表示される テンプレートが間違ったオブジェクトを読むか、すべての行にプロパティが存在することを前提としている 通知の行項目変数を検査し、不足している値を安全に処理します。
交換アイテムがパーソナライゼーションを失う 新しい行が古いペイロードをコピーせずに作成された 必要なプロパティのみを再適用し、交換が保存される前に検証します。

カートキャプチャの問題にはブラウザ開発者ツールを使用してください。ダウンストリームの問題には注文データとWebhookペイロードを使用してください。最速の診断は、最終的なメールやフルフィルメント画面を単独でデバッグするのではなく、各境界での値を比較することから得られます。

Shopify 行項目プロパティの クイックリファレンス

テーマ、カートスクリプト、または注文統合を変更する前に、この表をコンパクトなレビューとして使用してください。

質問 実用的な回答
プロパティとは何ですか? 特定のカートまたは注文ラインアイテムに付属するキーと値のメタデータ。
それはバリアントですか? いいえ。購入されたアイテムに付属し、カタログバリアントを表していません。
テーマでどのようにキャプチャされますか? properties[Key]パターンで名前を付けられたproduct-formフィールドを使用してください。
カートに保存される場所はどこですか? ラインアイテムのpropertiesオブジェクト内。
更新中に何が起こりますか? 送信されたプロパティオブジェクトが既存のオブジェクトを置き換えるため、完全なセットを送信してください。
運用メタデータを隠すにはどうしたらいいですか? キーの前に_を付けて、その後のシステムでその正確なキーを参照してください。
統合は何を検証すべきですか? 必須キー、期待される値、表示ルール、および使用中の正確なAPIまたはカートパスの動作。
何をテストすべきですか? 初回カートへの追加、カートの更新、チェックアウト表示、通知、注文の読み取り、および購入後の編集。

耐久性のある実装の考え方は単純です: 正しいラインでプロパティをキャプチャし、更新中に完全なオブジェクトを保持し、すべての下流システムに明確な契約を与えてください。このアプローチにより、基本的なパーソナライゼーションのデモではめったに公開されない微妙なデータ損失を防ぐことができます。


Mayra Appsは購入後の注文編集とアップセル用のツールを提供しており、顧客向けの変更は注文ステータスページと顧客アカウントを通じて管理され、Shopifyが記録のシステムのままです。ラインアイテムプロパティワークフローが管理された注文変更と接続する必要がある場合は、Mayra Appsにアクセスして利用可能なアプローチを確認してください。