Billing customers in GitHub Marketplace

Apps on GitHub Marketplace should adhere to the basic billing guidelines and support recommended services. Following these guidelines helps customers navigate the billing process without any surprises.

Understanding the billing cycle

The billing cycle can be monthly or yearly. All changes to the billing cycle and plan selection will trigger a marketplace_purchase event. You can refer to the marketplace_purchase webhook payload to see which billing cycle a customer selects, and when the next billing date begins. For more information, see "About webhook payloads for a GitHub Marketplace listing."

Providing billing services in your Marketplace app

Customers must be able to perform the following actions from your Marketplace app's website:

  • Find the plan and price in the billing overview in their account on your Marketplace app's website. This billing overview must reflect any changes to their plan after a marketplace_purchase event has been triggered.

    For example, if a customer changes from a monthly to a yearly plan, they need to see this change both on GitHub and on your Marketplace app's website. If the pricing plan is per-unit, your Marketplace app's site should show units used and units available.

  • Modify or cancel their Marketplace plans for personal and organizational accounts separately.
  • Assign collaborators and per_unit seats to other users directly from your Marketplace app's website.

Billing services for upgrades, downgrades, and cancellations

To accommodate customers changing their plans, adhere to the billing process guidelines below. You can use the marketplace_purchase webhook's effective_date key to determine when a plan change will occur and periodically synchronize the list of GitHub accounts on a specific plan. For more information on webhooks, see "About webhooks payloads for a GitHub Marketplace listing."

Use the following guidelines to maintain a clear and consistent billing process.

When a customer upgrades their plan:

  • Provide the feature to them immediately. You need to apply a pro-rated discount to the new plan and change the billing cycle.

When a customer cancels their plan:

  • Automatically downgrade them to the free plan, if it exists.
  • Enable them to upgrade the plan through GitHub if they would like to continue the plan at a later time.

When a customer downgrades or cancels their plan in the middle of a billing cycle:

  • Keep them on the original plan and apply changes to their next billing date. GitHub will trigger a marketplace purchase webhook when the cancellation or downgrade takes place at the beginning of their next billing cycle.