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_purchaseevent 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_unitseats 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
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 purchasewebhook when the cancellation or downgrade takes place at the beginning of their next billing cycle.