# Migrate an extension to Stripe Apps Learn why and how to migrate your extensions to Stripe Apps. [Extensions](https://docs.stripe.com/building-extensions.md) are legacy integrations built on Stripe Connect. Through OAuth and API requests, they bring Stripe data into other business tools, like analytics dashboards or data warehouses. [Stripe Apps](https://stripe.com/apps) replaced extensions as the preferred way to integrate Stripe with other tools as of 2022. You can no longer create new extensions. All mention of legacy extensions were removed from the [Stripe Partner Directory](https://stripe.partners/). If you own a legacy extension, migrate to Stripe Apps now to ensure discoverability on the [Stripe App Marketplace](https://marketplace.stripe.com/). ## Reasons to migrate Stripe Apps is an upgrade from legacy extensions. By migrating, you get the following: - Better discoverability, with broad visibility in the Stripe Dashboard and the Stripe App Marketplace - More granular permissions, so you can set (and your users can understand) what data and APIs an app can access - Interactive functionality, with embedded UI components in the Stripe Dashboard (so users can interact directly with your app without leaving Stripe) - No interruption to your existing extension users if they choose to migrate ### What happens if you don’t migrate If you choose not to migrate your legacy extension to a *Stripe App* (An app that you can build on top of Stripe to customize the functionality of the Stripe Dashboard UI, leverage Stripe user data, store data on Stripe, and more), your extension will continue to work as it does today, for now. Legacy extensions are officially deprecated, ongoing support isn’t guaranteed, and new features aren’t available to legacy extensions. Additionally, new users can’t discover legacy extensions through the [Partner Directory](https://stripe.partners). We recommend that you migrate your legacy extension to a *Stripe App* (An app that you can build on top of Stripe to customize the functionality of the Stripe Dashboard UI, leverage Stripe user data, store data on Stripe, and more) as soon as possible. ## Stripe Apps vs. extensions An app can do everything an extension does, with two key additions: 1. Interactive functionality, using embedded UI components in the Stripe Dashboard. 1. More granular permissions to help users understand what data an app can access. The other difference is that any user can discover apps from the Stripe App Marketplace instead of the Partner Directory. | Extensions | Stripe Apps | | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Any Stripe user can use your extension. | Any Stripe user can install your app. | | Not discoverable from the [Stripe Partner Directory](https://stripe.partners) or [Stripe App Marketplace](https://marketplace.stripe.com). | Discoverable in the [Stripe App Marketplace](https://marketplace.stripe.com) and Stripe Dashboard. | | You can find your existing extensions in the Dashboard, under **Developers** > **Extensions**. | You can find your apps in the Dashboard, under **Developers** > **[Apps](https://dashboard.stripe.com/apps)**. | | Extensions are limited to either all read or all write permissions. No support for granular permissions. | You can request a granular set of permissions from users as part of app installation, increasing security and user trust. | | You can’t create new extensions. | Any developer can build on Stripe’s App Platform. | | After users link their Stripe accounts to your extension with OAuth, you can make API requests on their behalf. | Choose from [multiple authorization types](https://docs.stripe.com/stripe-apps/api-authentication.md) to support your user onboarding and API request flow. | | Users interact with your legacy extension by installing additional tools and leaving Stripe. | Users can interact with your app directly in the Stripe Dashboard. | | No ability to extend the Stripe UI. | You can build directly in the Stripe Dashboard. | ## Impact on your extension’s users When you upload and publish a Stripe App to the account that owns the legacy extension, this enables the migration process for users of your extension to switch to your Stripe App. The migration process doesn’t disrupt existing extension users. After migrating your extension to a Stripe App, your existing users will see a badge in their [extension settings](https://dashboard.stripe.com/test/extensions) page prompting them to re-authorize the permissions for your app. Your users must accept permissions to begin using your migrated app. Administrators on your users’ stripe accounts will see the following: ![Migrated app permissions example](https://b.stripecdn.com/docs-statics-srv/assets/migrated-app-permissions-diagram.8ed2661a5c4c75477ccd9aa77f02cd13.png) For a seamless migration process for your users, migrate your extension to an app by uploading the app to your existing account. If you don’t want to prompt your existing users to migrate, you must upload and publish your Stripe App on a separate Stripe account. You can’t have both an existing extension and an unrelated Stripe app on the same Stripe account. ## Migrate to Stripe Apps Follow the steps below to migrate your extension to a Stripe App. ![Steps to migrate an extension to a Stripe App](https://b.stripecdn.com/docs-statics-srv/assets/migrate_to_stripe_app_diagram.a741f6bfbd91e5840e123d581733bca9.png) Migrating an extension to a Stripe App ## Before you begin - While you develop your Stripe App, we recommend [testing](https://docs.stripe.com/stripe-apps/test-app.md) and uploading your app with a separate or new Stripe account. You must use a different ID for your app in the test account because app IDs are globally unique (for example, `"id": "com.example.myapp"` and `"id": "com.example.myapp.test"`). - To add an extra layer of safety, create a separate testing instance of your backend. While testing your Stripe app, avoid making changes to the backend code powering your live extension. - After testing your Stripe app, upload the app (with your final desired app ID) to the same Stripe account that owns your extension, then [publish your app](https://docs.stripe.com/stripe-apps/publish-app.md). ## Create an app manifest [Create an app manifest by creating a Stripe App](https://docs.stripe.com/stripe-apps/create-app.md). ## Optional: Add interactive functionality Optionally, you can add interactive functionality in the Stripe Dashboard with UI components: 1. [Build UI components on your Stripe App](https://docs.stripe.com/stripe-apps/build-ui.md). 1. [Build a self-hosted backend and authenticate users to your backend](https://docs.stripe.com/stripe-apps/build-backend.md). ## Choose an authentication type To make API calls from your back end on behalf of users that install your app, you must choose from the available [API authentication types](https://docs.stripe.com/stripe-apps/api-authentication.md). Most legacy extensions find that either the `platform` or `oauth` options offer a drop-in replacement for their existing Stripe integration, with minimal changes required. ## Add permissions to your app [Add permissions](https://docs.stripe.com/stripe-apps/reference/permissions.md) to your app manifest. If you need help with identifying the right permissions, after you [upload your app](https://docs.stripe.com/stripe-apps/upload-install-app.md) you can use the Permission Migration Tool on the App Details page to view recommended missing permissions. The tool reviews the recent requests on your account and analyzes the necessary permissions for your app. You can find the migration tool by navigating to your app on the App Details page in the [Dashboard](https://dashboard.stripe.com/apps). The tool exists in multiple locations highlighted below. ![Entry point for permission migration tool for unpublished apps](https://b.stripecdn.com/docs-statics-srv/assets/permission_tool_entry_point_unpublished.400af30ac4fb84772931a492e8b7edbe.png) Callout and button for unpublished apps ![Entry point for permission migration tool for published apps](https://b.stripecdn.com/docs-statics-srv/assets/permission_tool_entry_point_published.1c4da81be36b34728ab23812763573ab.png) Pushed to overflow menu option when app is published > When a user authorizes the new permissions for your Stripe App, this overwrites the unrestricted read/write all permissions previously granted to your extension. To ensure your existing users don’t experience permissions-related interruptions when migrating, you must include the necessary permissions in your app manifest prior to migrating existing users. ## Upload your app Use the CLI to [upload your app](https://docs.stripe.com/stripe-apps/upload-install-app.md) to Stripe. ## Publish your app [Submit your app for review and publish it on the Stripe App Marketplace](https://docs.stripe.com/stripe-apps/publish-app.md). To increase your chances of passing app review, adhere to Stripe’s: - [App review requirements](https://docs.stripe.com/stripe-apps/review-requirements.md) - [App publication guide](https://docs.stripe.com/stripe-apps/publish-app.md) > When you provide test credentials, make sure the test account has access to the app installation flow. Your app **must pass** App Review to list it in the Stripe App Marketplace. ## Onboard users After migration, your existing users must re-authorize the app’s permissions in the Dashboard in order to use your Stripe app. You can onboard *new* users to your Stripe App in two ways: - You can publish your app in the Stripe App Marketplace after migrating your legacy extension and passing App Review. - New users can continue to onboard to your legacy extension with Connect OAuth from your website. > To avoid onboarding new users with OAuth after you complete the migration, you can remove your OAuth callbacks and redirect new users to your app listing on the Stripe App Marketplace by changing your website’s **Connect with Stripe** button. ## See also - [Stripe Apps](https://docs.stripe.com/stripe-apps.md) - [Sample apps](https://docs.stripe.com/stripe-apps/sample-apps.md)