Migrating Products to BigCommerce Catalog v3 API: Preparations, Challenges, and Solutions

persona on laptop browsing tshirts in online shop

Our previous post reported the general differences between the BigCommerce v2 and v3 Product Experience, benefits and eligibility for migrating, and what the upgrade process entails. Now, we’ll take a closer look at one of the major elements involved—migrating product data. 

Migrating from Catalog v2 to v3 API can be challenging, especially when dealing with product options (now called variants in v3). As product options play a crucial role in the functioning of ecommerce stores, it’s essential to have a comprehensive picture of what to expect with the upgrade.

Merchants must also understand how to review product data to ensure a smooth transition and have the right potential solutions in place to remedy any issues along the way.

Defining Common Terms in the v2 to v3 Product Migration

Before we dive into the challenges of migration, let’s first define the common language associated with v2 and v3. As you learn more about the migration process, you’ll notice that some v2 terminology has been replaced by v3 terms that describe similar or equivalent functionality.

      • Product options are product attributes like size and color, but they can also be things like checkboxes or fields for adding custom text.

            • Options sets, specific to v2, represent different product options, which are then applied in bulk to products. Option sets may or may not be required.

            • Required options mean shoppers must select an option (like a small size of a t-shirt) before they can add the product to their cart. 

            • Non-required options are item variations useful for optional add-ons or customizations, like engraving or gift packaging.

          • Values are identifiers for each product option. For example, a size option would have values like small, medium, and large. For some option types, values are created by the shopper, like custom text fields or file upload fields.

          • SKUs (Stock Keeping Units) are unique identifiers assigned to products and variants in order to track inventory. With BigCommerce, you can assign SKUs to both the base product and its individual variants.

          • Variations, or variants (v3), the equivalent of product options in v2, are specific versions of a product defined by unique option values—like a small, blue shirt. Each variant can have its own image, price, and weight, and typically its own SKU and stock level. Shared variant options (v3) can be assigned directly to individual products or to multiple products.

          • Modifier options (v3) are essentially the same as non-required options in v2. These are the user-facing customization options that do not require inventory tracking or SKUs. They can be displayed by multiple choice, pick lists, or other fields like checkboxes, date fields, text fields, or file uploads. Shared modifier options can be assigned directly to individual products or to multiple products.

          • Rules provide a means of altering product information, such as price, weight, or displayed image, depending on which value-combination or SKU a customer selects.

        Preparing for the Catalog v2 to v3 API Migration

        To complete the migration process, you must remove all v2 product options and apply v3 variant or modifier options. If even one product has a v2 option, BigCommerce will block the upgrade from proceeding.

        To ensure a smooth migration process, plan ahead and ensure the following requirements are met:

            • Verify that all product options have SKUs. Note any options without SKUs, shared options, and non-required options. These options will not be migrated to v3 automatically and will require manual recreation.

            • Once confirmed that all options have SKUs, DO NOT update products until the migration process is complete. An export file will be created at the beginning of the project, and any changes made to the products after that will be overwritten.

            • Confirm no option sets are associated with products and no options present on products.

            • Confirm no Google Shopping fields are enabled for products or categories.

          Common Challenges Migrating Products from Catalog v2 to v3 API

          Product options are vital to any ecommerce store, as they enable customization by allowing customers to choose specific variations of a product, such as size or color.

          However, the process of migrating product options from v2 to v3 can be complex and certain challenges can arise, especially if you have a large number of products.

          Some of the challenges you may encounter when migrating product options include:

              1. Product options without SKUs and shared options will not migrate to v3. These options are erased from the v3 upload and are not retrievable.

                • Solution 1: Bulk apply SKUs before the upgrade.

                • Solution 2: Recreate the options as new variants in v3.

              Our team’s proprietary back-end script uses the v2 API to check all product options to determine which do not have a SKU assigned so that store owners do not need to review the list of products one by one. While SKUs will still need to be manually added for options that don’t have them, running this script will help determine the severity of the issue by showing how much of the catalog is affected.

                  1. Product options in v2 that were specifically ordered by size or style will become unsorted upon CSV upload of v2 product data. For example, a sandpaper product has different size (grit) values that are ordered by ascending size. If you create product options and then add different sizes, the product IDs will increase incrementally but the grit value will be lower.

                    • Solution: Drag-and-drop reordering in the v3 API regenerates incremental IDs in the appropriate order of size.

                  We’re Here to Help Make Your BigCommerce Catalog v2 to v3 API Migration Painless

                  Migrating from v2 to v3 can be challenging, especially when dealing with product option data. However, with careful planning and execution, and our expert guidance and support, you can ensure a smooth migration.

                  Ready to make the switch to BigCommerce Category API v3? Unsure if your store is ready to migrate? We’ve got you covered.

                  No matter your company’s size, industry, or business model, our team of BigCommerce-exclusive development experts will help make the transition to Catalog v3 a breeze. We’ll handle the entire migration process and any customization or integration needs you may need after the upgrade.

                  Send us a message or call us at (866) 901-4650 to discuss your needs today.

                    Sarah joined IntuitSolutions in 2022 as a Marketing Manager where she focuses on content creation, social media, and digital marketing. In her free time, she loves to travel, study a new language, and explore nature around her.

                    Related Post

                    Olark Widget Preloader