Skip to main content

Handling new purchases and free trials

When a customer purchases a paid plan, free trial, or the free version of your GitHub Marketplace app, you'll receive the marketplace_purchase event webhook with the purchased action, which kicks off the purchasing flow.

If you offer a GitHub 应用程序 in GitHub Marketplace, your app must identify users following the OAuth authorization flow. You don't need to set up a separate OAuth 应用程序 to support this flow. See "Identifying and authorizing users for GitHub 应用程序" for more information.

Step 1. Initial purchase and webhook event

Before a customer purchases your GitHub Marketplace app, they select a listing plan. They also choose whether to purchase the app from their personal account or an organization account.

The customer completes the purchase by clicking Complete order and begin installation.

GitHub Enterprise Cloud then sends the marketplace_purchase webhook with the purchased action to your app.

Read the effective_date and marketplace_purchase object from the marketplace_purchase webhook to determine which plan the customer purchased, when the billing cycle starts, and when the next billing cycle begins.

If your app offers a free trial, read the marketplace_purchase[on_free_trial] attribute from the webhook. If the value is true, your app will need to track the free trial start date (effective_date) and the date the free trial ends (free_trial_ends_on). Use the free_trial_ends_on date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your billing UI. To learn how to handle cancellations before a free trial ends, see "Handling plan cancellations." See "Handling plan changes" to find out how to transition a free trial to a paid plan when a free trial expires.

See "GitHub Marketplace webhook events" for an example of the marketplace_purchase event payload.

Step 2. Installation

If your app is a GitHub 应用程序, GitHub Enterprise Cloud prompts the customer to select which repositories the app can access when they purchase it. GitHub Enterprise Cloud then installs the app on the account the customer selected and grants access to the selected repositories.

At this point, if you specified a Setup URL in your GitHub 应用程序 settings, GitHub Enterprise Cloud will redirect the customer to that URL. If you do not specify a setup URL, you will not be able to handle purchases of your GitHub 应用程序.

Note: The Setup URL is described as optional in GitHub 应用程序 settings, but it is a required field if you want to offer your app in GitHub Marketplace.

If your app is an OAuth 应用程序, GitHub Enterprise Cloud does not install it anywhere. Instead, GitHub Enterprise Cloud redirects the customer to the Installation URL you specified in your GitHub Marketplace listing.

When a customer purchases an OAuth 应用程序, GitHub Enterprise Cloud redirects the customer to the URL you choose (either Setup URL or Installation URL) and the URL includes the customer's selected pricing plan as a query parameter: marketplace_listing_plan_id.

Step 3. Authorization

When a customer purchases your app, you must send the customer through the OAuth authorization flow:

For either type of app, the first step is to redirect the customer to https://github.com/login/oauth/authorize.

After the customer completes the authorization, your app receives an OAuth access token for the customer. You'll need this token for the next step.

Note: When authorizing a customer on a free trial, grant them the same access they would have on the paid plan. You'll move them to the paid plan after the trial period ends.

Step 4. Provisioning customer accounts

Your app must provision a customer account for all new purchases. Using the access token you received for the customer in Step 3. Authorization, call the "List subscriptions for the authenticated user" endpoint. The response will include the customer's account information and show whether they are on a free trial (on_free_trial). Use this information to complete setup and provisioning.

注:在当前版本的 GitHub Marketplace 中,如果客户已有一个从您的应用程序网站购买的现有帐户,他们可能还会通过 GitHub Marketplace 购买您的应用程序。 如果您发现已经为购买您的应用程序的客户设置了帐户,请向 GitHub 支持部门报告这种“双重”购买的情况。

If the purchase is for an organization and per-user, you can prompt the customer to choose which organization members will have access to the purchased app.

You can customize the way that organization members receive access to your app. Here are a few suggestions:

Flat-rate pricing: If the purchase is made for an organization using flat-rate pricing, your app can get all the organization’s members via the API and prompt the organization admin to choose which members will have paid users on the integrator side.

Per-unit pricing: One method of provisioning per-unit seats is to allow users to occupy a seat as they log in to the app. Once the customer hits the seat count threshold, your app can alert the user that they need to upgrade through GitHub Marketplace.