Manage your app's versions and releases

In Stripe Apps, a version is a framework to help you manage changes to your app over time. A release is a version of your app that you decide to publish—either to your own account or on the Stripe App Marketplace after passing app review.

Versions overview

The version property in the app manifest lets you specify the version of your app. Stripe doesn’t enforce a specific versioning schema for apps, but we recommend following an established pattern, like semantic versioning.

Stripe users who install your app don’t have to think about the version number. Stripe automatically upgrades them to the latest release of an app. The app functions in a similar manner to apps updating automatically on your phone. The only exception is cases where the permissions scope changes. If you change the permissions, users of your app are prompted to re-authorize your app and its new permissions.

How to upload a new app version

1. Change the version property in the app manifest.
2. Upload the new app version to Stripe. Follow the same upload process that you used when creating an app.

Changing between app versions in test mode

You can change between different app versions in test mode and sandbox environments before creating a release.

1. In the Stripe Dashboard, go to Apps.
2. Select the app you want to create a new version for, and view App Details.
3. In the version history table, click the overflow menu () of the new version.
4. Select Install in test mode and complete the installation.

Releases overview

To distribute your app in live mode for users, create a new release. You can publish it to your own account or to the App Marketplace. To be listed in the App Marketplace, releases must go through App Review.

How to create a new release

1. In the Stripe Dashboard, go to Apps.
2. Select the app you want to create a new version for, and view App Details.
3. Click Create new release.
4. Follow the steps to create a new release.

When your release passes app review, all users are automatically upgraded to the latest released version.

How to remove an app listing or change a release

App releases can only be fixed forward. To remove an app listing or change an app release that had accidental changes, bump the app version and make a new release of the app.

Since we don’t enforce a versioning structure, an incremental release is any release created after the current live version. For example, if version 2.0.0 was uploaded before version 1.0.0, version 2.0.0 won’t be available to create a release.

To remove an app or an app release from Stripe, contact Stripe according to the terms of the App Marketplace Agreement, specifically the “Takedowns” section.

How app permission updates affect app users

When you release a version of your app with changed permissions, your app’s users must reauthorize it by approving any new permissions. If the app tries to perform an action without the required permissions, Stripe returns an “invalid request” error.

For more information about specific permissions and the functionality they control, see the Permissions reference.

When an app requires reauthorization, Stripe notifies users by email and through their Dashboards.

App reauthorization notification

Authorize new permissions