Supporting purchased plans for OAuth 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.


  1. The customer selects 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.


  1. GitHub redirects the customer to the specified Installation URL for the listing. GitHub passes the selected plan as a the URL query parameter marketplace_listing_plan_id.
  2. You redirect the customer to to begin OAuth authorization flow with appropriate parameters for the OAuth App.
  3. You receive an OAuth token for the customer.

Mapping customer to purchase

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