Migrating from the Legacy Product Experience: Upgrading to BigCommerce v3

Migrating from the Legacy Product Experience BigCommerce

CHAPTER 1: Comparing V2 and V3 Product Experiences and Considerations

Product data being moved from v2 to v3

In 2019, BigCommerce upgraded our products to support more features that our merchants need to grow, such as omnichannel sales, API accessibility, SKU-level attributes, more intuitive options, and variants management. Products now use our Catalog v3 API, which allows merchants to leverage the API to streamline their workflows and provide a fantastic shopper experience. In this guide, we will cover how v3 products differ from the original v2, and explore v3 features such as variants and customizations. We will look at reasons why you may not want to migrate yet from v2 to v3, and reasons why you should consider making the jump. Finally, we will outline how to migrate from v2 to v3 (upgrading to BigCommerce v3), including requirements and any potential preparation to ensure a smooth transition.

CHAPTER 2: Switching to the V3 Product Experience: Upgrading to the New Product Experience

Switching to the V3 Experience

upgrading to BigCommerce v3

Try it out! You can view and test the v3 experience beforehand by creating a trial store. This also allows you to become familiar with the new layout of product details and creating product options, variations, and modifiers.

When adding or editing products, if you see the opt-in banner for the new product experience, your store is already eligible to upgrade to BigCommerce v3. Simply click Update now to start the migration.

If you don’t see this banner, you may need to make changes to your catalog before your store is eligible. This is due to certain aspects of v2 functionality not having an equivalent in v3 or setup incompatibility between v2 and v3 fields. Most stores should be able to use the steps detailed in our Quick Guide to meet the catalog requirements.

Depending on the size and complexity of your store’s catalog, preparing your catalog for v3 migration (upgrading to BigCommerce v3) may require advanced planning to minimize any storefront impact, such as putting your store into maintenance.

Requirements for Upgrading to BigCommerce v3

To upgrade to BigCommerce v3, your store needs to meet the following requirements:

  • No option sets associated with products, or options present on products
  • No Configurable Fields enabled on products

We’ve created a Quick Guide for Disassociating Option Sets using CSV export/reimport. You can also remove option sets manually from individual products within the control panel using the steps provided further down.

Make a backup copy! Be sure to back up your product information, including image files, before following these steps. If you do not make a backup, BigCommerce cannot restore your data.

After meeting all of these requirements, if your store is eligible to upgrade to v3, you will see the opt-in banner for the new product experience at the top of the page when you’re editing or adding a product. If you’ve made the above changes and feel that your store meets requirements but you still don’t see the opt-in, contact our support team.

If you upgrade to v3 and decide you want to go back to v2, contact our support team for assistance. We do not typically downgrade stores to v2 unless there is a strong business need for this legacy feature on Enterprise and partner sandboxes and stores. You must have your product backup CSV file available.

Quick Guide for Disassociating Option Sets: Preparing Your Catalog for BigCommerce v3

To disassociate all option sets from products in bulk, you can use the CSV export/reimport method. As this will leave your products available on the storefront without any options, we recommend putting your store into maintenance until you have completed migrating to v3 and recreated your product options.

Note: It is not necessary to delete your Option Sets, only to disassociate them from your products. For backup purposes, we recommend not deleting your Option Sets and instead only disassociating them using the method below.

Make a backup copy! Be sure to back up your product information, including image files, before following these steps. If you do not make a backup, BigCommerce cannot restore your data.


Follow these steps to disassociate option sets using CSV export/reimport:

  • Export your products using the Bulk Edit template.
  • Make a copy of the CSV file and save it for your records.
  • Remove all SKU rows from your working CSV file. You can do this quickly by using the “Filter” feature on the Item Type column. While this step is optional, it will ensure that you don’t see import errors for disassociated options when updating your catalog later on.
  • Remove all columns from your working CSV file, except for the ones listed below. This is to minimize the risk of product data loss.

    • Product ID
    • Product Name
    • Option Set
    • Track Inventory
    • Category
  • Change all option sets in the Option Set column to the same thing, e.g., “temp” or anything that isn’t an existing option set in your catalog. This will disassociate the product from your existing option sets.
  • Update all product fields under the Track Inventory column from “by option” to “by product”.
  • Save your updated CSV file. Use a unique file name to make it easier to locate in the future.

Reimporting Your Products: Updating Your Catalog to BigCommerce v3

Import your products using the edited CSV file. Select the Bulk Edit Re-import option.

  • Select “File was exported using the ‘Bulk Edit’ template.”
  • Uncheck “Ignore blank values during import” and continue with the import workflow. While we don’t recommend disabling this setting during product updates due to the risk of deleting product data, we are using it here to cleanly remove option set data from products.

After importing, check your products to ensure that all option sets have been removed.

Cleaning Up: Recreating Options and Variants After Migration

Delete the “temp” option set if used. Product options and variants can be recreated after migration, using shared variant options and shared modifier options.

Removing Option Sets Manually in the Control Panel

If you want to remove your option sets from products individually in the control panel, you can do so by editing a product, going to the Options & SKUs tab, and selecting “(None)” from the Option Set dropdown menu. This will delete any existing product options and variants.

Select “(None)” to remove the option set on a product.

Configurable Fields

This is a deprecated field that was found under the Custom Fields tab. Stores created before 2018 may still have products using these fields. Note that this is different from Custom Fields:

Configurable Fields, if present on your store, are found under the Custom Fields tab.

To remove configurable fields, go to the Custom Fields tab and remove any text in the Field Name. The Required checkbox should be disabled as well if it is checked. When ready, click Save. They can also be updated via API.

Future Improvements


BigCommerce is working to automate the upgrade from v2 to the v3 catalog experience. In the near future, we expect to:

Migrate options and variant SKUs automatically, with some limitations. These limitations include:

  • Option sets will be removed, as they’re not included in v3.
  • Existing options in option sets will be recreated as shared options and shared modifiers, but not assigned to existing products.
  • Options and variants will remain assigned to products, but they won’t be shared. Merchants will need to update their values per product, if necessary.

The v3 product experience offers greater ease in creating and editing products, as well as versatility in the options you can create for your products. Review the considerations listed above, and when you’re ready, update your store’s catalog to the latest experience. With a clean layout and the features you need in a modern online store, it’s never been easier to manage your catalog and bring your products to valued customers, old and new. Don’t miss out on the benefits of upgrading to BigCommerce v3!

0 0 votes
Article Rating
Notify of
Inline Feedbacks
View all comments