プラン変更の処理

課金に関連するアップグレードとダウングレードの詳細については、「アプリケーション内でのGitHub marketplace APIの使用」を参照してください。

手順 1. 料金プランの変更イベント

顧客が GitHub Marketplace の注文に対して次のいずれかの変更を行うと、GitHub は changed アクションを含む marketplace_purchase Webhook をお客様のアプリに送信します。

• より高価な価格プランへのアップグレードあるいは低価格なプランへのダウングレード
• 既存のプランへのシートの追加あるいはシートの削除
• 支払いサイクルの変更

GitHubは、変更が有効になるとwebhookを送信します。 たとえば、顧客がプランをダウングレードすると、その顧客の支払いサイクルの終了時点でwebhookを送信します。 顧客がプランをアップグレードした場合には、新しいサービスをすぐに利用できるようにするため、GitHubは即座にアプリケーションにwebhookを送信します。 顧客が支払いサイクルを月次から年次に切り替えた場合は、アップグレードと見なされます。 アップグレードまたはダウングレードと見なされるアクションの詳細については、「顧客への課金」を参照してください。

marketplace_purchase Webhook から effective_date、marketplace_purchase、previous_marketplace_purchase を読み取り、プランの開始日を更新して、顧客の請求サイクルと価格プランを変更します。 marketplace_purchase イベント ペイロードの例については、「GitHub Marketplace APIのためのwebhookイベント」を参照してください。

アプリで無料試用版が提供されている場合は、無料試用の期限が切れると、changed アクションを含む marketplace_purchase Webhook を受け取ります。 顧客の無料トライアル期間が終了したら、その顧客を無料トライアルプランの有料バージョンにアップグレードしてください。

手順 2. 顧客アカウントの更新

顧客がGitHub Marketplaceの注文に対して行った支払いサイクルや価格プランの変更を反映させるために、顧客のアカウント情報を更新しなければなりません。 changed アクションの Webhook を受け取ったら、Marketplace アプリの Web サイトまたはアプリの UI で、価格プラン、seat_count (ユニットごとの価格プランの場合)、請求サイクルに対するアップグレードを表示します。

顧客がプランをダウングレードした場合には、顧客がプランの制限を超えているかをレビューし、UIで直接関わるか、電話やメールで連絡することをおすすめします。

アップグレードを促すために、アップグレードのURLをアプリケーションのUIに表示できます。 詳細については、「アップグレード URL について」を参照してください。

アップグレードの支払いの失敗

顧客がプランをアップグレードし、支払いに失敗した場合、GitHub はその顧客の GitHub Marketplace サブスクリプションを以前の状態に戻します。 また、GitHub はその顧客に対して失敗を知らせ、購入をもう一度試みることができるよう、メールを送ります。 以前のプランに戻すように要求する changed アクションを含む Webhook を受け取ります。

アップグレードURLについて

アップグレードURLを使い、ユーザをアプリケーションのUIからGitHub上でのアップグレードへリダイレクトできます。

https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/<CUSTOMER_ACCOUNT_ID>

たとえば、顧客が5人のプランを使っていて、10人のプランに移行する必要があることに気づいた場合、アプリケーションのUIに「アップグレードの方法はこちら」というボタンを表示したり、アップグレードURLへのリンクを持つバナーを表示したりできます。 アップグレードURLは顧客をリストされたプランのアップグレードの確認ページへ移動させます。

顧客が購入を望むプランの LISTING_PLAN_NUMBER を使用します。 新しい価格プランを作成すると、リスト全体でプランごとに固有の LISTING_PLAN_NUMBER と、GitHub Marketplace においてプランごとに固有の LISTING_PLAN_ID を受け取ります。 プランを一覧表示するとこれらの値を確認でき、それはリストの価格プランを示します。 LISTING_PLAN_ID と GET /marketplace_listing/plans/{plan_id}/accounts エンドポイントを使って CUSTOMER_ACCOUNT_ID を取得します。