shoplazza-billing

shoplazza CLI — 請求モジュール

重要 — 何よりも先に、../shoplazza-common/SKILL.md を Read で参照してください。 ここでは、アクセス階層、出力エンベロープ（.data）、--dry-run、 --jq、schema、api rest、認証／プロファイル、安全プロトコルなど、すべての共通機能を扱います。このファイルでは請求ドメインのみを扱い、それらを繰り返しません。

概要

請求モジュールを使うと、アプリ開発者はアプリの利用に対して加盟店に請求できます。対象は、一回限りの料金、 定期サブスクリプション、従量制の利用量料金（および取引記録）です。これは 仕様のリーフのみで、+shortcuts はありません。すべての請求で実際のお金が動くため、まず --dry-run を実行し、実行前に請求内容をユーザーに再確認してください（shoplazza-common → Safety）。

請求は2 段階で処理されます。create だけではお金は動かず、レスポンスで返される承認 URL（1 回限りの請求では confirm_url、 定期請求では confirmation_url）を加盟店が開き、Shoplazza 管理画面で承認するまで、請求は保留状態になります。承認後、加盟店はお客様の return_url に移動します。 利用量の請求では承認は不要です。すでに承認済みの定期請求に対して課金されます。

コマンド一覧

意図 → コマンド。正規のパラメーター／本文は shoplazza schema billing.<group>.<cmd> を参照してください。

ユーザーの意図	コマンド
1 回限りの請求を作成する（金銭が動くため、まず --dry-run を実行）	billing one-time create --data '{"application_charge":{"name":"…","price":"<amt>","return_url":"…"}}' --dry-run
1 回限りの請求を取得／一覧表示する	billing one-time get --params '{"charge_id":"<id>"}' · billing one-time list
1 回限りの請求の取引を取得する	billing one-time transactions --params '{"charge_id":"<id>"}'
定期（サブスクリプション）請求を作成する（金銭が動くため、まず --dry-run を実行）	billing recurring create --data '{"recurring_application_charge":{"name":"…","price":<amt>,"return_url":"…"}}' --dry-run（trial_days、capped_amount、terms は任意）
定期請求を取得／一覧表示する	billing recurring get --params '{"charge_id":"<id>"}' · billing recurring list
定期請求を更新する	billing recurring update --params '{"charge_id":"<id>"}' --data '{"recurring_application_charge":{…}}'
定期請求をキャンセルする（まず --dry-run を実行）	billing recurring cancel --params '{"charge_id":"<id>"}' --dry-run
定期請求の取引を取得する	billing recurring transactions --params '{"charge_id":"<id>"}'
定期請求に利用量の請求を記録する（金銭が動くため、まず --dry-run を実行）	billing usage create --params '{"charge_id":"<id>"}' --data '{"usage_charge":{"description":"…","price":<amt>}}' --dry-run
利用量の請求を取得／一覧表示する	billing usage get --params '{…}' · billing usage list --params '{"charge_id":"<id>"}'
アプリ請求の取引を 1 件取得する	billing transactions get --params '{"transaction_id":"<id>"}'

リクエストへの対応

請求の書き込みでは実際のお金が動きます。作成／キャンセルの前に、必ず次の手順を行ってください。

1. 意図を末端の項目に照らし合わせます（ここでは近道をしないでください）。
2. 必須フィールドを確認します。不足している場合は、金額を決して捏造せず、AskUserQuestion で質問してください：
   • 1 回限りの create：name、price、return_url
   • 継続課金の create：name、price、return_url
   • 使用量課金の create：charge_id（親となる継続課金）、description、price
   • 継続課金の cancel：charge_id
3. まず --dry-run を実行し、内容を言い直して確認します（「加盟店に $X を請求します — 1 回限り／月額 $X のサブスクリプション／CHG…に紐づく $X の使用量課金。戻り先は です。加盟店が返された確認リンクから承認するまで保留になります」）。ユーザーの承認を待ってから実行してください。 cancel の場合は、ID だけをそのまま繰り返すのではなく、キャンセルする対象を言い直してください。同じ返信内で、cancel --dry-run のプレビューとともに、まず recurring get を実行します （名前／価格／ステータスを確認し、すでにキャンセル済みの場合も検知できます）。
4. 1 回限りまたは継続課金の create が成功したら、承認 URL をユーザーに渡してください — --jq '.data.application_charge | {id, status, confirm_url}'（1 回限り）／ --jq '.data.recurring_application_charge | {id, status, confirmation_url}'（継続課金） — そして、加盟店がリンクを開いて承認するまで料金は請求されませんとはっきり伝えてください。
5. プラットフォームが課金を拒否した場合、金額を変えて再試行してはいけません。 価格が拒否される原因はほとんどの場合、値を探るべきではない商品リスト設定の問題です（「注意点」を参照）。金額を試すと、ユーザーが承認していない課金が作成されるおそれがあります。拒否されたことと必要な partner-backend 設定を伝え、そこで止めてください。

適用範囲

請求のように見えて、実際には別の機能に属するもの：

請求のように見えるもの	実際の所属先	コマンド
取引記録 = 購入者が店舗に支払ったお金／注文の支払い取引	shoplazza-orders	orders transactions
注文の返金／購入者への返金	shoplazza-orders	orders +refund

billing transactions = アプリが加盟店に請求する料金です。注文に対する購入者の支払いは orders transactions です。（app-charge-transactions／order-payment-transactions のルーティングの競合に対応します。）

権限 · スコープ

Billing にストアスコープは不要です。 auth login --domain billing はスコープを 0 個に展開されます。 これは正しい動作であり、バグではありません。アプリ課金エンドポイントはストア OAuth の許可ではなく、アプリのインストール自体によって認可されます。実環境で確認済みです。read_finance も write_finance も持たないプロファイルで recurring list は ok:true を返し、recurring create は業務バリデーション（400／422）まで進み、401／403 にはなりませんでした。

したがって、auth login --domain billing は実行しないでください。 認可ではサーバー側の許可が置き換えられるため、スコープ 0 個でのログインにより、他のドメインが依存するスコープが取り消される可能性があります。ここでの 401／403 は、アカウントのログインが不足しているか期限切れであることを意味します。スコープを追いかけず、auth status を確認してください。

注意点

このモジュール固有の内容のみです（一般的な .data／--dry-run／--jq のルールは shoplazza-common に記載されています）。

症状	原因	対処方法
price の型が原因で請求が拒否される	price の型は請求の種類によって異なります：一回限り＝文字列（"99.99"）、定期および従量課金＝数値（29、0.05）	型を合わせます。一回限りの場合は引用符で囲み、定期／従量課金の場合は数値をそのまま指定します
create は成功したが、加盟店に請求されない	請求は二段階です。create は保留中の請求を返し、加盟店が返された承認 URL から承認するまで有効になりません	URL をユーザーに渡し、加盟店が承認するまで課金されないことを伝えます。create の ok:true は「請求済み」を意味しません
承認 URL を取得する jq の結果が null になる	フィールド名は請求の種類によって異なります：一回限り＝confirm_url、定期＝confirmation_url（従量課金にはどちらもありません。承認手順がないためです）	請求の種類に合ったフィールドを指定します
usage create が請求なしで失敗する	charge_id（親となる定期請求）は必須のパスパラメーターです	--params '{"charge_id":"<recurring charge id>"}'
プレビューせずに実際の請求を作成した	請求には実際に金銭が発生します	まず --dry-run を実行し、ユーザーに内容を改めて伝えて、承認を待ってから実行します
recurring create → 422 The price configuration in the plan does not match with the listing, please check	プラットフォームが受け付けるのは、アプリの掲載情報（パートナーバックエンド）で設定された料金プランに一致する価格のみです。任意の金額は拒否されます。CLI では修正できません — このモジュールには掲載情報／プランのエンドポイントがありません（schema billing で確認できます）	アプリの掲載情報でそのプランを追加／調整するようユーザーに伝え、その後、同じコマンドを変更せずに再実行します。他の価格を試してはいけません
recurring create → フィールド情報のない単純な 400 Bad Request が返り、本文は schema と一致する	capped_amount を追加すると、バックエンドは代わりに具体的な 422 を返します（実環境で確認済み：同一の本文に capped_amount を加えると、上記の掲載情報に関する 422 が返ります）。400 が同じ根本原因によるものか、独自の capped_amount チェックによるものかは未確認です。schema ではこのフィールドは任意とされています	不正なフィールドを探し回らず、実際のメッセージを表示するために capped_amount を付けて一度だけ再送し、その内容に応じて対処します。これは診断であり、修正ではありません。他の価格で再試行してはいけません。また、設定すれば請求が通ると決めつけてはいけません

レシピ

# 1. One-time $99.99 setup fee (price is a STRING)
billing one-time create --data '{"application_charge":{"name":"Setup Fee","price":"99.99","return_url":"https://app.example.com/billing/done"}}' --dry-run
# real run: add --jq '.data.application_charge | {id, status, confirm_url}' and hand the URL over

# 2. Recurring $29/mo subscription, 7-day free trial (price is a NUMBER)
billing recurring create --data '{"recurring_application_charge":{"name":"Pro Plan","price":29,"return_url":"https://app.example.com/billing/ok","trial_days":7}}' --dry-run
# real run: add --jq '.data.recurring_application_charge | {id, status, confirmation_url}'

# 3. Usage charge $0.05 under recurring charge CHG7788 (price NUMBER)
billing usage create --params '{"charge_id":"CHG7788"}' --data '{"usage_charge":{"description":"API calls overage","price":0.05}}' --dry-run

# 4. Cancel a recurring charge: look up what it is, preview, then STOP for the user's go-ahead
billing recurring get --params '{"charge_id":"CHG5566"}' --jq '.data.recurring_application_charge | {name, price, status}'
billing recurring cancel --params '{"charge_id":"CHG5566"}' --dry-run

参考資料

• コマンドごとのフラグ：shoplazza billing <group> <cmd> --help
• パラメーター／本文／レスポンス：shoplazza schema billing.<group>.<cmd>
• 共通の仕組み（認証／ティア／出力エンベロープ／--dry-run／安全性）：../shoplazza-common/SKILL.md