プラン排他グループ機能（プラン切替）¶

同じ「排他グループキー」を設定した商品同士を排他プランとして扱い、利用者が新たに購入した時点で既存の同グループ契約を自動的に解約する機能です。EC/会員制サービスでの有料プランのアップグレード・ダウングレード運用を、管理者の手動操作なしに実現できます。

想定ユースケース¶

1. 階層プランのアップグレード／ダウングレード¶

「Plusプラン（月額500円）」と「Proプラン（月額1,500円）」のように、同時に複数契約させたくない階層プランを運用するケースです。

利用者が Plus を契約中 → 利用者が Pro を購入 → Plus が自動解約され、Pro のみ有効に
利用者が Pro を契約中  → 利用者が Plus を購入 → Pro が自動解約され、Plus のみ有効に

2. 月額／年額の切替¶

「月額1,500円プラン」と「年額15,000円プラン」に同じ排他グループキーを設定することで、支払い周期の変更時に旧プランを自動解約できます。

3. ビジネスサイズ別プラン¶

「Smallプラン」「Mediumプラン」「Largeプラン」のような規模別プランに同じキーを設定し、利用者が企業規模の変更に合わせてプランを変更する際の切替作業を自動化します。

設定方法¶

1. 商品設定画面で「排他グループキー」を入力¶

サイドバー「商品設定」→「商品設定を追加」または既存商品の「設定変更」を開き、「排他グループキー」欄に任意のキー（例: paid_main）を入力します。

項目	説明
排他グループキー	同じキーを持つ商品同士が排他関係になります。英数字・ハイフン・アンダースコアのみ、64文字まで。
排他自動解約時は解約費を免除する	チェックを入れると、プラン切替による自動解約では解約費を請求しません。通常の解約画面からの操作には影響しません。

キー名の命名例

paid_main — 有料メインプラン
billing_cycle — 月額/年額切替用
business_tier — ビジネス規模別

キー名はテナント内で意味のある命名を付けてください。異なるテナント間でキー名が重複しても問題ありません（テナント境界内で独立に判定されます）。

2. 排他関係にしたい商品すべてに同じキーを設定¶

上記の手順を、排他関係にしたい2つ以上の商品設定で繰り返します。同じキーを持つすべての商品が排他グループとして連動します。

3. 動作確認¶

テストユーザーでの購入→別プラン購入→旧プランが解約済みになることを確認してください。Webhook通知を購読している場合は、subscription.cancelled（source=exclusive_group_auto_cancel）と subscription.created の両方が発火することも合わせて確認します。

動作の詳細¶

自動解約の対象となる契約¶

利用者が同じ排他グループ内で保有する契約のうち、以下の contract_status に該当するものすべてが解約対象となります：

`contract_status`	状態	解約対象
1	試用期間中	✅ 対象
2	定額使用中	✅ 対象
3	休止中	✅ 対象
4	解約予定	✅ 対象
5	解約済み	❌ 対象外（既に解約済み）
6	未契約	❌ 対象外
7	支払い済み（単発）	❌ 対象外
8	支払い免除	❌ 対象外

解約のタイミング¶

PaymentLink での購入完了（Stripe checkout.session.completed webhook 受信）時点で、即時に実行されます。試用期間や最低契約期間の残存期間があっても待ちません。

解約費用の扱い¶

商品設定	挙動
解約費免除チェックなし（デフォルト）	通常の解約ロジックに従い、最低契約期間内なら解約費を請求（試用期間中・支払い免除中を除く）
解約費免除チェックあり	排他自動解約時のみ解約費を請求しない。通常の解約画面（ユーザー操作）からの解約には影響しない

解約費を免除したい場合は両方の商品に設定してください

「Plusを解約してProへ移行するとき」「Proを解約してPlusへ移行するとき」の両方向で免除を有効にするには、PlusとProの両方の商品設定で「解約費免除」にチェックを入れる必要があります。どちらか片方でもチェックが入っていれば免除されます。

PaymentLink購入前画面での予告表示¶

利用者が排他グループに属する商品のPaymentLinkにアクセスし、かつメールアドレスで既存契約が特定できる場合、購入前の中間ページに自動解約予告と同意チェックが表示されます。

表示内容: - 自動解約される既存プラン名と契約番号 - 解約タイミング（「ご購入完了後すぐ」） - 解約費用の有無と金額

利用者は「プラン切替に同意します」のチェックと「利用規約に同意します」のチェックの両方を入れないと、PaymentLink決済ページへ進むことができません。

メールアドレスが特定できない場合

ログイン状態ではなく、かつURLに email パラメータも付与されていないアクセスの場合、購入前の予告表示はスキップされます。ただし購入完了時点で既存契約は同じように自動解約されるため、機能としては動作します。

既存機能との関係¶

「複数契約OK」の商品（排他グループキーなし）は従来通り¶

サブスクライトは原則として同一利用者が複数契約を保有できる設計です（オプション商品の複数購入、在庫割り当て商品などで活用されています）。排他グループは明示的にキーを設定した商品のみに適用される追加機能で、キー未設定の商品は従来通り並行契約が可能です。

オプション商品との組み合わせ¶

オプション商品（is_option=1）にも排他グループキーを設定できますが、通常商品での利用を推奨します。オプション商品は「特定商品の補助的機能」という位置付けで、排他関係の運用とは相性が合わないことが多いためです。

サブスクライト標準パッケージ¶

メイン管理者向けの「サブスクライト標準パッケージ」には、排他グループキーを設定しないでください。特権管理用の設定のため、排他運用の対象外です。

よくある質問¶

Q. 解約されたプランの `contract_unique_id` はどうなりますか？¶

A. 解約費が発生した場合は contract_unique_id を保持します（解約費請求の照合に必要）。解約費が発生しない場合は null に設定されます。いずれの場合も cancel_reason カラムに exclusive_group_auto_cancel が記録されるため、履歴追跡は可能です。

Q. 同じ排他グループ内で3つ以上の商品を扱えますか？¶

A. はい。同じキーを3つ以上の商品に設定できます。例えば「Free / Plus / Pro」の3階層でも、利用者が新たなプランを購入すると、同グループ内の他のすべてのアクティブ契約が自動解約されます。

Q. 年間契約を途中でキャンセルしたくない場合の運用は？¶

A. 最低契約期間と解約費を設定し、「解約費免除」のチェックを外してください。利用者が排他グループ内の別プランを購入しても、最低契約期間内であれば解約費が請求されます。利用者は課金を避けるために、最低契約期間の経過を待ってから別プランに切り替えることになります。

Q. 排他グループキーを途中で変更・削除するとどうなりますか？¶

A. 既に作成されている契約には影響しません。設定変更後に新たに購入された契約から新しい排他ルールが適用されます。例えばグループから商品を外す（キーを空にする）と、その商品の将来の購入は他プランを自動解約しなくなります。

Q. 管理画面から手動でプラン切替を行った場合も自動解約されますか？¶

A. 現バージョン（Phase 1）では、PaymentLink経由の購入完了時のみ自動解約が動作します。管理画面からの「利用者に契約商品を追加」等の操作では自動解約は発火しません。管理者操作でのプラン切替は、別途手動で旧プランを解約する運用としてください（将来バージョンで対応予定）。

Q. 排他グループ自動解約は取り消しできますか？¶

A. Stripe Subscription のキャンセルは不可逆です。誤って排他グループに設定してしまった場合は、以下の対応が必要になります：

商品設定から排他グループキーを除去または変更
既に自動解約された契約については、利用者に再購入を依頼するか、管理画面から手動で契約を復元

テスト環境で十分に挙動を確認してから本番適用することを強く推奨します。

外部システム連携との連動¶

排他グループ自動解約が発生すると、以下の2つのWebhook通知が連動して発火します（Webhook エンドポイントを登録している場合）。

イベント種別	内容
`subscription.cancelled`	旧プランの解約通知。`source=exclusive_group_auto_cancel`、`replaced_by_contract_id` / `replaced_by_product_setting_id` に新プランの情報を含む
`subscription.created`	新プランの作成通知。`auto_cancelled_contracts` フィールドに自動解約された旧契約の一覧を含む

外部アプリ側でこれらを相関させることで、自社システム上のユーザープランを一括更新できます。詳細なpayload仕様とサンプルコードは外部システム連携ガイドをご参照ください。