docs/content/developers/github-marketplace/billing-customers.md

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.	[/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]	[{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."

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."