What to do when a Shopify app is uninstalled

A common problem that comes up with public Shopify Apps is knowing when your app is uninstalled.

I’m not sure how I’m supposed to know if the user has installed the app or not.

Why would you care if your app is uninstalled?

  • If you’re trying to grab data from the store, these API requests will now fail…
  • If you’re billing outside of Shopify like in Stripe, you’ll need to cancel those transactions before you have a very upset customer…
  • (Probably most importantly) You’ll want to be notified about the uninstall and try to reach out to the merchant and see if you can help them and reactivate their account.

There’s two ways to find out if your Shopify app is uninstalled.

1. Uninstall webhook

First, whenever a store uninstalls an app Shopify will send the app the apps/uninstalled webhook. This webhook includes information about which store uninstalled so your app can perform any uninstallation tasks.

You will need to register for this webhook so Shopify knows you’re interested in it. I like to do this when the app is first installed.

2. Failing API requests

The second way to tell if your app is uninstalled is to watch for 401 or 403 response codes from the Shopify API. In Ruby, using the Shopify API gem these come up as ActiveResource::UnauthorizedAccess and ActiveResource::ForbiddenAccess exceptions which you can easily catch and handle.

Tip: Watch out for uninstall/installs

Sometimes a merchant will accidentally uninstall your app and then try to re-install it. Sometimes this happens because they’re hoping this will reset something, just like you would turn your computer or phone off and back on when it acts up.

Depending on what you do when an uninstall happens, you might want to delay and wait a few minutes before processing the uninstall request. For example, instead of deleting their account and all of their data right away; wait 6, 12, or even 24 hours.

A safer option is to change your how app’s admin area acts for an uninstalled store. Show the merchant a special page saying the app has been uninstalled, asking if this was a mistake, if they’d still like to use it, and if they would like to re-install it.

Be thoughtful about your app’s lifecycle

Uninstalls are part of every Shopify App’s lifecycle. Sometimes they are accidents, other times the merchant isn’t needing your app anymore.

Whatever the reason, with a little bit of code and some thought you can handle the majority of these cases and provide a great experience for the merchant.

Pick an option above and make sure to include it in your app. Either the apps/uninstalled webhook or by watching for failed API requests – or even both.

Learn how to fix authentication errors in your Shopify app

Hear when Shopify App Authentication is available, along with any limited-time launch bonuses or discounts.

Bonus: While you wait, you'll also get articles about other Shopify app development topics.