Migration guide
Technical details and steps for migrating legacy fields to the new form builder
Kyle Weiskopf avatar
Written by Kyle Weiskopf
Updated over a week ago

What does it mean to “migrate” my form?

Migrating essentially means copying your existing form and settings into the new form builder experience with improved user experience, more flexibility, and new features.

Breaking changes to Legacy forms

On June 1st, 2023, Customer Fields will remove all legacy features from the app’s codebase, including all forms created before December 2019. It's time to migrate to our new form builder, loaded with tools to help you grow your store.

Steps for migration

Follow the steps below to migrate a legacy form to the app's new form builder.

Step 1: Make a copy of the store's live theme

If your store's theme code includes any app-related customizations, then there is a chance that the customizations will be lost when migrating, and they may need to be reconfigured. For this reason, it's imperative that you make a backup of the store's theme before migrating or installing a new form, just in case you need to roll back the theme code to the old version.

Since you will be replacing the legacy form with the new migrated form, it's always best to test out the new form on an unpublished theme first; this way, you can ensure it's working as expected before customers start using it.

You can duplicate the store's live theme in the Shopify admin area under Online Store > Themes > Actions > Duplicate. We suggest renaming the duplicate theme to make it easier to reference later on.

Step 2: Navigate to the 'Fields' page

To start the process, open the Customer Fields app and access the 'Fields' page in the app admin by clicking the "Fields" tab on the left nav. From here, you will see a splash page that allows you to access the legacy fields editor or start the migration process. Click the 'Continue with migration' button to proceed.

Read the FAQ that appears on the following page, and then click the 'Continue with migration' button to begin the migration process.

Step 3: Run the migration

The migration tool will create a new form using the app's new and improved form builder. During migration, the app will automatically copy all of the legacy fields and settings from the legacy field editor. It will also create a form rule to hide legacy fields previously using the "Hide on registration" setting.

You'll have the option to edit the name of the migrated form, change the form's account options (learn more), and you can also preview an example of what the migrated form will look like before continuing.

Click the 'Continue' button to proceed and launch the app's new form builder.

Step 4: Configure the new form

Once you launch the form builder, you can customize the form by adding new fields or rearranging existing ones. Be sure to review each field on the form and the form settings to make sure things are set up properly. Once the new form is ready, click the 'Continue' button to proceed.


  • The 'Auto-tag' setting for Country and Province fields have been removed. If you need to add customer tags based on their country or province, you can do so by creating form rules. Learn more here: Tag customers by region.

  • The new version of the app has introduced the concept of data columns. If a legacy field has a name/key which contains spaces, the app will create new data columns with keys in the proper format (read more).

Step 5: Form install

On the installation page, you will want to use the 'Theme' dropdown to select the duplicate theme you created in Step 1. After selecting the proper theme, you will want to use the on-screen buttons and instructions to enable the app and install the form in the desired locations.

Pro tip: Most legacy forms are installed on both the registration and edit account pages, but some stores only use the app's form on the edit account page. You can find more details about form installation and the available options using this help article.

Step 6: Test the new form

Once the new form is installed on a theme, it's time to test it on the storefront by previewing the theme you selected when installing the form. Make sure to fill out the form's fields and submit the form to double-check that everything works properly.

Remember that you can edit the migrated form at any time using the 'Forms' page in the app admin if you need to make any changes. From the Forms page, click the 'Edit' button for the form to launch the form builder.

If you're ready to install the new form on the store's live theme, change the 'Theme' setting on the 'Installation' tab in the form builder. Select the live theme and repeat the installation steps.

Step 7: Disable legacy fields editor

The next step of the migration process is to disable the legacy fields editor in the app admin. This will remove the 'Fields' tab from the left nav, and it will also remove the 'Legacy data' card from the customer detail pages.

To disable the legacy fields editor, navigate back to the 'Fields' page in the app admin and click the red button for 'Disable fields editor.'

Step 8: Get rid of old code!

Finally, let’s clean up our leftover app code from all of your themes. Go to the app's Settings > Vintage uninstall page. Choose the 'Select all' box to remove legacy code from ALL themes, and push the red 'Uninstall' button. Au revoir!

✅ Migration success. What's next?

After migrating your form, you can learn more about the new features and benefits.

🤔 Need help migrating?

If you are unfamiliar with how your shop is currently utilizing the Customer Fields app, or if you simply would like some assistance with migration, our Customer Success team can help.

Did this answer your question?