All Collections
Customer Fields
Legacy Fields
Customer Fields migration guide
Customer Fields 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: Get rid of old code

Let’s clean up the legacy app code from your test theme. Go to the app's Settings >Vintage uninstall page. Select the specific test theme that you are using and push the red 'Uninstall' button. In most cases, this should reliably remove an old code and prevent conflicts when creating your new form.

Step 3: 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 4: 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 5: 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 6: 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 7: Get rid of any remaining 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.

Did this answer your question?