shoplazza-products

shoplazza CLI — products モジュール

重要 — 何よりも先に、../shoplazza-common/SKILL.md を Read してください。 このファイルには、すべての横断的な仕組みが記載されています。3 つのアクセス階層、出力エンベロープ（.data）、 --dry-run、--jq（「-r を渡さない」ことを含む）、--fields、schema、api rest、認証／プロファイル、 および安全プロトコルです。このファイルでは products ドメインのみを扱い、それらについて繰り返しません。

概要

products モジュールは、商品とそのバリエーション、価格、在庫、 タグ、画像、コレクション、ギフトカード、顧客レビュー、倉庫の所在地、 サプライヤー、調達など、商品カタログを管理します。3 つのアクセス階層すべてが適用されます（階層選択ルールは shoplazza-common に記載されています — +shortcut を優先してください）。

+update または +delete ショートカットはありません — 更新と削除は仕様のリーフコマンドです。 Products は大規模なドメインです。このファイルはルーターと高頻度の操作を扱い、 サブリソースごとの詳細は references/（バリエーション、在庫／所在地、 コレクション／collects、画像、ギフトカード、コメント、調達／サプライヤー）に記載されています。

コマンド一覧

意図 → コマンド。最も適合する階層を優先します。正式なフラグ／パラメーターはこの表ではなく、 shoplazza products <cmd> --help と shoplazza schema products.<cmd> に記載されています。

ユーザーの意図	コマンド
商品を検索／絞り込み	products +search [--keyword <title-word>] [--vendor <exact>] [--published published|unpublished|any] [--collection-id <id>] [--fields id,title]
商品数を数える	products +count [--published …]
単一バリエーションの商品を作成	products +create --title <name> --price <n> --image <url> [--published]
複数仕様の商品を作成（规格矩阵: color × size × …）	2つの手順で行います：products +create --title <name> --price <n> --image <url> を実行し、続けて products +set-variants --id <new-id> --add "Color:Red,Blue" [--add "Size:S,M"] を実行します（作成されたバリエーションが最初の組み合わせになり、ほかの組み合わせにはその価格がコピーされます）
仕様値や仕様項目の追加／削除／置換／名前変更、価格バリエーションの変更を1回の呼び出しで任意に組み合わせて実行	products +set-variants --id <product-id> [--add|--remove|--set "Name:v1,v2"] [--drop "Name[=value]"] [--rename "Name:old=new"] [--new-price …] [--set-price …]
商品を公開	products +publish --id <product-id>
商品を非公開（下架）にする	products +unpublish --id <product-id>
バリエーションの価格を変更	products +set-price (--variant-id <id> | --sku <sku> [--all] | --product-id <id>) --price <n>
在庫を調整（追加または減少）	products +stock (--variant-id <id> | --sku <sku> | --product-id <id>) (--adjust <±n> | --set <n>) [--location-id <id>]
タグを追加／削除／置換	products +tag --id <product-id> (--add a,b | --remove c,d | --set x,y)
商品を1件取得	products get --params '{"product_id":"<id>"}'
商品一覧を取得（+search では対応していないフィルター：ID、ハンドル、日付範囲、SPU など）	products list --params '{…}'
全項目を指定して作成（ショートカットでは指定できないフィールド）	products create --data '{"product":{…}}'（schema products.create を参照）
商品のフィールドを更新	products update --params '{"product_id":"<id>"}' --data '{"product":{…}}'
商品を1件削除	products delete --params '{"product_id":"<id>"}'
商品を複数削除	products batch-delete --params '{"product_ids":["<id>",…]}'
商品のバリエーション一覧を取得	products variants list --params '{"product_id":"<id>"}' → references/variants.md
バリエーションを更新（オプション、SKU、重量など）	products variants update --params '{"variant_id":"<id>"}' --data '{"variant":{…}}'
SKUでバリエーションを検索	products variants list-by-sku --params '{"sku":"<sku>"}'
キュレーションコレクションを作成	products collections create --data '{"collection":{"title":"…"}}' → references/collections-collects.md
商品をコレクションに追加	products collects create --data '{"collect":{"collection_id":"<cid>","product_id":"<pid>"}}'
商品に画像を添付	products images create --params '{"product_id":"<id>"}' --data '{"image":{"src":"<url>"}}' → references/images.md
ギフトカードを作成（保存価値は金銭に相当するため、先に --dry-run を実行）	products gift-cards create --data '{"gift_card":{"code":"…","initial_value":"…","expires_on":"YYYY-MM-DD"}}' --dry-run → references/gift-cards.md
ギフトカードの残高を確認	products gift-cards get --params '{"id":"<id>"}' --jq '.data.gift_card.balance'
ギフトカードを停止／「削除」（取り消し不可のため、先に --dry-run を実行し、承認を得てください）	products gift-cards disable --params '{"id":"<id>"}' --dry-run（削除エンドポイントはありません。無効化すると、引き換えが永久に停止されます）
在庫レベル／商品、ロケーション	products inventory … / products locations … → references/inventory-locations.md
顧客レビュー（评价）	products comments {list,create,batch-create} → references/comments.md
サプライヤー／調達注文	products suppliers … / products procurement … → references/procurement-suppliers.md
ストアフロントのカテゴリー	products categories list

リクエストへの対応

「新建商品 / 上架 / 调价 / 补货 / create a product / restock」は質問ではなく、操作です。

1. 意図に合うショートカットを選びます。下のトリガーテーブルを参照してください。
2. 必須フィールドを確認します（各ショートカットの デフォルトなし フラグ）。不足または曖昧な場合は、AskUserQuestion で確認し、決して作り上げないでください。特に --price（金額）と --image（推測できないアセット URL）が対象です。不足しているフィールドは複数回に分けず、1 回の質問にまとめてください。
3. CLI のデフォルト値があるフラグや、省略すると無効になるフラグについて質問してはいけません。デフォルト値を適用してください。
4. 必須項目がすべてそろっている場合は実行します。+shortcuts はそのまま安全に実行できます。削除、一括操作、ギフトカード作成（保存価値＝金額）では、shoplazza-common → Safety protocol に従い、まず --dry-run を使用してください。
5. できないことは正直に伝えます。プラットフォームで実行できない場合（たとえば、デフォルト以外のロケーションまたは複数ロケーションの商品の在庫数を減らす場合。詳細は references/inventory-locations.md を参照）、書き込みコマンドは出力せず、制限を説明して正当な代替案を提示してください。

トリガーフレーズ → ショートカット

ユーザーの発言	ショートカット	値の抽出方法
商品を検索 / 商品を探して / 検索 / 商品を一覧表示	+search	タイトルの単語 → --keyword（タイトルのみを照合）；供应商/ベンダー → --vendor（完全一致、入力どおり）；未掲載 → --published unpublished；掲載済み → --published published
商品はいくつある / 商品の合計数 / 販売中の商品数を教えて	+count	掲載済み → --published published；件数は .data.count から取得します。手作業で数えないでください
商品を新規作成 / 商品を登録 / 新商品を追加 / 新しい商品を作成	+create	商品名 → --title（入力どおり）；販売価格 → --price；メイン画像/画像 URL → --image；「掲載する」という表現があれば --published を追加；「下書きで保存/draft」の場合は --published を省略
カラーとサイズの選択肢がある商品を作成	+create の後に +set-variants --add	手順 1：上記のとおり +create を実行（下書き）；手順 2：各ディメンションにつき 1 つの --add "Name:v1,v2,…" を指定し（最大 3 つ、順序＝ストアフロントでの表示順）、1 回の呼び出しで実行（価格は不要：すべての組み合わせに +create で設定した価格がコピーされます；--existing は不要：作成したバリアントには最初の値が割り当てられます）；組み合わせごとの SKU には {Name} プレースホルダーを使った --sku-template を指定；最後に公開
色を 1 つ追加 / サイズをいくつか追加 / 仕様値を追加	+set-variants --add	--id（または名前から解決）；ディメンションと新しい値 → --add "Color:White"；既存の他のディメンションの組み合わせごとに新しいバリアントが 1 つ作成されます（以前削除された組み合わせは復元されません）；新しい組み合わせには --new-price が必要です（値ごとに指定する場合：--new-price "Color:White=19,Black=21"）。また、バリアント画像が必要な商品では --new-image も必要です
仕様ディメンションを丸ごと追加（例：サイズ仕様を追加）	+set-variants --add + --existing	未知のディメンション名は新しいディメンションとして扱われます。既存のバリアントには --existing "Size:<value>" で指定した値が割り当てられ（ディメンションに複数の値を設定する場合は必須）、ID/SKU/在庫/画像は維持されます。他の値には、価格/比較価格/重量/画像をコピーした新しいバリアントが作成されますが、SKU と在庫は設定されません（--new-stock で一括設定できます）。価格の指定は不要です。実行前に、現在のバリアントの値を確認してください
特定の色/サイズを削除	+set-variants --remove	--remove "Color:Red"；該当するバリアントは削除され、出力に一覧表示されます。値は正確な表記が必要です（大文字と小文字を区別し、大文字小文字だけが異なる場合は「did you mean」と表示して拒否されます）。存在しない名前/値はエラーです。表記を修正し、成功したと報告しないでください
特定の仕様で分類しない / ディメンションを丸ごと削除	+set-variants --drop	--drop "Size" はすべてのバリアントを保持します（ID も維持）。バリアントが 1 つの組み合わせに統合される場合は拒否されるため、どの値のバリアントを残すか確認してから --drop "Size=M" を指定します（他の値のバリアントは削除されます）
仕様値を…だけ残す / 全体を…に変更 / 1 つのディメンションの値を設定	+set-variants --set	--set "Color:Red,Blue" は、そのディメンションの値をこの値だけにします（順序＝ストアフロントでの表示順）。指定されていない値は、関連するバリアントとともに削除され、新しい値にはバリアントが作成されます
名前を変更 / Red をワインレッドに変更 / 値またはディメンションの名前を変更	+set-variants --rename	値 → --rename "Color:Red=Wine Red"（複数の場合："Color:Red=Wine Red,Blue=Navy"）；ディメンション → --rename "Color=Colour"；名前はその場で変更され、すべてのバリアントの ID/SKU/在庫/画像は維持されます。変更後の名前がすでに使われている場合は拒否されます（値を入れ替えるには一時的な名前を経由してください）。再度実行すると、旧名が見つからないという報告（「すでに名前が変更されていますか？」）が表示されます。これは変更が完了していることを意味します。名前変更を削除＋追加として処理しないでください
仕様変更が一文に複数含まれる場合（仕様の削除、一部の値だけを残す、名前変更、価格の統一など）	+set-variants を 1 回呼び出す	すべての変更（--drop/--set/--rename/--set-price など）を同じ呼び出しに含めます。固定順（削除、ドロップ、設定、追加、名前変更）に適用され、1 回のリクエストで書き込まれます。すべて現在の名前で指定してください（新しい名前を指定するのは --rename の右側だけです）。出力の changes リストに、実行される変更が表示されます
仕様値ごとに価格が異なる / S は 20 で、M は 30	+set-variants --set-price "Size:S=20,M=30"	その値を持つすべてのバリアントに値ごとの価格を設定します。値が新しい場合は --add と組み合わせます。数値だけを指定すると、すべてのバリアントの価格が変更されます
商品 X を掲載 / 商品 X を公開	+publish	ID → --id；名前しかない場合は、まず +search --keyword で解決します
非掲載にする / 商品を非表示にする / 公開を解除	+unpublish	ID → --id
価格を変更 / 価格を調整 / 価格を X に変更	+set-price	対象：バリアント ID → --variant-id；SKU → --sku；商品 ID → --product-id（その商品のバリアントが 1 つだけの場合に解決されます。複数バリアントの場合は候補を一覧表示して拒否されます）；名前しかない場合は、まず +search --keyword を実行します。新しい価格 → --price（入力どおり）；--price 0 は価格をクリアします（¥0 と表示するわけではありません）。この違いを説明し、0 を渡す前にユーザーの確認を得てください
比較価格 / 取り消し線付き価格	+set-price --compare-price	ユーザーが明示的に指定した場合のみ
在庫を N 個追加 / N 個補充 / 在庫を N 個追加	+stock --adjust N	追加/増加 N 個 = 正の差分 → --adjust N。対象：バリアント ID → --variant-id；SKU → --sku；商品 ID → --product-id（バリアントが 1 つの商品。複数バリアントの場合は候補を表示して拒否されます）；名前しかない場合は、まず +search --keyword を実行します。ユーザーにバリアント ID を尋ねないでください
在庫を N 個に設定	+stock --set N	目標値（≥ 0）を指定します。増減のどちらにも使えます。在庫の減少は、単一ロケーションの商品のデフォルトロケーションでのみ許可されます。対象フラグは「在庫を N 個追加」の行と同じです
在庫を減らす / 在庫を N 個減らす	+stock --adjust -N	減少/差し引き N 個 = 負の差分 → --adjust -N；結果が 0 未満になる場合、--location-id がデフォルトロケーションでない場合、または商品が複数のロケーションに在庫を持つ場合、CLI は拒否します。その場合は理由を説明し、代わりに +unpublish または在庫ポリシー deny を提案してください。対象フラグは「在庫を N 個追加」の行と同じです
タグを追加（既存のタグは保持）/ タグを追加	+tag --add	タグはカンマ区切りで指定します。既存のタグは保持されます
特定のタグを削除 / タグを削除	+tag --remove	存在しないタグは無視されます
タグをすべて…に置き換え / すべてのタグを置き換え	+tag --set	タグの一覧全体を置き換えます。「置き換える/変更後は…だけにする」という明示的な表現がある場合のみ使用してください
複数の行が一致する場合は、どれかを尋ねてください。推測しないでください。

必須か質問かのマトリックス

質問できるのは、デフォルト値のないフラグだけです。

ショートカット	ユーザーが指定していない場合に必ず尋ねる	可能であれば推測する	確認せずにデフォルトを適用
+create	--price、--image（まとめて一度に尋ねます。価格や画像 URL を決して捏造しないでください）	発話中の製品名から --title、上架／公開の表現から --published	--published（省略すると下書き）、--sku、--stock、--stock-policy（デフォルトは deny）、--compare-price、--tags、--collection-ids
+set-variants	--new-price は新しい値が追加される場合に限ります（既存の次元に値を追加する場合。次元を追加すると価格はコピーされます。削除や名前変更では不要です）。--new-image も同様に、CLI が製品にバリアント画像を必須としている場合に限ります（製品の画像のいずれかである必要があります）。次元のある製品に複数の値を持つ次元を追加する場合は --existing。--drop によってバリアントが統合される場合は、残す値。次元と値（仕様値を決して創作しないでください。ユーザーの値の表記をそのまま保持してください。値は大文字と小文字を区別します）	表現から編集フラグを判断します（加→--add、删／去掉→--remove、不按…分→--drop、只保留／换成→--set、改名／改成→--rename、统一价／都卖→--set-price）。+search で名前から --id を特定します	--sku-template、--set-stock、--new-stock（任意。省略すると SKU／在庫は変更されません）
+set-price	--price（数値を決して創作しないでください）	ユーザーが指定した対象から判断します。バリアント ID → --variant-id、SKU → --sku、製品 ID → --product-id（その製品の唯一のバリアントを特定します）。バリアント ID は尋ねず、特定してください	--compare-price、--all（ユーザーが SKU に一致するすべてのバリアントを明示的に指定した場合のみ）
+stock	数量 — それ以外は何も尋ねません。バリアント ID や在庫アイテム ID は尋ねず、特定してください	表現から --adjust と --set を判断します（加 N = --adjust N、减／扣 N = --adjust -N、设为 N = --set N）。対象は +set-price と同様です。バリアント ID → --variant-id、SKU → --sku、製品 ID → --product-id。ここでは --all は使用しません。在庫の書き込み対象は 1 つのバリアントです	--location-id（デフォルトのロケーションが適用されます）
+publish / +unpublish	--id（または +search で名前から特定します）	—	—（--id のみを受け取ります）
+tag	--id、タグの値	表現から追加／削除／設定のモードを判断します	—
+search / +count	(なし — すべてのフィルターは任意です)	表現からフィルターを判断します	--page-limit、--fields

識別子の段階 — 尋ねずに特定してください。 販売者が把握しているのは、製品名と製品 ID です。 バリアント ID と在庫アイテム ID は内部処理用のもので、販売者が目にすることはありません。以下の各段階はそれぞれ 1 つのコマンドです。ユーザーが持っていない ID を尋ねるのではなく、段階を順に進んでください。

name  --(+search --keyword)-->  product id  --(--product-id, single-variant)-->  variant id
                                product id  --(products variants list)-------->  variant id
                                variant id  --(+stock resolves it internally)->  inventory item id

段階で曖昧さが本当に残る場合に限り、尋ねてください。つまり、製品に複数のバリアントがあり、ユーザーの言葉から対象を特定できない場合です。--product-id はそのケースでは候補を一覧表示して拒否します。その一覧から選んでもらってください。ユーザーに代わって variants[0] を選ばないでください。

サブリソースに関する質問（末端の階層でも同じルールです）：

• gift-cards create — code と initial_value が指定されていない場合は必ず尋ねてください（保存金額は通貨の値です。決して捏造しないでください）。customer_id／send_email は任意です。顧客について確認するのは問題ありませんが、顧客を創作してはいけません。
• variants update — ユーザーが変更を求めたフィールドのみを送信してください。リクエスト本文に余計な項目を追加しないでください。

質問しない項目のリスト

CLI のデフォルト値があるフラグ、または省略すると無効になるフラグは、質問に含めません： --location-id（デフォルトのロケーション） · --stock-policy（デフォルトは deny） · --published （省略すると下書き；公開を明示する表現がある場合のみ設定） · --compare-price · +create の --sku ／ --stock ／ --tags ／ --collection-ids（任意） · --page-limit · --fields（ユーザーが特定のフィールドを求めた場合のみ使用） · --all（明示的な一括操作の 上書き指定の場合のみ） · +set-variants の --sku-template ／ --set-stock ／ --new-stock（任意） · +set-variants の編集フラグ（表現から判断：加 = --add、删 = --remove、 不按…分 = --drop、只保留 = --set、改名 = --rename）。

判断例

ユーザーの発言	判定
「商品を新規作成：Lycra ヨガパンツ、価格 39.99、メイン画像は https://…/yoga.jpg、まずは下書き保存」	作成 — +create --title "Lycra 瑜伽裤" --price 39.99 --image https://…/yoga.jpg；下書き保存 = --published を省略
「新しい Tシャツ商品を出品して」	質問 — 価格と画像が未指定（まとめて質問）。タイトル T恤 は使用可能；ユーザーが出品と言っているため --published を指定する計画
「SKU TSHIRT-RED-M の価格を 24.99 に変更して」	作成 — +set-price --sku TSHIRT-RED-M --price 24.99；単一バリエーションの意図なので --all は不要
「バリエーション 998877 の価格を調整して」	質問 — 新しい価格；対象の --variant-id 998877 はすでに判明しています
「バリエーション 12345 の在庫を 50 個増やして」	作成 — +stock --variant-id 12345 --adjust 50
「バリエーション 88664 の在庫を 30 個減らして」	作成 — +stock --variant-id 88664 --adjust -30；CLI が拒否した場合（0 未満／デフォルト以外のロケーション／複数ロケーションの商品）は、理由を伝えて代替案を提示します
「常連客にギフトカードを贈って」	質問 — initial_value と code（金額は絶対に捏造しない）
「ブラジャーセットを作成して。色は 3 種類、ブラのサイズは 15 種類、ショーツのサイズは 6 種類、すべて 29.99」	まず --image を質問してから、2 段階で実行：+create --title … --price 29.99 --image … → +set-variants --id <new> --add "Color:…" --add "Bra Size:…" --add "Brief Size:…"（すべての組み合わせに 29.99 を引き継ぎます）
「この商品に White の色を追加して」	作成 — +set-variants --id <id> --add "Color:White" --new-price <n>；不明なら価格を質問します（新しい組み合わせに価格が必要です）
「出品中の T シャツにサイズのバリエーション S/M/L を追加して」	先に質問 — 現在のバリエーションのサイズを確認します（ID／SKU／在庫は維持されます）。ほかのサイズは各色の価格で作成されますが、SKU はなく、在庫はゼロです。その後、+set-variants --id <id> --add "Size:S,M,L" --existing "Size:<answer>"
「赤をワインレッドに改名して」	作成 — +set-variants --id <id> --rename "Color:Red=酒红"（その場で変更；ID／SKU／在庫は維持）
「lenses の規格分けをやめて 6lenses だけ残して、スタイルは Ocean だけにして 2 lenses に改名、価格はすべて 19.9」	先に確認（バリエーションが削除されます） — 1 回実行：+set-variants --id <id> --drop "lenses=6lenses" --set "Style:Ocean" --rename "Style:Ocean=2 lenses" --set-price 19.9 --dry-run。返された changes を伝えてから実行します
「lenses の規格分けをやめて」（lenses に複数の値がある場合）	質問 — どの lenses 値のバリエーションを残すか確認し、その後 --drop "lenses=<value>"

境界

商品関連に見えても、実際には別の場所に属するもの、およびこのドメインが扱う類似項目：

～のように見えるもの	実際の所属先	コマンド
割引コード／クーポンコード／一定額以上の割引／フラッシュセール／割引・クーポンコード	shoplazza-discounts	discounts +*
ギフトカード／プリペイドカード／ギフトカード（引き換え可能なストアクレジット）	ここ（割引でも請求でもありません）	products gift-cards …
ファイルをメディアライブラリにアップロードする／ストアのメディアライブラリアセット	shoplazza-shop	shop files / shop +upload-file
商品に画像を添付する／商品に紐付けられた画像	ここ	products images create
ホームページのカルーセル画像／カード内の画像／テーマカード内の画像	shoplazza-themes	themes +page → themes +edit
商品詳細ページのテンプレート／カスタム商品ページテンプレート	shoplazza-themes	themes template create
商品のメタフィールド／商品またはストアのメタフィールド	shoplazza-shop	shop metafields-resource / metafields-definition
在庫同期／補充／在庫と倉庫在庫	ここ（注文／フルフィルメントではありません）	products +stock / products inventory
購入者の評価／レビュー／商品レビュー	ここ（ストアブログ／ページのコンテンツではありません）	products comments …
ブログ／カスタムページ／ストアフロントのコンテンツページ	shoplazza-shop	shop blogs / shop pages

Collections と collects — ドメイン内の注意点： collections はコレクションそのもの（タイトル、画像、SEO、スマートルール）で、collects は商品とコレクションを紐付ける関連付けレコードです。「商品をコレクションに追加する」は collects create を使います。collections update は使いません。references/collections-collects.md を参照してください。

権限 · スコープ

認可はコマンドごとではなく、--domain の単位となるドメインごとに行われます。認可フローについては shoplazza-common → Authentication を参照してください。

操作	必要な権限	付与方法
読み取り（get / list / +search / +count / サブリソースの読み取り）	products の読み取りスコープ	auth login --domain products
書き込み（+create / +publish / +set-price / +stock / +tag / 作成 / 更新 / 削除 / サブリソースへの書き込み）	products の書き込みスコープ	auth login --domain products

正確なスコープのリテラルは shoplazza auth scopes で確認してください。--domain products を指定すると、それらが展開されます。

注意点

このドメイン固有の落とし穴のみを記載しています（.data プレフィックスや -r を付けない --jq などの一般的な注意点は shoplazza-common に記載されています）。

症状	原因	修正方法
在庫の減少が拒否される	inventory_levels の書き込みリーフ（set-stock／update-level）は追加のみです。減少には variant.inventory_quantity を使用しますが、これはデフォルトロケーションのみを対象とし、複数ロケーションの商品では検証されていません。そのため、+stock は条件に応じて処理を制限します	+stock --adjust -N／--set N を使います。制限が適用された場合は理由を説明し、代替案（非公開にする、在庫ポリシーを設定する）を提示します
ユーザーは下書きを希望していたのに、商品が公開された	+create の --published は値を取らないブール値フラグです。指定すると公開されます	下書きにするには --published を一切指定しません（デフォルトは下書きです）
+count／その他のショートカットで unknown flag: --fields と表示される	このモジュールで --fields が使えるのは +search のみです	それ以外では --jq を使って必要な項目を抽出します
+search --fields の結果に指定したフィールドがない	名前はレスポンスのキー（primary_image、price_min など）です。誤字や不明な名前は API によって黙って無視されます。id、title、created_at、updated_at は指定にかかわらず返される場合があります	デフォルトの出力、または schema products.list --view response で名前を確認します。または --fields を使わずに --jq で必要な項目を抽出します
更新後にタグが消えた	products update（リーフ）はタグ一覧全体を置き換えます。+tag --set も同様です	+tag --add／--remove を使います。既存のタグは保持されます
variants 配列を指定した products update（リーフ）の後にバリアントが消えた	この配列は全置換です。指定されていないバリアントは削除され、id のない指定済みバリアントはオプション値（大文字小文字を区別）で照合され、一致するものがない場合は再作成されます（SKU／在庫はリセットされます）	リーフで variants 配列を手作業で指定しないでください。既存のバリアントをマッピング（IDを引き継ぎ）し、削除されるものをすべて報告する +set-variants（値ごとの価格も指定可能）を使います
大規模なマトリックスで products update／create を実行すると「Result too large」と表示される	レスポンスには商品全体が含まれます。バリアントが数百件ある場合、約25個のフィールドがそれぞれ返されます	出力サイズが制限される +set-variants を使います。リーフでは必ず --jq で結果を絞り込み、--data @file で本文を渡します
書き込み結果が「result too large」と表示され、再試行しようとしている	エコーされた結果が大きすぎただけで、リクエストは成功している可能性が非常に高いです	再送信しないでください。まず products variants count --params '{"product_id":"<id>"}' で確認します
仕様の次元を追加した後、1つのサイズだけに在庫がある	次元を追加すると、既存の各バリアント（ID、SKU、在庫、画像）は --existing の値に引き継がれます。他の値は新しいバリアントとなり、価格はコピーされますが、SKU／在庫はありません	これは想定どおりです。残りは --new-stock、+stock、または --sku-template で設定します。出力の remapped_detail／created_detail で、各バリアントの割り当て先を確認できます
+set-variants が「would merge variants that differ only by it」で拒否された	次元を削除すると、2つのバリアント（例：Red/S と Red/M）が同じ組み合わせになり、一方のデータしか保持できません	どちらの値のバリアントを残すかユーザーに確認し、他の変更と同じ呼び出しで --drop "Size=<value>" を指定します
削除して追加する方法で値の「名前を変更」したら、SKU／在庫が失われた	削除して追加すると、古いバリアントが削除され、新しいバリアントが作成されます	--rename "Color:Red=赤" を使います。値がその場で変更されます
+set-variants の出力に sku_may_be_stale と表示される	保持されたバリアントの SKU が、現在は存在しない値を示しています（次元の削除／値の変更によるものです）	ユーザーに伝えます。新しい SKU を希望する場合は --sku-template で再生成します
+set-variants が S と s を別の値として扱う	サーバーでは値の大文字小文字が区別されます。同じ次元に大文字小文字だけが異なる新しい値を追加しようとすると拒否されます（追加、更新、新しい次元）。削除には正確な表記が必要です	正確な表記を使います。--rename で表記を変更します
商品には仕様値が表示されているのに、バリアントがない	他の変更ではその値はそのまま残ります。--add／--set で指定すると、その値のバリアントが作成されます（他の次元の既存の組み合わせごとに1つずつ作成されます。--new-price が必要です）	これは想定どおりです。提供すべきでない場合は --remove で削除します
+set-variants に --new-price を渡したのに、一部の価格が変わらなかった	--new-price はコピー元がない新しいバリアントの価格のみを設定します。既存の価格は変更しません（出力の price_applied／warnings に表示されます）	--set-price で価格を変更します（すべてのバリアント、または値ごとに "Size:S=20" のように指定できます）
新しい商品を注文できず、在庫が設定されているのに API が「Out-of-stock」と返す	商品が下書きになっています（+create のデフォルト）。下書きは注文できず、エラーメッセージは誤解を招きます	先に products +publish --id <id> を実行します
+set-price --sku が候補一覧を表示して拒否された	SKU が複数のバリアントに一致したため、CLI が複数一致を拒否しています	表示された候補から適切な --variant-id を選ぶか、「すべて」を明示的に指定する場合に限り --all を渡します
--variant-id に商品 ID を指定すると 404 No variants found（または「no inventory item found for that variant」）になる	--variant-id はバリアント単位の指定です（PUT /variants/{variant_id}）。商品 ID は一致しません	代わりに --product-id に渡します。エラーの hint にもその旨が表示されます。または先に products variants list --params '{"product_id":"<id>"}' で一覧を取得します
--product-id が「product … has N variants」で拒否された	複数バリアントの商品には、単一の価格や在庫の対象がありません	hint に示された候補を使ってユーザーにどれを指定するか確認します（候補は最大10件で、残りを一覧表示するコマンドも記載されます）。その後、--variant-id または --sku を指定して再実行します。variants[0] を推測で選んではいけません
+set-price --price 0 の後に価格が消えた	'0'／'0.00' は価格を0に設定するのではなく、消去します	ユーザーが価格の消去を希望する場合にのみ 0 を渡します
gift-cards delete を実行したかった	削除エンドポイントはありません（サブコマンド：batch-create／create／disable／get／list／update）	gift-cards disable で引き換えを停止できます。削除ではなく無効化であることをユーザーに伝えます
パスに product_id を指定して variants update が 404 になる	variants get／update はバリアント単位です：/variants/{variant_id}。product_id は指定しません	variants list／create／delete のみが商品単位です（delete には両方の ID が必要です）
inventory set-stock がバリアント ID を拒否する	在庫レベルは inventory_item_id をキーとします。これはバリアント ID とは異なります	先に inventory list-by-variant --params '{"variant_ids":["<id>"]}' で対応関係を確認します
必須フィールドがないため comments create が拒否される	star、like、created_at、user_name、content、product_id はすべて必須です	references/comments.md を参照してください。不明な場合は like: 0 を使います
「合集に追加」を collections update で実行しようとした	商品とコレクションの関連付けは collect レコードです	1件なら collects create、複数なら collects batch-create を使います
存在しない +delete／+update ショートカットを使おうとした	これらは存在しません	delete／batch-delete／update は仕様のリーフです（Command map を参照）

レシピ

# 1. All unpublished products from vendor Nike
products +search --vendor Nike --published unpublished

# 2. Ids, titles and main image only, of products with "hoodie" in the title
products +search --keyword hoodie --fields id,title,primary_image

# 3. How many published products?
products +count --published published --jq '.data.count'

# 4. Create a draft product (draft = no --published)
products +create --title "Lycra 瑜伽裤" --price 39.99 --image https://cdn.example.com/yoga.jpg

# 5. Publish a product you only know by name
ID=$(products +search --keyword "瑜伽裤" --jq '.data.products[0].id')
products +publish --id "$ID"

# 6. Restock / reprice a product you only know by product id (single-variant product)
#    --product-id resolves the one variant. A multi-variant product is refused with
#    its candidates listed — show them to the user and let them pick.
products +stock --product-id 7ab09fcd-2ee7-4118-8c4d-e44a10d51caf --adjust 50
products +set-price --product-id 7ab09fcd-2ee7-4118-8c4d-e44a10d51caf --price 24.99

# 7. Multi-variant product: resolve the variant the user actually named, then write.
#    Pick by the option the user said (XL), never by position. If the user named no
#    option, ask which variant — don't take variants[0].
VID=$(products variants list --params '{"product_id":"9036f033-c605-4b6f-8a08-1b7ae090791c"}' \
  --jq '.data.variants[] | select(.option2=="XL") | .id')
products +stock --variant-id "$VID" --set 20

# 8. Append tags without clobbering the existing ones
products +tag --id 445566 --add summer,sale

# 9. Delete one product — dry-run, restate, wait for the user's go-ahead, then run
products delete --params '{"product_id":"778899"}' --dry-run
products delete --params '{"product_id":"778899"}'          # only after the user agrees (next turn)

# 10. Batch delete — always dry-run first and restate the count
products batch-delete --params '{"product_ids":["111222","333444","555666"]}' --dry-run
products batch-delete --params '{"product_ids":["111222","333444","555666"]}'

# 11. Change one variant's size option (partial body — only the field to change)
products variants update --params '{"variant_id":"24680"}' --data '{"variant":{"option1":"XL"}}'

# 12. Create a multi-spec product: draft first, then add the dimensions (3 colors × 2 sizes = 6 variants)
ID=$(products +create --title "Yoga Set" --price 29.99 --image https://cdn.example.com/yoga.jpg \
  --jq '.data.product.id')
products +set-variants --id "$ID" --add "Color:Black,White,Pink" --add "Size:S,M" \
  --sku-template "YS-{Color}-{Size}"

# 13. Add one color to an existing product (existing variants untouched)
products +set-variants --id 7ab09fcd-…  --add "Color:White" --new-price 29.99

# 14. Add a whole dimension — existing variants become 70B (id/sku/stock kept); 70A/70C copy the
#     price with no sku/stock: ask which value the current variants are first
products +set-variants --id 7ab09fcd-… --add "Bra Size:70A,70B,70C" --existing "Bra Size:70B"

# 15. Drop one value / a whole dimension (deleted variants are listed in the output)
products +set-variants --id 7ab09fcd-… --remove "Color:Pink"
products +set-variants --id 7ab09fcd-… --drop "Size=M"

# 15b. Rename a value / a dimension in place (every variant keeps its id, sku and stock)
products +set-variants --id 7ab09fcd-… --rename "Color:Red=Wine Red"
products +set-variants --id 7ab09fcd-… --rename "Color=Colour"

# 15c. Several edits in one call — preview, relay "changes", then run
products +set-variants --id 7ab09fcd-… --drop "lenses=6lenses" --set "Style:Ocean" \
  --rename "Style:Ocean=2 lenses" --set-price 19.9 --dry-run

# 15d. Prices per value
products +set-variants --id 7ab09fcd-… --set-price "Size:S=20,M=25,L=30"

# 16. Put a product into a collection
products collects create --data '{"collect":{"collection_id":"999000","product_id":"555777"}}'

# 17. "Delete" a gift card you only know by code — resolve the id, preview the disable
#     (irreversible) in the SAME reply, then wait for the user's go-ahead
ID=$(products gift-cards list --params '{"keyword":"GC9988"}' --jq '.data.gift_cards[0].id')
products gift-cards disable --params '{"id":"'$ID'"}' --dry-run

参考資料

• references/variants.md — バリアントの CRUD、SKU の検索・更新、オプションの処理
• references/inventory-locations.md — 在庫アイテムと在庫レベルの違い、在庫減少の制御条件、ロケーション
• references/collections-collects.md — キュレーションコレクションとスマートコレクション、コレクト、カテゴリー
• references/images.md — 商品画像の CRUD
• references/gift-cards.md — ギフトカードのライフサイクル（削除不可。無効化）
• references/comments.md — カスタマーレビュー（インポート、一覧表示）
• references/procurement-suppliers.md — サプライヤー、調達注文
• コマンドごとのフラグ：shoplazza products <cmd> --help
• 仕様の各項目のパラメーター／本文／レスポンス：shoplazza schema products.<cmd>（ネストされた項目：schema products.variants.update）
• 横断的な仕組み（認証／ティア／出力エンベロープ／--dry-run／--jq／安全性）：../shoplazza-common/SKILL.md
• ショートカットの信頼できる情報源：shortcuts/products/*.go