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.

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 change the plan and seat count based on results of previous step.
  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.