メモ
この記事は、GitHub Marketplace でのアプリの公開にのみ適用されます。 GitHub Marketplace での GitHub Actions の公開について詳しくは、「GitHub Marketplaceでのアクションの公開」をご覧ください。
課金に関連するアップグレードとダウングレードの詳細については、「アプリで GitHub Marketplace API を使用する」を参照してください。
手順 1. 料金プランの変更イベント
顧客が GitHub Marketplace の注文に対して次のいずれかの変更を行うと、GitHub は changed アクションを含む marketplace_purchase Webhook をお客様のアプリに送信します。
- より高価な価格プランへのアップグレードあるいは低価格なプランへのダウングレード
- 既存のプランへのシートの追加あるいはシートの削除
- 支払いサイクルの変更
変更が有効になると、GitHubは webhook を送信します。 たとえば、顧客がプランをダウングレードすると、GitHubは顧客の請求サイクルの最後に Webhook を送信します。 GitHub、顧客が新しいサービスにすぐにアクセスできるようにプランをアップグレードすると、すぐに Webhook がアプリに送信されます。 顧客が支払いサイクルを月次から年次に切り替えた場合は、アップグレードと見なされます。 アップグレードまたはダウングレードと見なされるアクションの詳細については、「顧客への課金」を参照してください。
`effective_date` Webhook から `marketplace_purchase`、`previous_marketplace_purchase`、`marketplace_purchase` を読み取り、プランの開始日を更新して、顧客の請求サイクルと価格プランを変更します。 `marketplace_purchase` イベント ペイロードの例については、「[AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api)」を参照してください。
アプリで無料試用版が提供されている場合は、無料試用の期限が切れると、marketplace_purchase アクションを含む changed Webhook を受け取ります。 顧客の無料トライアル期間が終了したら、その顧客を無料トライアルプランの有料バージョンにアップグレードしてください。
手順 2. 顧客アカウントの更新
顧客がGitHub Marketplaceの注文に対して行った支払いサイクルや価格プランの変更を反映させるために、顧客のアカウント情報を更新しなければなりません。
seat_count アクションの Webhook を受け取ったら、Marketplace アプリの Web サイトまたはアプリの UI で、価格プラン、changed (ユニットごとの価格プランの場合)、請求サイクルに対するアップグレードを表示します。
顧客がプランをダウングレードした場合には、顧客がプランの制限を超えているかをレビューし、UIで直接関わるか、電話やメールで連絡することをおすすめします。
アップグレードを促すために、アップグレードのURLをアプリケーションのUIに表示できます。 詳細については、「アップグレード URL について」を参照してください。
メモ
`GET /marketplace_listing/plans/:id/accounts` を使って定期的に同期を行い、各アカウントについてアプリのプラン、支払いサイクル情報、ユニット数 (ユニット単位の料金の場合) が正しくなるようにすることをお勧めします。
アップグレードの支払いの失敗
顧客がプランをアップグレードし、支払いに失敗した場合、GitHub はその顧客の GitHub Marketplace サブスクリプションを以前の状態に戻します。 また、GitHub はその顧客に対して失敗を知らせ、購入をもう一度試みることができるよう、メールを送ります。 以前のプランに戻すように要求する changed アクションを含む Webhook を受け取ります。
アップグレードURLについて
アプリの UI からユーザーをリダイレクトし、アップグレード URL を使用して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 を取得します。
メモ
顧客がアップグレードしてユニット（座席など）を追加した場合、それを引き続き購入に対して適切なプランに送ることができますが、現時点では unit_count パラメーターをサポートできません。