This guide provides user experience (UX) guidelines for Partners that want to migrate existing merchant subscription data into Shopify. You can reference this guide to ensure that the experience you build aligns with the technical steps and APIs described in our [Subscriptions API migration guide](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api).

You can use [Polaris](https://polaris.shopify.com/) or your own visual language to build the components displayed in this guide.

## Requirements

To be eligible to use Shopify subscriptions, merchants need to meet the [qualifying criteria](https://help.shopify.com/en/manual/products/subscriptions/setup#eligibility-requirements).

## Recommended migration process

The migration process is divided into two steps:

| Step | Tasks |
|---|---|
| [**Step 1**: Migrate your settings](#step-1-migrate-your-settings) | <ul><li>[Create selling plans and selling plan groups](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api#create-selling-plans-and-selling-plan-groups-for-your-subscriptions)</li><li>[Create checkout discount codes](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api#create-checkout-discount-codes)</li><li>[Manage discount errors (if applicable)](#managing-discount-errors)</li><li>[Create delivery profiles for shipping](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api#create-checkout-discount-codes)</li><li>[Inform merchants that taxes will be exclusively computed by their settings in Shopify](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api#charging-taxes)</li><li>[Update theme code](#updating-theme-code)</li></ul> |
| [**Step 2**: Migrate legacy subscribers and data](#step-2-migrate-legacy-subscribers-and-data) | <ul start="1"><li>[Connect Stripe as a secondary payment gateway](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-customer-information#step-1-configure-your-payment-gateway-to-work-with-subscriptions)</li><li>[Create new payment methods for customers](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-customer-information#step-2-import-payment-methods-for-customers)</li><li>[Import subscription contracts](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts#step-1-import-subscription-contracts)</li><li>[Create billing attempts](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts#step-2-create-billing-attempts)</li></ul> |

## Migration strategy

Before you begin helping merchants migrate to use subscriptions in Shopify, consider a migration strategy that includes the following:

- Creating a clear mental model for merchants so they [understand what is migrated, in which order, and how it changes their process](#viewing-migration-progress).
- Giving merchants [a time estimate for how long the migration process will take](#displaying-an-estimated-migration-time), and which jobs are being done in the background.
- Communicating how migrating will help merchants run their subscription business by being [better integrated in Shopify](/docs/apps/build/purchase-options#shopifys-principles).
- Offering links to further documentation for more information about how migrations affect subscriptions and about the customer experience. If the merchant isn’t eligible to migrate, then [link to documentation that outlines the steps to be eligible](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api#merchant-eligibility-for-subscriptions).

> Note:
> It's important to communicate to merchants what is no longer supported. Consult [our help documentation](https://help.shopify.com/en/manual/products/subscriptions) to ensure that merchants have all information they need to confidently onboard to the migration process.

### Onboarding banner

You can use an onboarding banner to offer merchants that are eligible to migrate to subscriptions. Don't show the onboarding banner if the merchant isn't eligible to migrate.

![Subscriptions onboarding banner](/assets/api/subscriptions/subscriptions-onboarding-banner.png)

### Viewing migration progress

To help merchants better understand the migration process, there needs to be a progress page that allows merchants to do the following:

- Learn more about the impact of migration.
- Understand upcoming milestones.
- Access information to understand what completion looks like for each step of the migration process.
- See where there are errors, if any, and a way to fix them.

It’s also important that there’s a way for the merchant to leave the page and know how they can access it again.

![Subscription migration progress page](/assets/api/subscriptions/subscription-migration-progress-page.png)

### Showing updates on the app homepage

Merchants might want to leave the progress page during migration to focus on running their businesses. You can show updates on the app homepage to ensure that merchants have the right information at the right time.

#### Migration still in progress

Show a banner on the app that reflects the migration progress. Always include a way to access the progress page in addition to the overview of the status.

![Migration in progress banner](/assets/api/subscriptions/migration-in-progress.png)

#### Action required: errors need to be fixed

If there are errors, then show how many errors there are and what area is affected:

![Action required errors need to be fixed banner](/assets/api/subscriptions/action-required-errors.png)

#### Action required: next steps

If there are any next steps that the merchant should follow, then show the following information:

- Errors that need attention
- The next action to take to complete the migration

![Action required next steps banner](/assets/api/subscriptions/action-required-next-steps.png)

### Viewing and managing errors

During the migration of data, certain errors can occur due to incorrect settings or duplicated information. It’s important that merchants understand why an error has occurred. They also need to be informed about how to resolve the error.

You can help merchants view and manage errors by doing the following:

- Provide a link to a page where a setting needs to be changed.
- Provide a link to a page where the error can be managed. For example, if there are duplicate discount codes that can’t be migrated, then the link should take the merchant to the **Discounts** page, where they can replace, rename, or delete codes.

Display an error banner in the right context and link to where error can be resolved:

![Error banners in context of a page](/assets/api/subscriptions/error-banners-in-context.png)

### Emailing updates

As the migration process runs in the background, merchants should receive a notification in their email about any required actions. This allows merchants to focus on other important tasks without needing to check the app homepage for updates.

#### Example email informing merchants about errors

Hi _merchant name_,

There is an error migrating some of your subscription data. Visit the app for more details and next steps.

_**[Go to app]**_

#### Example email informing merchants about a required action

Hi _merchant name_,

You can now finish migrating your subscription setup by updating your theme code.

_**[Update theme code]**_

### Canceling or pausing migration

Merchants who are in the middle of migrations need to have a way to cancel or pause the migration should something unexpected happen. It’s important to make sure that merchants feel in control of this process, as it can hurt their trust in Shopify when they find themselves stuck in a process without a way out.

To help merchants feel in control of the migration process, show a cancel button and either assure merchants that this won’t impact their business, or explain any consequences for cancelling the process.

If no cancel button is available, then offer merchants other steps, such as calling Support.

![Cancel or pause migration notice](/assets/api/subscriptions/cancel-or-pause-migration.png)

## Step 1: Migrate your settings

The first step in the migration process allows merchants to [process new subscriptions and manage new subscribers through Shopify](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api).

As part of the first step, merchants might need to [manage discount errors](#managing-discount-errors) and [update their theme code](#updating-theme-code).

### Managing discount errors

Merchants will likely have created discounts in the Shopify admin and in the app using the same discount code. When these codes are now migrated to the Shopify admin, an error occurs, as discount codes need to be unique.

Merchants need to be able to resolve this error themselves and choose what to do with the discounts.

Make the following actions available to merchants during this process and ensure that merchants are aware of the consequences of their actions:

- Replace the discount in the Shopify admin with the one from the app. This results in deleting the discount in the Shopify admin.
- Rename the discount in the app to a unique code.
- Delete the discount that exists in the app.

![Manage discount codes page](/assets/api/subscriptions/manage-discount-codes.png)

### Updating theme code

When the subscription data has been migrated, merchants might need to [update the theme code](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api#add-code-to-the-storefront) from the app to make sure that selling plans are displayed correctly on the store.

Do the following to help merchants complete the first step of migration:

- Show that the previous steps are done, to assure merchants of their progress.
- Prompt merchants to update the theme code.
- Communicate that when their theme code is updated, they can process new subscriptions through Shopify, and that their subscription settings will be fully integrated with Shopify admin and checkout.

![Subscription migration step one](/assets/api/subscriptions/subscription-migration-step-one.png)

## Step 2: Migrate legacy subscribers and data

When the first step of migration is finished, merchants can [start migrating over their legacy subscribers and data](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts). Depending on the data that needs to be migrated, this step might take longer than merchants expect.

As part of the second step, you should [display an estimated migration time](#displaying-an-estimated-migration-time) to inform merchants how long the migration will take.

### Pausing billing

We strongly recommend pausing billing within the app during the migration. This helps to avoid double billing contracts. If you choose to not pause billing during this step, then merchants need to be informed of any issues they might experience (such as double billing).

If you pause billing during the migration, then you should clearly inform merchants that billing will be paused before they start the migration, and that it will resume after migrating is finished. The merchant's store checkout won't be affected.

### Displaying an estimated migration time

Display an estimate for how long the migration will take. This is especially important if billing is paused during migration, and if it's a large merchant with a lot of data. Displaying an estimated migration time helps merchants decide when to begin the migration to avoid interfering with their business.

![Payments paused notification](/assets/api/subscriptions/payments-paused-notification.png)