Upgrading or downgrading plans

Upgrading or downgrading a GitHub Marketplace app triggers the marketplace_purchase event webhook with the changed action. This flow explains the actions that you should take when this event occurs.

For more information about upgrading and downgrading as it relates to billing, see "Billing customers in GitHub Marketplace."

Customer changes their plan

  1. The customer returns to the Marketplace listing they want to modify.
  2. The customer changes their plan in one or both of the following ways:
    • Upgrades or downgrades their plan.
    • Adds or removes seats to their existing plan.
  3. GitHub triggers marketplace_purchase webhook with the action changed when the change takes effect. Downgrades will occur at the end of the customer's billing cycle. Upgrades will occur immediately.

Changing account status

  1. You need to change the plan and seat count based on results from a customer changing their plan. Upgrades to plan information and seat_count changes should be displayed on your Marketplace app's website immediately. When a plan is downgraded, you must display the new plan and its effective date. This information is available in the marketplace_purchase webhook payload.
  2. Redirect the customer to your upgrade URL page. For more details see About upgrade URLs.

Note: We recommend performing a periodic synchronization using GET /marketplace_listing/plans/:id/accounts.

About upgrade URLs

When a customer wants to upgrade, you can send them to an upgrade URL where you specify the LISTING_PLAN_ID and CUSTOMER_ACCOUNT_ID:

https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_ID>/<CUSTOMER_ACCOUNT_ID>.

This URL takes the customer to your listing's plan change confirmation page. The LISTING_PLAN_ID is a unique number for each Marketplace listing plan, relative to your GitHub Marketplace listing. You can find this number when you list all plans for your Marketplace listing. You can find the CUSTOMER_ACCOUNT_ID when you list all GitHub user accounts on a specific plan.

Note: If your customer upgrades to extra units (such as seats), you can still send them to the appropriate plan for their purchase but we are unable to support unit_count parameters at this time.