shoplazza-discounts

shoplazza CLI — 割引モジュール

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

概要

discounts モジュールでは、割引キャンペーン（自動適用とコードベース）と クーポン（バウチャー）キャンペーンを管理します。3つのアクセス階層すべてが適用されます（階層の選択ルールは shoplazza-common にあります。+shortcut を優先してください）。

+update、+cancel、+restart ショートカットはありません — これらのライフサイクル操作は spec のリーフコマンドです。

コマンド一覧

目的 → コマンド。正式なフラグ／パラメーターは、この表ではなく shoplazza discounts <cmd> --help と shoplazza schema discounts.<cmd> に記載されています。

ユーザーの目的	コマンド
割引率（クーポンコードあり）	discounts +percent-code --target order|product --percent <1-99>
固定額の割引（クーポンコードあり）	discounts +amount-code --target order|product --off <amt>
送料無料クーポン	discounts +free-shipping-code
Xを買うとYをプレゼント（クーポンコードあり）	discounts +bxgy-code（購入側の対象範囲 + 付与側の対象範囲）
フラッシュセール（自動適用、コードなし）	discounts +flashsale --value ...
N個購入でN個目を割引（自動適用、コードなし）	discounts +mn-discount --tiers "n:%,...”
購入額／購入数のしきい値に応じた自動割引	discounts +rebate --target order|product --tiers "th:disc,..."
割引を検索／絞り込み	discounts +search --query ... --progress ongoing
IDで割引を1件取得	discounts get --params '{"id":"<id>"}'
コードで割引を1件取得	discounts get-by-code --params '{"discount_code":"<CODE>"}'
割引をキャンセル	discounts cancel --data '{"ids":["<id>",...]}'
一時停止中の割引を再開	discounts restart --data '{"id":"<id>"}'
終了した割引を1件削除	discounts delete --params '{"id":"<id>"}'
終了した割引を複数削除	discounts batch-delete --data '{"ids":[...]}'
自動割引を更新	discounts update-automatic --params '{"id":"<id>"}' --data '<body>'
自動適用ではない（コード）割引を更新	discounts update-non-automatic --params '{"id":"<id>"}' --data '<body>'
異なる種類の割引の併用ルールを設定	discounts combine --data '<rules>'
クーポンキャンペーン（バウチャー）	discounts coupons {create,get,update}

リクエストへの対応

ユーザーが「X营销活动を作成して」／「フラッシュセールを作成して」／「割引コードを作って」／その他同様の依頼をした場合、これはアクションであり、質問ではありません。

1. 以下のトリガーテーブルを使って、意図に合うショートカットを特定します。
2. 必須フィールド（各ショートカットのデフォルトなしフラグ）を確認します。いずれかが不足または曖昧な場合は、AskUserQuestion で質問し、決して捏造しないでください。 実際の割引は加盟店の費用になるため、「とりあえず満100減10をデフォルトにします」は不適切です。
3. これらの必須かつデフォルトなしのフィールドについては、このスキルがセッションレベルの「確認質問をしない」という設定に優先します。 利用上限はこの対象ではありません（以下を参照）。
4. 必須項目がすべてそろっている → 実行します（+shortcuts は安全に実行できるよう設計されています。ユーザーが明示的に求めた場合にのみ、先に --dry-run を実行します）。
5. CLI にデフォルト値があるフラグについて、質問してはいけません。 例外はありません。<shortcut> --help に (default …)／省略時に自動生成／省略すると無効になる、と表示されるフラグは、いかなる AskUserQuestion にも含めてはいけません。デフォルト値を使い、ユーザーの表現で意味が明確な場合にのみ上書きします（例：「8折」→ --type=amount-percent）。

利用上限は任意です（省略すると上限なし）。 --limit-max／--limit-user（および flashsale の --limit-user-variant/-product/-all）には、設定すべきデフォルト値はありません。省略すると、割引は無制限になります。上限について質問してはいけません。また、-1 を渡してはいけません（CLI は -1 を拒否し、「must be > 0」と表示します）。例外として、期間が未定で、費用が発生するコード／クーポンキャンペーン（終了日なし＋上限なし）の場合は、引き換えが無制限になることを返信で伝えてもかまいません。ただし、伝えるだけにとどめ、実行を保留したり、AskUserQuestion にしたりしてはいけません。

質問禁止リスト（すべて CLI にデフォルト値があるか、省略すると無効になるため、質問してはいけません）： --start（デフォルトは now） · --end（デフォルトは -1／無期限） · --name（自動生成） · --code（自動生成） · --combines（デフォルトは空＝併用なし） · --limit-max／ --limit-user（省略すると上限なし） · --limit-user-variant／--limit-user-product／ --limit-user-all（flashsale。省略すると上限なし） · --limit-order（+bxgy-code、デフォルトは 1） · --limit-order-once（+amount-code／+rebate、デフォルトは true） · --type（デフォルトは +rebate では amount-off、+flashsale では percent） · --scope（+mn-discount ではデフォルトは highest） · --price-rule（+flashsale ではデフォルトは price） · --price-sort（+mn-discount ではデフォルトは desc） · --min-amount（デフォルトは 0） · --min-quantity（デフォルトは 1） · --countries（デフォルトはすべて） · --stock（省略すると商品在庫に従う） · --exclude（デフォルトは オフ） · --customer-segments（省略するとすべての顧客が対象）。

迷ったときは <shortcut> --help を実行してください。行に「(default ...)」、「auto-generated」、または「omit …」が含まれるフラグは、質問リストではなくデフォルト値に任せます。

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

ユーザーの発言	ショートカット	値の抽出方法
满X减Y / 订单满X减Y / Xを使うとY割引	+rebate --target order --type amount-off	--tiers "X:Y"；複数の段階「满200减20,满500减50」→ "200:20,500:50"
商品满X减Y / 商品にX使うとY割引	+rebate --target product --type amount-off	--products、--collections、または--variantsが必要です
满N件减Y元 / N個購入でY割引	+rebate --type qty-off	--tiers "N:Y"
满X享Y折 / 满X打Y折 / X使うとY%オフ	+rebate --type amount-percent	Yは割引率です。例：「8折」→ 20（つまり20%オフ） — 曖昧な場合は確認してください
满N件享Y折 / N個購入でY%オフ	+rebate --type qty-percent
第N件Y折 / 买N件第N件Y折 / N個目の商品がY%オフ	+mn-discount	Yを割引率として--tiers "N:Y"を指定します
闪购 / 限时秒杀 / 限时折扣 / フラッシュセール	+flashsale	自動適用され、コードは不要です。--valueと--typeを指定します。対象は--variants／--collectionsで指定します（省略すると全商品が対象です）
优惠码 + X% off / 折扣码立减Y% / X%オフクーポン	+percent-code	--percentはパーセンテージ（1～99）です
优惠码立减Y元 / 折扣码减¥Y / Y円オフクーポン	+amount-code	--offは割引額です
包邮码 / 免邮券 / 送料無料コード	+free-shipping-code	--off（一部割引）と--countriesは任意です
买X送Y / 买X赠Y / X個購入でY個無料	+bxgy-code	購入側の対象範囲と--buy-quantity／--buy-amount、獲得側の対象範囲と--get-quantityを指定します。--get-free／--get-percent／--get-off

複数の行に該当する場合は、どれかを尋ねてください。推測しないでください。

必須項目と確認項目のマトリックス

確認できるのは、デフォルト値がないフラグだけです。上限はここには含まれません — デフォルトで上限なしになります。

ショートカット	ユーザーが指定していない場合に必ず確認する項目	可能であれば推定する項目	確認なしでデフォルト設定する項目
+percent-code	--percent（%）、--target、--target=productの場合は--products／--variants／--collections	「订单／商品」という表現から--targetを推定	--min-amount、--min-quantity、上限、--combines、--code、--name、期間、--customer-segments、--exclude
+amount-code	--off（¥）、--target、--target=productの場合は対象範囲	表現から--targetを推定	+percent-codeと同じ項目に加えて、--limit-order-once
+free-shipping-code	—（厳密に必須の項目はありません）	ユーザーが「运费立减Y元」と指定した場合のみ--off	--off、--min-amount、--min-quantity、--countries、上限、--combines、--code、--name、期間
+bxgy-code	購入側の対象範囲、--buy-quantityまたは--buy-amount、獲得側の対象範囲、--get-quantity、--get-free／--get-percent／--get-offのいずれか	「买N件送M件」から購入数／獲得数を推定。「打折」／「立减」という表現から--get-percent／--get-offを推定（どちらにも該当しない場合は--get-free）	--limit-order（デフォルトは1）、上限、--combines、--code、--name、期間、--exclude
+flashsale	--valueのみ（--typeは確認しないでください — デフォルトはpercentです）	表現から--typeを推定（「X折／X%off」はpercent、「一口价Y元」はfixed-price、「立减Y元」はoff）。商品名から対象範囲を推定	--type（デフォルトはpercent）、対象範囲（省略すると全商品が対象）、--price-rule、--stock、ユーザーごとの上限、--combines、--name、期間
+mn-discount	--tiers	--scope（「最高档」＝highest、「全部档」＝all。highest-allもあります）	--scope、--price-sort、対象範囲のフラグ、上限、--combines、--name、期間、--exclude
+rebate	--target、--tiers	表現から--typeを推定 — 上のトリガー表を参照してください	--target=orderの場合の対象範囲、--limit-order-once、上限、--combines、ユーザーが明確に指定していない場合の--type、--name、期間

判断例

ユーザーの発言	判定
"帮我建个满减活动"	質問 — 段階設定と対象が未指定です
"创建一个满减活动，满200减20"	質問 — 対象が不明です（注文または商品？）
"创建一个满200减20的订单级满减活动，永不过期"	作成 — 必要な情報がすべて揃っています（+rebate --target order --tiers "200:20" --end forever）。上限の指定がない場合は無制限です
"Create a 15% off coupon code"	質問 — 対象が不明です（注文または商品？）
"Create a 15% off site-wide coupon code, max 100 uses, 1 per customer"	作成（+percent-code --target order --percent 15 --limit-max 100 --limit-user 1）
"创建闪购活动 50% off"	作成 — --value 50 だけで十分です（+flashsale --value 50）。適用範囲の指定は任意です。商品が指定されていない場合は、ストア全体に適用されることを必要に応じて伝えてください。

質問の方法

具体的な番号付き選択肢を使って AskUserQuestion を呼び出します。関連する項目は1回の質問にまとめてください （1回につき質問は4つまで）。質問可能な項目のすべては次のとおりです。

質問の種類	質問する場合	選択肢の例
対象範囲（--target）	ユーザーが「订单/商品」と指定していない場合の +percent-code／+amount-code／+rebate	「注文レベル」、「商品レベル」
段階設定（--tiers）	+rebate／+mn-discount で指定されていない場合	自由入力：しきい値:割引 の組み合わせリスト
割引値（--percent／--off／--value）	ユーザーが数値を指定せず、種類のみ（「割引して」など）を伝えた場合	数値を自由入力
商品の指定（--products／--collections／--variants）	対象が商品である場合、またはショートカットで範囲の指定が必要な場合	ID リストを自由入力
BXGY の購入／獲得対象	範囲またはトリガー数量が指定されていない +bxgy-code の場合	ID リストと数量を自由入力

以上です。この表にない項目を質問に含めないでください。使用上限を含むその他のフラグには、CLI のデフォルト値があるか、省略すると無効になります。質問する前にユーザーのメッセージを読み直し、すでに回答が含まれている項目は尋ねないでください。

作成：最低限必要なフラグ

必須とは、指定しないと CLI がコマンドを拒否する（デフォルト値がない）フラグです。利用上限は必須ではありません。上限なしにする場合は省略してください。

ショートカット	必須フラグ
+percent-code	--target --percent（--target=product の場合はスコープフラグも必要）
+amount-code	--target --off（--target=product の場合はスコープフラグも必要）
+free-shipping-code	(なし)
+bxgy-code	購入対象のスコープ · （--buy-quantity | --buy-amount） · 特典対象のスコープ · --get-quantity · （--get-free | --get-percent | --get-off）
+flashsale	--value
+mn-discount	--tiers
+rebate	--target --tiers（--target=product の場合はスコープフラグも必要）

「スコープフラグ」とは、--products ／ --variants ／ --collections のいずれかです（相互排他）。

コンパクトなペア／リスト構文：

フラグ	形式	例
+rebate --tiers	threshold:discount,...	"200:20,500:50"（200以上で20割引、500以上で50割引）
+mn-discount --tiers	Nth-item:percent,...	"3:50,5:70"（3個購入で3個目が50%オフ、5個購入で5個目が70%オフ）
+bxgy-code の購入側	--products P1,P2 --buy-quantity 2（または --buy-amount 100）	特典を適用する条件となる、購入対象アイテム全体の数量／金額
+bxgy-code の特典側	--get-products P3 --get-quantity 1 --get-free	割引対象となる特典側アイテムの数と割引方法

時間の指定形式（すべてのショートカットで --start ／ --end に使用）：

形式	意味
now	現在時刻
+30d / +2w / +12h	現在時刻からの相対時間
2026-11-01	その日の UTC 午前0時
2026-11-01T08:00:00	UTC の日時を明示
<unix-int>	Unix 秒の値
forever / -1	有効期限なし（--end のみ）

ターゲティング／適用対象のヘルパー（いずれも任意。多くのショートカットで使用可能）：

• --exclude — スコープ ID をブロックリストにします（列挙したものを除くすべての商品に適用）。効果を有効にするにはスコープフラグが必要です。
• --customer-segments <ids> — 指定したセグメント ID の顧客に割引対象を限定します（省略すると、すべての顧客が対象になります）。

割引の併用： --combines は、この割引をほかの割引と併用できるかどうかを制御します。デフォルトは空（併用不可）です。併用を許可するには、--combines order,product,shipping のように指定します（部分指定可）。--combines とは独立した、全体的な種別横断ルールには discounts combine を使用します。

検索

list よりも +search を優先してください。 どちらも GET /discounts を呼び出しますが、+search は名前付きフラグを使用し、list は --params の JSON のみを受け取ります。

discounts +search --progress ongoing --discount-type flashsale --page-limit 250
discounts +search --query "spring" --discount-method discount_code

複数値を指定するフィルター（--progress、--discount-type、--discount-method、--discount-target）では、カンマ区切りのリストを指定します。

割引オブジェクトは .data.discount.{discount_info,discount_layer,discount_rule,entitled_product,...} にネストされています（「jq の開始位置は .data」という一般ルールは shoplazza-common に記載されています）。

discounts get-by-code --params '{"discount_code":"CODE123"}' \
  --jq '.data.discount.discount_info.id'

discount_type の列挙値

これらは API 内部で使用される名前です。--discount-type または --params 内で使用してください。ユーザー向けのラベルではありません。

flashsale                m_n_discount
rebate_cta_otr           rebate_ctq_otr           rebate_cta_otp           rebate_ctq_otp
code_percent             code_fix_price_reduction code_bxgy                code_free_shipping

ショートカットとの対応：

ショートカットが書き込む値	discount_type
+percent-code	code_percent
+amount-code	code_fix_price_reduction
+free-shipping-code	code_free_shipping
+bxgy-code	code_bxgy
+flashsale	flashsale
+mn-discount	m_n_discount
+rebate --target=order --type=amount-off	rebate_cta_otr
+rebate --target=product --type=qty-off	rebate_ctq_otr
+rebate ... --type=amount-percent / qty-percent	rebate_cta_otp / rebate_ctq_otp

--discount-type rebate で絞り込んでも結果は返りません。そのラベルは存在しないため、4種類の rebate_* 列挙値のいずれかを使用してください。

ライフサイクル — リクエスト本文の形状は非対称

単数形と複数形の違いに注意してください。これは spec-leaf で最もよくある落とし穴です。

discounts cancel        --data '{"ids":["A","B"]}'   # ARRAY (one or many)
discounts batch-delete  --data '{"ids":["A","B"]}'   # ARRAY (must be finished)
discounts restart       --data '{"id":"A"}'          # SINGULAR — one id only
discounts delete        --params '{"id":"A"}'        # path param, no body, one id

delete と batch-delete は、progress == finished の割引に対してのみ機能します。有効な割引を削除するには、先に cancel してから delete してください。

更新

+update ショートカットはありません。get の結果から更新用の本文を作成し、フィードバックしてください：

discounts get --params '{"id":"<id>"}' --jq '.data.discount' > /tmp/d.json
# edit /tmp/d.json …
discounts update-automatic --params '{"id":"<id>"}' --data @/tmp/d.json --dry-run

フラッシュセール／リベート／mn-discounts（コードなし）には update-automatic を、 コード付きの割引には update-non-automatic を使用します。本文の形式は対応する create-* エンドポイントと同じです。フィールドを確認するには schema discounts.update-automatic を実行してください。

対象範囲

割引のように見えて、実際には別の場所に属するもの：

割引のように見えるもの	実際の所属先	コマンド
礼品卡 / 储值卡 / gift card（チェックアウト時にストアクレジットとして利用できるもの）	shoplazza-products	products gift-cards
テーマカードにホームページの期間限定プロモーションを表示する／テーマカードにフラッシュセールを表示する	shoplazza-themes（フラッシュセール自体の作成はここ）	themes +edit

クーポン（バウチャー）と割引コード — どちらもこのモジュールにありますが、混同しないでください：

• 割引コード（+*-code ショートカット）：購入者がチェックアウト時に入力する公開コードです。
• クーポン（discounts coupons …）：マーケティングキャンペーンで配布する、特定の顧客に割り当てられたバウチャーです。

デフォルトでは +*-code ショートカットを使用してください。ユーザーが「クーポンキャンペーン」「バウチャー」「顧客に割り当てる」などと明示した場合に限り、coupons を使用してください。

権限 · スコープ

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

操作	必要なもの	付与方法
読み取り（get / get-by-code / list / +search）	read_price_rules	auth login --domain discounts
書き込み（create-* / +* / cancel / restart / delete / batch-delete / update-* / combine / coupons）	write_price_rules	auth login --domain discounts

discounts スコープの名前は read_price_rules / write_price_rules です。名前に 「discount」を含むスコープはありません。shoplazza auth scopes の granted_scopes でこの2つを確認してください。 --domain discounts により、この2つのスコープが展開されます。

注意点

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

症状	原因	対処方法
すべての discounts 呼び出しで、読み取りも含めて 403 PermissionDenied「check if a store is a new marketing store」が発生する	スコープの問題ではなく、ストア側のチェックです。このストアでは discounts API が有効になっていません。エンベロープの汎用的な再ログイン用 hint は該当しません	再ログインや再試行はしないでください。auth scopes → granted_scopes に read_price_rules / write_price_rules が含まれていることを確認してください（discounts のスコープです。「discount」という名前のものはありません）。含まれている場合は、このストアでは CLI を通じて discounts を管理できないことをユーザーに伝え、そこで終了してください
get / get-by-code の後に null が返る	discount オブジェクトは .data.discount の下にネストされています	jq の起点を .data.discount.discount_info.… にしてください
--discount-type rebate で何も一致しない	「rebate」は列挙値ではありません	rebate_cta_otr / rebate_ctq_otr / rebate_cta_otp / rebate_ctq_otp を使用してください
--limit-max must be > 0 (got -1)	上限は正の値のみ指定でき、-1 は拒否されます	「上限なし」にする場合は、上限の指定自体を省略してください。-1 は渡さないでください
+percent-code で unknown flag: --off が表示される	percent-code では --off ではなく --percent を使用します	--percent 15（1～99）
+flashsale で unknown flag: --discount が表示される	flashsale では --value を使用します	--value 50（および --type）
+bxgy-code --buy/--get が拒否される	これらのフラグは存在しません	購入側：スコープフラグと --buy-quantity / --buy-amount。特典側：--get-* スコープと --get-quantity、さらに --get-free / --get-percent / --get-off
restart --data '{"ids":["X"]}' が失敗する	restart の本文は単数形です	--data '{"id":"X"}'
delete が進捗メッセージとともに 4xx を返す	discount が finished ではありません	先に cancel を実行してから、delete を実行してください
--target=product が「requires one of --products/--collections/--variants」で拒否される	target=product の場合は商品スコープが必須です	スコープフラグを渡してください
応答の display_name が途中で切れているように見える	サーバーが自動的に約 20 文字に切り詰めます	重要な場合は --name を明示的に渡してください
同じ --code で discount を 2 つ作成してしまう	コードはストアごとに一意です	一意な --code を明示的に渡すか、省略して CLI-XXXXXX を自動生成させてください
ショートカットで更新しようとした	+update はありません	本文全体を指定して update-automatic / update-non-automatic を使用してください

レシピ

# 1. Spend $200 → $20 off, auto-applied, no expiry, unlimited
discounts +rebate --target order --tiers "200:20" --end forever

# 2. 15% off site-wide coupon, max 100 redemptions, 1 per shopper
discounts +percent-code --target order --percent 15 --limit-max 100 --limit-user 1 --code SPRING15

# 3. Buy 2 of P1, get 1 of P2 free, single set per order
discounts +bxgy-code --products P1 --buy-quantity 2 --get-products P2 --get-quantity 1 --get-free

# 4. Find all ongoing flash sales
discounts +search --progress ongoing --discount-type flashsale --page-limit 250 \
  --jq '.data[] | {id: .discount_info.id, name: .discount_info.discount_name}'

# 5. Cancel a code-bearing discount by its code
ID=$(discounts get-by-code --params '{"discount_code":"SPRING15"}' --jq '.data.discount.discount_info.id')
discounts cancel --data "{\"ids\":[\"$ID\"]}" --dry-run     # check first
discounts cancel --data "{\"ids\":[\"$ID\"]}"               # only after the user agrees (next turn)

# 6. Hard-delete the now-finished discount
discounts delete --params "{\"id\":\"$ID\"}"

リファレンス

• コマンドごとのフラグ：shoplazza discounts <cmd> --help
• 仕様リーフのパラメーター／本文／応答：shoplazza schema discounts.<cmd>
• 横断的な仕組み（認証／ティア／出力エンベロープ／--dry-run／--jq／安全性）：../shoplazza-common/SKILL.md
• ショートカットの信頼できる情報源：shortcuts/discounts/*.go