3.6 KiB
title, intro, redirect_from, versions
| title | intro | redirect_from | versions | |||||
|---|---|---|---|---|---|---|---|---|
| Billing customers | Apps on {% data variables.product.prodname_marketplace %} should adhere to GitHub's billing guidelines and support recommended services. Following our guidelines helps customers navigate the billing process without any surprises. |
|
|
Understanding the billing cycle
Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make 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 (effective_date). For more information about webhook payloads, see "Webhook events for the {% data variables.product.prodname_marketplace %} API."
Providing billing services in your app's UI
Customers should be able to perform the following actions from your app's website:
- Customers should be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately. {% data reusables.marketplace.marketplace-billing-ui-requirements %}
Billing services for upgrades, downgrades, and cancellations
Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "Using the {% data variables.product.prodname_marketplace %} API in your app."
You can use the marketplace_purchase webhook's effective_date key to determine when a plan change will occur and periodically synchronize the List accounts for a plan.
Upgrades
When a customer upgrades their pricing plan or changes their billing cycle from monthly to yearly, you should make the change effective for them immediately. You need to apply a pro-rated discount to the new plan and change the billing cycle.
{% data reusables.marketplace.marketplace-failed-purchase-event %}
For information about building upgrade and downgrade workflows into your app, see "Handling plan changes."
Downgrades and cancellations
Downgrades occur when a customer moves to a free plan from a paid plan, selects a plan with a lower cost than their current plan, or changes their billing cycle from yearly to monthly. When downgrades or cancellations occur, you don't need to provide a refund. Instead, the current plan will remain active until the last day of the current billing cycle. The marketplace_purchase event will be sent when the new plan takes effect at the beginning of the customer's next billing cycle.
When a customer cancels a plan, you must:
-
Automatically downgrade them to the free plan, if it exists.
{% data reusables.marketplace.cancellation-clarification %}
-
Enable them to upgrade the plan through GitHub if they would like to continue the plan at a later time.
For information about building cancellation workflows into your app, see "Handling plan cancellations."