shoplazza-shop

shoplazza CLI — shop モジュール

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

概要

shop モジュールは、ストアレベルの設定とコンテンツを扱うドメインです。ショップ情報／設定、 販売・トラフィック分析、メディアライブラリ（ファイル）、メタフィールド（3 つすべてのファミリー）、 ブログと記事、カスタムページ、ナビゲーションメニュー、URL リダイレクト、マーケット、ストア言語、 リアルタイムの配送レートキャリアサービスを扱います。広範ですが、各領域は浅く扱います。このファイルはルーターであり、サブ領域ごとの詳細は references/ にあります。

唯一のショートカットは +upload-file です。それ以外はすべて spec リーフ （--params／--data）です。3 つのアクセス層すべてが適用されます（shoplazza-common の tier ルールを参照）。

コマンド一覧

目的 → コマンド。適合度の高い層から順に記載します。正式なフラグ／パラメーターは、この表ではなく shoplazza shop <cmd> --help と shoplazza schema shop.<cmd> を参照してください。

ユーザーの目的	コマンド
ストア情報 — ストア情報／ドメイン／通貨／プランを確認	shop info get（任意の --params '{"fields":["id","domain"]}'）
カスタマーサービスのメールアドレスを変更（編集可能な唯一の項目）	shop info get --jq '.data.id' → shop info update --params '{"shop_id":"<id>"}' --data '{"shop":{"customer_email":"…"}}'
分析 — 指定期間の売上／注文数レポート	shop analytics overview --data '{"begin_time":"<unix-str>","end_time":"<unix-str>","indicator":["sales","orders"]}' → references/analytics.md
SKU の売上ランキング／売れ筋 SKU	shop analytics by-sku --data '{…,"sort_by":"sales_total","sort_direction":"desc"}'
SPU／ランディングページ／UTM の内訳	shop analytics by-spu（追加の type が必須）／by-land-page（dimensions が必須）／by-utm
検索キーワード分析／検索結果がなかったキーワード／サイト内検索キーワード	shop analytics search-keyword --data '{…,"sort_by":"count","sort_direction":"desc"}'（has_result は文字列 "0"／"1"）
トラフィックチャネル／トラフィックソース／チャネル別トラフィック	shop analytics traffic-channel（dimensions と metrics が必須）。有効なチャネル名：shop analytics traffic-channel-options
メディアライブラリ — ファイルを素材ライブラリにアップロード（公開 URL のみ）	shop +upload-file --source-url <url> [--source-url <url> …] [--folder <name>]
アップロードタスク／アップロード状況を確認	shop files task --params '{"task_id":"<id>"}'（ショートカットですでに一度取得します）
メディアライブラリを参照	shop files list（フォルダーのデフォルトは all_upload、page_size は 300 以下）
ファイルの詳細／ファイルを削除	shop files {get,delete} --params '{"file_uri":"<uri>"}'
メタフィールド — ストアレベルのメタフィールド	shop metafields-shop create --data '{"namespace":"…","key":"…","type":"string","value":"…"}' → references/metafields.md
商品／注文／顧客などにメタフィールドを設定（商品にフィールドを追加）	shop metafields-resource create --params '{"owner_resource":"product","owner_id":"<id>"}' --data '{"definition_id":"…","namespace":"…","key":"…","type":"…","value":…}'
メタフィールドのスキーマを定義（メタフィールド定義）	shop metafields-definition create --params '{"owner_resource":"…"}' --data '{"name":"…","namespace":"…","key":"…","type":"…"}'
ブログコンテンツ — ブログ記事を公開／新しいブログ記事	shop articles create --data '{"article":{"title":"…","content":"…","blog_ids":["…"]}}' → references/blogs-articles.md
ブログ（記事の入れ物）を管理	shop blogs list ／ shop blogs create --data '{"blog":{"Title":"…"}}'（タイトルのキーは大文字の Title）
カスタムページ — カスタムページ／会社概要／About Us	shop pages create --data '{"page":{"title":"…","content":"…"}}' → references/pages-redirects.md
ナビゲーションメニュー — ナビゲーションメニューを確認／メニューと項目を一覧表示	shop menu list（組み込みメニューの ID は header ／ footer。特定のメニューを 1 つ指定：--params '{"ids":["header"]}'）
メニューを新規作成／カスタムメニューを作成	shop menu create --data '{"title":"…","children":[…]}'（カスタムメニューのみ）
メニュー名／メニュー項目を変更／メニューを編集	shop menu update --params '{"id":"<menu-id>"}' --data '{"title":"…"}' — children を送信すると項目ツリー全体が置き換えられます（「注意点」を参照）
メニューを削除／カスタムメニューを削除	shop menu delete --params '{"id":"<menu-id>"}'（組み込みの header ／ footer は削除できません）
URL リダイレクト — 301 ／ リダイレクト	shop redirects create --data '{"redirect":{"from_url":"…","redirect_url":"…","status":"…"}}'（status は必須。「注意点」を参照）
マーケット — マーケットを作成／特定の国で公開	shop markets create --data '{"name":"…","countries":["JP"]}' → references/markets.md
言語 — 言語を追加／多言語化	shop languages supported → add → enable → publish → references/languages.md
配送業者サービス — リアルタイム配送料見積もりを提供する配送業者を登録	shop carrier-services create --data '{"carrier_service":{"name":"…","callback_url":"…","carrier_code":"…"}}' → references/carrier-services.md

書き込みのルール

設定ドメイン — 完全な確認マトリックスはありませんが、以下の書き込みにはデフォルト値のない必須フィールドがあります。 不足または曖昧な場合は、AskUserQuestion で一度にまとめて確認し、決して捏造しないでください。デフォルト値または任意のフィールドについては確認しないでください。

操作	不足時に必ず確認	暗黙的にデフォルト設定／確認しない
+upload-file	公開 URL（ローカルファイルの場合 → 機能を制限して対応：API が取得できるのは公開 URL のみであることを説明し、リンクまたはホストの提示を求める）	--folder（デフォルトは all_upload）
pages create	title	url、meta_*、independent_seo — 省略し、SEO フィールドを決して捏造しない
redirects create	from_url、redirect_url。文言から status の値が確定しない場合（スキーマに列挙値がないため、Gotchas を参照）	—
metafields-shop create	namespace、key、type、value	description、definition_id（この場合は任意）
metafields-resource create	owner_resource+owner_id、definition_id、namespace、key、value	description。type — 確認を求める前に定義から解決する（metafields-definition get）
markets create	name、countries	confirm — 決して暗黙的に true を渡さない（使用中のマーケットが削除されます）
carrier-services create	name、callback_url（ユーザー自身のエンドポイント — 決して作り出さない）、carrier_code	active、logo、short_desc
languages add	言語（複数可）。languages supported を使って IETF コードを解決する	—
info update	新しい customer_email	shop_id — info get で自分で解決し、確認しない
menu create	title。各項目のタイトルとリンク先（ID は自分で解決する）	category（常にカスタム 3）、target、disabled
menu update	対象のメニュー（menu list で ID を解決する）、変更内容	title / category — 変更しないよう省略する

破壊的な操作（pages batch-delete、markets delete — 取り消し不可、files delete、 redirects delete、metafields-* delete、menu delete、children を伴う menu update）→ まず --dry-run を実行して内容を再提示し、shoplazza-common → Safety protocol に従う。

対応範囲

他のドメインのように見える操作（または他のドメインに見えるショップ操作）：

目的	実際の担当	コマンド
商品／注文にメタフィールドを追加する / 商品のメタフィールド	ここ — 商品が所有するものも含め、すべてのメタフィールドはショップに属します	shop metafields-resource create --params '{"owner_resource":"product",…}'
商品画像／メイン画像／商品に添付された画像	shoplazza-products	products images create
ファイルのアップロード／素材ライブラリ／メディアライブラリのアセット	ここ	shop +upload-file / shop files …
売上／トラフィック／コンバージョンのレポート / 売上・トラフィック分析	ここ	shop analytics …
注文数の集計／注文検索 / 注文数・検索	注文ドメイン	orders +count / orders +search
リアルタイムの送料見積もりを提供する配送業者 / チェックアウト時に料金を見積もる配送業者	ここ	shop carrier-services …
配送業者の検索／配送伝票の追跡／フルフィルメント追跡の配送業者、配送ゾーン	注文ドメイン	orders tracking-carriers / orders shipping-schemas
カスタムページ／会社概要／ブランドストーリーのページ	ここ（テーマではなくコンテンツ）	shop pages create
ナビゲーションメニュー／メニュー項目／メインメニューへのリンク追加	ここ（メニューコンテンツ）	shop menu list → shop menu update
ヘッダーに表示するメニュー／メニューをヘッダーカードに関連付ける	shoplazza-themes	themes +edit（カードの link_list 設定）
テンプレートの変更／ストアのデザイン調整／テーマとテンプレートの編集、カスタムページのレイアウト	shoplazza-themes	themes +page / themes +edit / themes template …
ブログ／記事	ここ（商品レビューではありません）	shop blogs / shop articles
購入者のレビュー／商品レビュー	shoplazza-products	products comments …
クーポンコード／割引／割引コード	shoplazza-discounts	discounts +*

権限 · スコープ

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

操作	必要なもの	付与方法
読み取り（info get、analytics *、files list/get/task、* list/get/count）	shop 読み取りスコープ	auth login --domain shop
書き込み（+upload-file、* create/update/delete、languages enable/publish、…）	shop 書き込みスコープ	auth login --domain shop

正確なスコープ文字列は shoplazza auth scopes で確認してください。--domain shop はそれらのスコープに展開されます。

注意点

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

症状	原因	修正方法
アナリティクスの呼び出しが拒否される／結果が空になる	すべての analytics レポートは POST です（traffic-channel-options のみ GET です）。フィルターは --params ではなく --data に指定します。begin_time／end_time は UNIX 秒のタイムスタンプを文字列として渡す必要があります（"1782864000"）	タイムスタンプを計算し、文字列として引用符で囲んで --data で送信します
traffic-channel が 400 cannot unmarshal object … filters of type string を返す	filters は JSON オブジェクトを文字列としてエンコードしたものです。search-keyword の has_result も文字列です	"filters":"{\"last_referrer_first_show\":{\"operator\":\"in\",\"value\":[\"Social\"]}}"、"has_result":"0" を指定します。references/analytics.md を参照してください
menu update 後にメニュー項目が消えた	children は項目ツリー全体を置き換えます。含めなかった項目は削除され、[] を指定するとメニューがクリアされます	まずメニューを読み込み、ツリー全体を編集して、すべてを送り返します（既存の各項目の id は維持してください）。タイトルだけを変更する場合は children を省略します
ネストされたメニュー項目がフラットな状態で返された／ネストが失われた	menu list は項目をフラットな形式で返します。サブ項目は pid で親を参照します。書き込み時はネストされた children のみで階層を指定し（pid フィールドはありません）	children を送信する前に、pid からツリーを再構築します
メニュー項目の url_obj に何を指定すればよいかわからない	リンクの type の値はスキーマに列挙されていません	menu list で同じ種類の既存項目から url_obj（type ＋ source_id ＋ url）をコピーします。type や source_id を推測で作成しないでください
ショップ名／住所を更新しようとした	info update で編集できるフィールドは shop.customer_email の1つだけです	それ以外はこのエンドポイントでは更新できないことを伝えます
info update に必要な shop_id がユーザーにわからない	shop_id は必須のパスパラメーターです	先に shop info get --jq '.data.id' で取得します
ローカルファイルのアップロードを依頼された	+upload-file が受け取るのは公開 URL であり、ローカルファイルではありません（ヘルプに明記されています）。API が URL からファイルを取得します	対応を見送ります。書き込みは行わず、公開リンクを依頼するか、先にホスティングする方法を提案します
アップロードが「完了」したのにファイルがない	アップロードは非同期タスクです。POST は task_id を返し、ショートカットはタスクを一度だけ自動取得します	shop files task --params '{"task_id":"…"}' で再確認し、status／success_list が確定するまで繰り返します
blogs create でタイトルが無視される／拒否される	ブログタイトルのキーは小文字の title ではなく、大文字で始まる Title です（必須、1～100 文字）	shop blogs create --data '{"blog":{"Title":"…"}}' を実行します。フィールドは schema shop.blogs.create で確認してください
redirects の status に指定できる値は？	status は必須ですが、スキーマに列挙値は記載されていません。値を推測で作成しないでください	schema shop.redirects.create を確認するか、既存ルールを調べます（shop redirects list --jq '.data.redirects[].status'）。または OpenAPI ドキュメントを確認します。それでも不明な場合はユーザーに確認してください
metafields-resource create は拒否されるが、metafields-shop create は成功する	相違点があります。リソースレベルでは definition_id が必須ですが、ショップレベルでは任意です。タイプの列挙値も異なります（ショップ：JSON／string、リソース：single_line_text_field、integer など）	references/metafields.md を参照してください
言語を公開したら市場との関連付けが消えた	languages publish は完全な置き換えです。market_ids: [] を指定すると、すべての関連付けが削除されます	常に対象となるリスト全体を送信してください
言語を追加したが、ストアフロントに反映されない	追加された言語はデフォルトで無効です。未対応のコードは通知なく除外されます	add の後に languages enable を実行します。languages supported でコードを確認してください
confirm: true を指定して markets create/update を実行したら、他の市場が削除された	1つの国が所属できる市場は1つだけです。confirm: true を指定すると、重複する市場が自動的に削除されます	markets preview と --dry-run で事前に確認し、削除される内容を改めて伝えて、明示的な同意を得てください
metafields-definition get で、パスに ID を指定しても 404 になる	id はパスセグメントではなくクエリパラメーターです	shop metafields-definition get --params '{"id":123456}'

レシピ

# 1. Store's primary domain and currency
shop info get --jq '{domain: .data.domain, currency: .data.currency}'

# 2. Change the customer-service email (only editable field; two steps)
SHOP_ID=$(shop info get --jq '.data.id')
shop info update --params "{\"shop_id\":\"$SHOP_ID\"}" --data '{"shop":{"customer_email":"[email protected]"}}'

# 3. Sales + order count, 2026-07-01 .. 2026-07-15 (unix seconds as STRINGS)
shop analytics overview --data '{"begin_time":"1782864000","end_time":"1784159999","indicator":["sales","orders"]}'

# 4. Best-selling SKU over a window (sort desc by sales metric)
shop analytics by-sku --data '{"begin_time":"1782864000","end_time":"1784159999","sort_by":"sales_total","sort_direction":"desc","page_size":10}'

# 5. Upload a public image to the media library (async task; folder defaults to all_upload)
shop +upload-file --source-url https://example.com/banner.png

# 6. Create an "About Us" custom page
shop pages create --data '{"page":{"title":"关于我们","content":"我们是一家来自杭州的 DTC 品牌"}}'

# 7. Permanent URL redirect (status REQUIRED — pin the value via schema/existing rules first)
shop redirects list --jq '.data.redirects[].status'   # see what values live rules use
shop redirects create --data '{"redirect":{"from_url":"/old-sale","redirect_url":"/new-sale","status":"<verified-value>"}}'

# 8. Shop-level metafield (no definition_id needed at shop level)
shop metafields-shop create --data '{"namespace":"global","key":"support_phone","type":"string","value":"400-800-1234"}'

# 9. Product-level metafield (owner in --params, definition_id REQUIRED in --data)
shop metafields-resource create --params '{"owner_resource":"product","owner_id":"66880"}' \
  --data '{"definition_id":"D8899","namespace":"specs","key":"material","type":"single_line_text_field","value":"cotton"}'

# 10. Launch Japanese and publish it to the Japan market
shop languages supported --jq '.data.languages'   # find the exact IETF code
shop languages add --data '{"codes":["ja-JP"]}'
shop languages enable --params '{"language_code":"ja-JP"}'
MARKET_ID=$(shop markets list --jq '.data.markets[] | select(.name=="Japan") | .id')
shop languages publish --params '{"language_code":"ja-JP"}' --data "{\"market_ids\":[\"$MARKET_ID\"]}"

# 11. Rename a custom menu without touching its items (no children = items kept)
shop menu list --jq '[.data.menus[] | {id, title, category}]'   # category 3 = custom
shop menu update --params '{"id":"<menu-id>"}' --data '{"title":"Footer links"}'

リファレンス

• references/analytics.md — 7 つの POST レポートとチャネルオプションの検索、指標／ディメンション、並べ替えの列挙値、タイムスタンプのルール
• references/metafields.md — 定義、リソース、ショップのメタフィールド、owner_resource の列挙値、タイプの列挙値
• references/blogs-articles.md — ブログ（コンテナ）と記事（投稿）の違い。ブログのタイトルキーは大文字の Title
• references/pages-redirects.md — カスタムページの CRUD／一括処理、リダイレクトと、ドキュメントに記載されていないステータスの列挙値
• references/markets.md — マーケットのライフサイクル、国の占有／確認、価格／税／ドメイン／言語
• references/languages.md — 追加 → 有効化 → 公開の流れ、全置換のセマンティクス
• references/carrier-services.md — 料金見積もりを行う配送業者の登録
• コマンドごとのフラグ：shoplazza shop <cmd> --help
• 仕様の詳細パラメーター／本文／レスポンス：shoplazza schema shop.<cmd>（ネストされたコマンド：schema shop.metafields-resource.create）
• 複数の機能に共通する仕組み（認証／ティア／エンベロープ／--dry-run／--jq／安全性）：../shoplazza-common/SKILL.md