プラン変更の処理

GitHub Marketplace アプリをアップグレードまたはダウングレードすると、changed アクションで marketplace_purchase イベント Webhook がトリガーされて、アップグレード フローまたはダウングレード フローが始まります。

この記事の内容

注: この記事は、GitHub Marketplace でのアプリの公開にのみ適用されます。 GitHub Marketplace での GitHub Actions の公開について詳しくは、「GitHub Marketplaceでのアクションの公開」をご覧ください。

課金に関連するアップグレードおよびダウングレードの詳細については、「アプリケーション内での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 について」を参照してください。

Note

GET /marketplace_listing/plans/:id/accounts を使って定期的に同期を行い、各アカウントについてアプリのプラン、支払いサイクル情報、ユニット数 (ユニット単位の料金の場合) が正しくなるようにすることをお勧めします。

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

顧客がプランをアップグレードし、支払いに失敗した場合、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」を取得します。

Note

顧客がアップグレードしてユニット (シートなど) を追加した場合、引き続きそれを購入に対して適切なプランに送信できますが、現時点では GitHub は unit_count パラメーターをサポートできません。