Supporting purchase plans for GitHub Apps
Purchasing a GitHub Marketplace app triggers the
marketplace_purchase event webhook with the
purchased action. This flow explains the actions that you should take when this event occurs.
- The customer selects a listing plan and, if applicable, designates the number of units to purchase. The
marketplace_purchasewebhook provides information for customers who are
on_free_trial: the date the free trial starts (
effective_date), and the date the free trial ends (
free_trial_ends_on). The number of days left in the free trial should be displayed on your Marketplace app's website.
- The customer chooses to purchase a plan using a payment method from their personal account or an organization that they administer.
The customer clicks Complete purchase and begin installation. GitHub will trigger the
marketplace_purchaseevent changed action if the customer cancels the plan before the trial period ends or at the end of their 14-day free trial. For more information on how to handle a cancellation during a free trial, see "Cancelling plans."
Once a free trial expires, you need to upgrade the customer to the paid version of the free-trial plan. For information on how to handle an upgrade at the end of a free trial, see "Upgrading and downgrading plans."
marketplace_purchasewebhook with the action
Note: Use this webhook for notification and tracking only, but not for provisioning.
- GitHub prompts the customer to select which repositories they want to grant access to.
- GitHub redirects the customer to the GitHub App Setup URL. The
setup_urlis an optional field that you can define when creating a GitHub App to allow this flow to work.
- You redirect the customer to https://github.com/login/oauth/authorize to begin OAuth authorization flow with appropriate permissions for the GitHub App.
- You receive an OAuth token for the customer.
Mapping customer to purchase
- You call Get a user's Marketplace purchases using the token from Authorizing.
- You can complete setup and provisioning. For example, if the purchase is for an Organization and per user, you prompt the customer to choose which organization members will have access to the GitHub Marketplace App.
Supporting free trials
To support the free trials flow:
Use the Marketplace API
has_free_trialkey to know which customers purchased a free trial. The Marketplace purchase webhook provides information for customers who are
on_free_trialthe date the
Note: For authorization, you can give customers the same access as they would have on that paid plan because they will move to the paid plan after the trail period.
free_trial_endsdate to let the user know how many days they have left on their free trial in your app UI. You can do this in either a banner or in your billing UI.
- GitHub will trigger the
changedaction if the customer cancels the plan before the trial period ends or at the end of their 14-day free trial. Once a free trail expires, the customer is upgraded to the paid version of the free-trial plan.