处理计划更改

有关与计费相关的升级和降级的更多信息，请参阅“在应用程序中使用 GitHub Marketplace API”。

步骤 1。 定价计划更改事件

当客户对其 GitHub Marketplace 订单进行以下任何更改时，GitHub 会将带有 changed 操作的 marketplace_purchase Webhook 发送到你的应用：

• 升级到更昂贵的定价计划或降级到价格较低的计划。
• 在其现有计划中增加或删除席位。
• 更改结算周期。

更改生效时，GitHub 将发送 web 挂钩。 例如，当客户降级计划时，GitHub 会在客户的结算周期结束时发送 web 挂钩。 当客户升级其计划以便立即访问新服务时，GitHub 会立即向您的应用程序发送 web 挂钩。 如果客户从月度结算周期切换到年度结算周期，则视为升级。 请参阅“向客户计费”以详细了解哪些操作被视为升级或降级。

读取 marketplace_purchase Webhook 中的 effective_date、marketplace_purchase 和 previous_marketplace_purchase 以更新计划的开始日期并更改客户的计费周期和定价计划。 有关 marketplace_purchase 事件有效负载的示例，请参阅“GitHub Marketplace API 的 web 挂钩事件”。

如果应用提供免费试用版，则你将在免费试用版到期时收到带有 changed 操作的 marketplace_purchase Webhook。 如果客户的免费试用到期，则将客户升级到免费试用计划的付费版本。

步骤 2. 更新客户账户

您需要更新客户的帐户信息，以反映客户对其 GitHub Marketplace 订单所做的结算周期和定价计划更改。 收到 changed 操作 Webhook 时，Marketplace 应用的网站或应用的 UI 上会显示定价计划、seat_count（对于每单位定价计划）和计费周期的升级。

当客户降级计划时，建议查看客户是否超出了计划限制，然后直接在您的 UI 中与他们互动，或者通过电话或电子邮件与他们联系。

要鼓励用户升级，您可以在应用程序的 UI 中显示升级 URL。 有关更多详细信息，请参阅“关于升级 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（对于上架产品中每个计划而言是唯一的）和 LISTING_PLAN_ID（对于 GitHub Marketplace 中每个计划而言是唯一的）。 在列出计划（用于标识上架产品的定价计划）时，可以找到这些数字。 使用 LISTING_PLAN_ID 和“GET /marketplace_listing/plans/{plan_id}/accounts”终结点获取 CUSTOMER_ACCOUNT_ID。