Customer experience best practices for apps

Guidelines for creating an app that will be easy to use and understand.

If you follow these best practices it will help you to provide a good customer experience.

Customer communication

  • Marketing materials for the app should accurately represent the app's behavior.
  • Apps should include links to user-facing documentation that describe how to set up and use the app.
  • Customers should be able to see what type of plan they have in the billing, profile, or account settings section of the app.
  • Customers should be able to install and use your app on both a personal account and an organization account. They should be able to view and manage the app on those accounts separately.

Plan management

  • Customers who cancel a paid plan purchased from GitHub Marketplace should be automatically downgraded to the app's free plan if it exists. When a customer cancels a GitHub Marketplace subscription, GitHub does not automatically uninstall the app, so the customer can expect that free features will continue to function. It's highly recommended to allow customers to re-enable their previous plan.
  • Customers should be able to upgrade from your app's user interface if you provide an upgrade URL in this format:<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/<CUSTOMER_ACCOUNT_ID>
  • Customers should be able to modify which users have access to your app from your app's website if they purchased seats (per-unit pricing plan) or the plan offers unlimited collaborators.
  • Customers should be able to see the following changes to their account immediately in the billing, profile, or account settings section of the app's website:
    • Current plan and price.
    • New plans purchased.
    • Upgrades, downgrades, cancellations, and the number of remaining days in a free trial.
    • Changes to billing cycles (monthly or yearly).
    • Usage and remaining resources for flat-rate and per-unit plans. For example, if the pricing plan is per-unit, your app's site should show units used and units available.

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.