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.

Purchasing

  1. The customer chooses a listing plan and, if applicable, designates the number of units to purchase.
  2. The customer chooses to purchase a plan using a payment method from their personal account or an organization that they administer.
  3. The customer clicks Complete purchase and begin installation.
  4. GitHub triggers marketplace_purchase webhook with the action purchased.

    Note: Use this webhook for notification and tracking only, but not for provisioning.

Installing

  1. GitHub prompts the customer to select which repositories they want to grant access to.
  2. GitHub redirects the customer to the GitHub App Setup URL. The setup_url is an optional field that you can define when creating a GitHub App to allow this flow to work.

Authorizing

  1. You redirect the customer to https://github.com/login/oauth/authorize to begin OAuth authorization flow with appropriate permissions for the GitHub App.
  2. You receive an OAuth token for the customer.

Mapping customer to purchase

  1. You call Get a user's Marketplace purchases using the token from Authorizing.
  2. 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:

  1. Use the Marketplace API has_free_trial key to know which customers purchased a free trial. The Marketplace purchase webhook provides information for customers who are on_free_trial the date the free_trial_ends_on.

    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.

  2. Track the free_trial_ends date 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.

  3. GitHub will trigger the marketplace_purchase event changed action 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.