A common occurrence is for merchants to uninstall and re-install your app. This guide provides best practices for how to gracefully handle this scenario.

Overview of app uninstalls

A common action taken by developers is to delete all merchant records after an app uninstall. This is not recommended, since there are situations where a merchant has uninstalled an app, but realizes that they need to re-install it within the same payment period. This can lead to overlapping app billing cycles.

For the best merchant experience, you should track when an uninstall occurs and the amount of days left in the current payment period. You can do this by subscribing to the Shop webhook, which notifies you when a merchant uninstalls your app. Then you can take one of the recommended actions described below.

Create another recurring application charge

In this scenario, the merchant is double billed, but offered a credit.

To issue the recurring app charge

  1. Create a new RecurringApplicationCharge.
  2. Create an ApplictionCredit to credit the merchant for one of the app charges.

POST /admin/application_credits.json

Request body:

  "application_credit": {
    "description": "application credit for refund",
    "amount": 10.0

For example, if a merchant installs your app on the 1st of the month and then uninstalls on the 10th, before re-installing on the 20th, their 30-day bill would include three charges: both recurring application charges, and the application credit.

Offer a free trial

Using this approach, you can provide the merchant with a free trial, either by extending the length of the free trial or not creating a charge for the overlapping days. For information about how to create free trials see Free trials.

Billings merchants who uninstall and re-install your app while on a free trial

In some cases, merchants will uninstall and re-install your app while on a free trial.

To best handle this scenario, Shopify recommends that you track the install and uninstall days of the merchant on a free trial. If the merchant still has remaining free trial days, then offer the merchant a prorated free trial. For example, if you offer a 7 day free trial, but the merchant installs and then uninstalls your app after 2 days, then offer 5 new free trial days.

In some cases, if enough time has lapsed (for example, 1 year), you might want to offer 7 days of free trial to encourage the merchant to try your app again.