49 lines
3.6 KiB
Markdown
49 lines
3.6 KiB
Markdown
---
|
|
title: Billing customers
|
|
intro: '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.'
|
|
redirect_from:
|
|
- /apps/marketplace/administering-listing-plans-and-user-accounts/billing-customers-in-github-marketplace/
|
|
- /apps/marketplace/selling-your-app/billing-customers-in-github-marketplace/
|
|
- /marketplace/selling-your-app/billing-customers-in-github-marketplace
|
|
versions:
|
|
free-pro-team: '*'
|
|
---
|
|
|
|
|
|
|
|
### 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](/developers/github-marketplace/webhook-events-for-the-github-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](/developers/github-marketplace/using-the-github-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](/rest/reference/apps#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](/developers/github-marketplace/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](/developers/github-marketplace/handling-plan-cancellations)."
|