Migrating from FastStore v1 to v4

FastStore v4 is the latest version of the framework and is recommended for storefront development.

For stores still running in FastStore v1, migrate directly to FastStore v4 in a new subaccount. This guide explains the migration process, how it works, and the steps required.

Migration overview

The migration process involves running two VTEX accounts in parallel. Your main account (FastStore v1) remains live while you create a subaccount (FastStore v4) for development, validation, and gradual rollout.

Step	FastStore v1 (main account)	FastStore v4 (subaccount)
1. Subaccount setup	Live store remains on v1. No changes made here.	Create a new subaccount with its own domain and CMS.
2. Development start	No new development in v1.	Set up the v4 project and repository.
3. VTEX IO apps	Map installed apps and document settings.	Review app compatibility, reinstall or replace in v4, update pointers, and reapply settings.
4. CMS	Headless CMS (legacy) content stays as is.	Recreate pages and content in the CMS for FastStore storefronts (migration not supported).
5. Intelligent Search	Existing search configuration remains unchanged.	Rebuild Intelligent Search settings manually in v4.
6. Master Data	Provide source data for unification.	Open a support ticket to configure and unify Master Data from v1 into v4.
7. Traffic splitting	Share live traffic with v4 during the transition.	Gradually receive traffic, measure key metrics, and tune until stable.
Completion	Eventually retired after migration.	Becomes the live store (go live on v4).

Before you begin

This guide is for VTEX accounts currently using FastStore v1 that need to migrate to FastStore v4.

Before starting the migration, check the version of your FastStore project and set up the required GitHub environment.

Check your FastStore version

Confirm that your project is running on FastStore v1. You can check as follows:

In your project root, check for one of these files:
- store.config.js: Used by FastStore v1.
- discovery.config.js: Used by FastStore v4.
If store.config.js is present, your project is likely running on FastStore v1.
Open the package.json file and review the dependencies:

Package name FastStore v1 FastStore v2+
@faststore/core ❌ ✅
@faststore/styles ✅ ❌

If @faststore/styles is present and @faststore/core is missing, your project is running on FastStore v1.

See the key differences between FastStore versions in the guide FastStore versions and support levels.

Package name	FastStore v1	FastStore v2+
`@faststore/core`	❌	✅
`@faststore/styles`	✅	❌

Have a GitHub account

You'll need a GitHub account to set up your FastStore v4 project. You can use either a personal account or a GitHub organization. If you choose to use a GitHub organization, make sure you have admin access to it.

Instructions

Step 1 - Create a VTEX subaccount

To begin developing in v4, create a subaccount linked to your main VTEX account by following the Managing a multistore article.

This subaccount is a dedicated, isolated environment that ensures all v4 development and deployments don't affect your live FastStore v1 store. It will have its own domain, which prevents redirect conflicts, and an independent CMS, which avoids any data or content cross-contamination between environments.

Don't start developing directly in the main account (live store) without using a subaccount. Doing so can result in the deletion of your Headless CMS (legacy) live content during the WebOps onboarding process for FastStore v4.

Step 2 - Start development for v4

In your new subaccount, start your v4 project by following the FastStore getting started track.

Once you complete these steps, you'll have a repository linked to your subaccount (for example: subaccount.store). All your v4 development must be done in this repository.

Step 3 - Audit VTEX IO apps for compatibility

Each VTEX account or subaccount manages its own VTEX IO app installations, permissions, and URLs. Some apps that work in FastStore v1 may not work out of the box in v4 and may require a custom integration or an alternative distribution method.

Audit all VTEX IO apps from your v1 store to identify compatibility issues and prepare them for migration.

Step	Description
1. Map the store apps	Map all apps (`vendor.name`, current version) used by the v1 store.
2. Check v4 compatibility	Check the compatibility of each app with FastStore v4. If an app is incompatible, you can choose between custom integration, replacing it with an alternative, or deferring/removing it. If the app is compatible, continue to read the steps in this table.
3. Decide the cross‑account install strategy	Determine whether the app can be installed in the v4 account. If it's currently tied to the v1 account, you can do one of the following: Public app: Publish it so it can be installed in other accounts. Sponsor account + edition: Use a sponsor account to distribute the app to target accounts via an edition. Private/single‑account: Rebuild/republish under the vendor for account Y or adjust distribution so Y can install.
4. Update account‑specific pointers	Audit the app for hard‑coded account or workspace references and change them from v1 to v4. Search for absolute URLs and paths like: `[https://{account}.myvtex.com/_v/](https://{account}.myvtex.com/_v/)...`, `…?an={account}` or internal routes or endpoints that include the account or workspace name. Replace with the v4 account values. Where possible, externalize pointers into configuration (env vars/app settings) to avoid future hard-coding.
5. Plan for app data and settings	You can't transfer app data or app settings from one account to another. Export or document all current app settings (including secrets, API keys, and toggles). Recreate them manually in the v4 account after installation. Record any one-time data seeding steps required by the app.
6. Permissions and policies	Review and update required policies for the app. Confirm any store or admin permissions needed in v4.

Step 4 - Recreate the storefront content

When you create a new v4 subaccount, the CMS for FastStore storefronts is the only CMS option available. Recreate all necessary pages, components, and content directly in this CMS.

Content migration from Headless CMS (legacy) to the CMS for FastStore storefronts isn't supported. Once your subaccount is ready, manually recreate the storefront content in the new CMS, since stores using Headless CMS (legacy) are being gradually migrated. For more information, see the announcement Headless CMS (Legacy): Stores will be upgraded to the new VTEX CMS.

Step 5 - Recreate Intelligent Search settings

Rebuild your Intelligent Search configuration manually in the v4 environment, and plan enough time to reproduce and test all search settings in your subaccount. Learn more in Intelligent Search - Overview.

Migrating Intelligent Search settings from a v1 project to v4 isn't supported.

Step 6 - Unify Master Data

Open a ticket with VTEX Support to configure, validate, and unify Master Data from the account (FastStore v1) to the subaccount (FastStore v4).

This process ensures that all customer information, including profiles, login credentials, and order history, remains consistent across both environments during migration.

Master Data unification must be completed before traffic splitting begins.

Step 7 - Split traffic between v1 and v4

Once you've completed all previous steps, open a ticket with VTEX Support at least five days before your planned migration date to request traffic splitting between your main account (FastStore v1) and subaccount (FastStore v4).

This gradual rollout allows you to slowly redirect users from the old store to the new one, monitor performance, and ensure stability before going fully live on v4.

Consider the following during the process:

Traffic splitting vs. A/B testing: FastStore uses traffic splitting to gradually transition users between v1 and v4. You can also use this setup to run A/B tests with your analytics or testing tools to compare performance between both versions while the split is active.
Measure key metrics: Track and compare metrics such as conversion rates, engagement, and SEO performance across both versions. Use this data to optimize your configuration and adjust traffic allocation as needed.

Once v4 performance is validated, make it your live store and retire FastStore v1.