Legacy Product Import/Export | Importing Variants, Images, and Other Complex Attributes

Certain product attributes, such as variants and images, have multiple CSV fields with unique formatting requirements. In this chapter, we’ll walk you through the prerequisites and instructions for adding these attributes to your base products.

In addition to the general requirements for product import, there are specific prerequisites for each complex attribute. Note that products will need to meet all of the applicable requirements for them to be imported correctly. For example, a product with variants, images, and digital files must meet all three attribute-specific requirements, as well as the general requirements, in order to import successfully.

• Variant requirements
• Image requirements
• Digital file requirements
• Category requirements

Variant Requirements

• Product variant rows must be created directly under the corresponding base product row in order to successfully create variants via import.
• In addition to the fields required for importing base products, you must include the following fields when creating product variants via CSV import:
  • Item Type
  • Product Name
  • Product Code/SKU
• You must leave the Product ID fields blank when creating new variants.
• Product variants are arranged in SKU and Rule Item Types. Each Item Type supports the following variant attributes:

• To prevent import errors, you must delete the Option Set and Option Set Align fields from your CSV file before importing, or create a custom export template that excludes them.
• If a single variant has multiple options, separate them in the Product Name column with a comma when formatting. For example, for a variant that is small size and blue color, the Product Name column would look like [RB]Size=Small,[CS]Color=Blue:#0000FF.
• Swatch options require a color hex code for colors and a URL for patterns.
• Image files for pattern type swatches should be uploaded using WebDAV to the product_images/import folder. The file name and URL in the CSV must match exactly.
  • The maximum file size for swatch images is 8 MB.
• Each product can have a maximum of 600 variants.

Image Requirements

• The maximum file size for product and variant images is 8 MB.
• In addition to the fields required for importing base products, you must include the Product Image File field when adding product images via CSV import.
• You must leave the Product Image ID fields blank when creating new images.
• Image URLs must link to a file that is online and publicly accessible. Supported file types are JPEG/JPG, GIF, WebP, and PNG.
  • Non-HTTP/HTTPS image URLs are not supported.
• Use a full image URL or the file name of an image previously uploaded into the product_images/import folder of WebDAV.
  • If you've created a subfolder in product_images/import and added images to it, you must include that folder's subdirectory with the file name (like folder_name/image.png).
• Image file names are restricted to a-z, 0-9, - and _. They cannot contain any spaces or special characters.
• Image file names and URLs can have a maximum length of 1,024 characters.
• The optimal size for your product images is 1280 x 1280 pixels. Other product images (like thumbnails) will be created from the original image you upload.
• A base product can have a maximum of 1,000 images.
• Only one image can be added per variant.

Digital File Requirements

• In addition to the fields required for importing base products, you must include the Product File field when adding digital files via CSV import.
• If you’re importing digital files from WebDAV, you must add them to the product_downloads/import folder, and you must use the file name and extension in the Product File field, such as filename.pdf.
• If you’re importing digital files with a URL, the file you link to must be publicly accessible.
  • Non-HTTP/HTTPS file URLs are not supported.
• The maximum size for digital products is 512 MB.

Category Requirements

• Use semicolons (;) to separate the different categories that a product is assigned to.
• Use forward slashes (/) to denote a category-subcategory relationship (like Parent Category/Subcategory).
• A product can be assigned to a maximum of 1,000 categories.
• Your store can have a maximum of 16,000 categories.
• A category name can have a maximum of 50 characters.

Importing your variants allows you to add options, such as size or color variations, to your product in bulk. To create variant options, you will need to add SKU rows under your product, format the variant information for each combination of options, and include rules that define the changes to be made to the base product whenever the variant is selected.

We recommend creating base products first, exporting them to a new CSV file, adding variant attributes, then re-importing to update your products with variants. It can also be helpful to create a product with variants in the control panel, and then export it as a template for formatting additional variants.

Adding SKU Rows for Variants

Once you’ve either exported base products from your store or created them in a separate CSV file, add a row directly under the product that will have the new variant.

In the new row, add your variant information to the following columns:

In addition to the fields above, you can optionally add variant information to the following fields:

Repeat this process to add SKU rows under the products you want to create variants for, and then proceed to the next section to configure the variant option information.

Formatting Variant Options

To specify which type of variant option you are importing, you will need to format the Product Name column of your new SKU row, using the formulas below.

Option	Type	Format	Example
Multiple Choice	Radio Button	[RB]OptionName=Value	[RB]Size=Small
	Dropdown	[S]OptionName=Value	[S]Flavor=Vanilla
	Rectangle List	[RT]OptionName=Value	[RT]Cut=Square
Swatch	Color	[CS]OptionName=Value:#hexcode	[CS]Color=Blue:#0000FF
	Multiple Colors (up to three)	[CS]OptionName=Value:#hexcode1|#hexcode2	[CS]Color=Blue-Red:#0000FF|#E60C0C
	Pattern	[CS]OptionName=Value:URL	[CS]Pattern=Plaid:http://mybcstore.com/ product_images/import/ plaid.jpg

In the example below, we’ve added three new rows to add size variations to our product.

After re-importing, our variant options now show on the product detail page on the storefront.

If a single variant has multiple options assigned to it, separate them with a comma when formatting. For example, a variant that is small size and blue color, the Product Name column would look like [RB]Size=Small,[CS]Color=Blue:#0000FF.

Formatting Rules for Import

After adding SKU rows and configuring variant options in your CSV file, you can add rules to specify the behavior of your variants. This allows you to adjust attributes like price, weight, or display an image when a shopper selects the variant on your storefront product page.

To create a variant rule, add a row under the SKU rows of the product in question. Give this row an item type of Rule, and associate the rule to its corresponding variant by adding the variant’s SKU to the rule’s Product Code/SKU field. Make sure to leave the Product ID and Product Name fields blank.

Using the table below, format the fields in the Rule row to specify variant behavior.

Rule Type	Column	Action	Format	Example
Adjust Price	Price	Add a flat or percentage amount to the base product’s price	[ADD]#	[ADD]5 OR [ADD]25%
		Remove a flat or percentage amount from the base product’s price	[REMOVE]#	[REMOVE]5 OR [REMOVE]25%
		Set a fixed variant price	[FIXED]#	[FIXED]25
Adjust Weight	Product Weight	Add a flat amount to the base product’s weight	[ADD]#	[ADD]3
		Remove a flat amount from the base product’s weight	[REMOVE]#	[REMOVE]5
		Set a fixed variant weight	[FIXED]#	[FIXED]10
Show a Different Image*	Product Image File - 1	Show this image	Full image URL OR Image file name	http://mybcstore.com/product_images/import/filename.jpg OR filename.jpg
Make Unavailable for Purchase	Allow Purchases	Don’t allow purchases	N
		Allow purchases	Y
Stop Processing Rules	Stop Processing Rules	Don’t apply any rules to the variant in question that were placed below this row	Y

* Variant images must meet the same requirements for importing product images.

In our example spreadsheet below, we’ve added a rule to give our medium mug variant a price of $25 and a weight of 0.7 lbs.

On the storefront, we can see the price and weight update when the medium variant is selected.

Including product images in your product import is the fastest way to attach images to your products. This can be accomplished in one of two ways:

• If the images are already available on the internet and you know the URL, you can import them using the image path in the CSV file.
• If the photos are on your computer, we recommend uploading them through WebDAV instead.

Using the Image Path

If your product images are already online, you can specify the full image path in your CSV file to import them along with your products. Locate the Product Image File - 1 column in your CSV file. When importing new images, you must leave the Product Image ID column blank.

Enter the full path (such as http://oldstore.com/images/product-image.png) of the image for each product on their respective CSV row. Non-HTTP/HTTPS URLs are not supported.

To upload multiple images for a single product, or to add new images to a product with existing images, create a new column with a heading of Product Image File - #, increasing the number each time you make a new column. To include any of the other information for that image, such as descriptions, make a new column with the appropriate heading and same number as the corresponding image.

For example, if you wanted to import a product with two images, you would create extra columns and label them:

• Product Image ID - 2
• Product Image File - 2
• Product Image Description - 2

Uploading Through WebDAV

With the upload method, you will upload images from your computer to your store using WebDAV, then specify the image by its file name in the CSV file.

Begin by connecting to your store through WebDAV. Open the product_images folder, followed by the import folder. From here, drag and drop the images from your computer into the folder.

In your CSV file, locate the Product Image File - 1 column. Enter the file name (such as image.png) of the image file. If you've created a subfolder in product_images/import and added images to it, you must include that folder's subdirectory with the file name (like folder_name/image.png). Be sure to leave the Product Image ID field blank.

As with adding multiple images via full path, you can add additional images by creating new columns for the attributes of each image, increasing the number each time you add a new image.

Additional Image Attributes

While adding images to your products, you can specify image details like sort order and alt tags in your CSV file. If you are using the sample template, or you’ve exported products with the Bulk Edit template, your CSV file will have the following image fields:

• Product Image ID — This must be left blank for new images.
• Product Image File — Use the image path or the WebDAV file name to import images.
• Product Image Description — The alt tag for the product image.
• Product Image Is Thumbnail — Use Y or N to indicate which image should be used as the product thumbnail. If you remove this column from your CSV file, the first image listed under the product is assigned as the thumbnail upon import. Only one image can be assigned as the thumbnail.
• Product Image Sort — Specify the order that images should appear in. Images are sorted from lowest to highest value. Use whole numbers only. If left blank, the field will be set to "0".

When creating digital products, you can assign downloadable files in bulk via CSV import. Before adding file information to your CSV, give your desired products a Product Type value of D to designate them as digital.

Locate the Product File - 1 column in your CSV file and add the digital file using one of the following methods:

• If your file has a publicly-accessible link, you can paste the full file path in the field, such as https://myoldstore.com/filename.pdf.
• If your file is on your computer, upload it to the product_downloads/import folder of WebDAV, then enter the file name and extension in the field, such as filename.pdf.

You can optionally include other details for the digital file in your CSV, such as:

• Product File Description — a description of the file that will appear in the invoice and in the customer's account when they download the file.
• Product File Max Downloads — the total number of times a customer can download the file. Use numbers only, or leave blank if you do not wish to limit the number of downloads.
• Product File Expires After — the period after which the download link will not work for your customer. This can be entered as # Days, # Weeks, # Months, # Years, or Never. If left blank, the download link will not have an expiration period.

As with product images, you can add multiple files to your product by creating new columns for each file, increasing the number each time you add a new file. For example, if you wanted to import a product with two files, you would create a second set of product file columns and label them:

• Product File - 2
• Product File Path - 2
• Product File Description - 2
• Product File Max Downloads - 2
• Product File Expires After - 2

The Category field must be present in your CSV file in order to create new products, although it can be left blank. To assign your products to an existing top-level, parent category, enter the category’s name in the Category field. This field is not case-sensitive, but the category name must be spelled correctly in order to avoid creating a new category by mistake.

If you want to assign a product to a subcategory, list both the parent category and the subcategory, separated by a forward slash (/). Note that the product won’t display in the parent category unless configured in your store’s category settings. For example, "Kitchen/Coffee" will add the product to the Coffee subcategory, but not the Kitchen category.

To assign products to multiple categories, enter each category name and separate them with a semicolon (;), without a space.

Creating New Categories via CSV Import

In addition to assigning products to existing categories, you can generate new categories via CSV import by entering the new category’s name in the field. You can also use this method to create new subcategories under existing parent categories, or to create new parent and subcategory groupings.

If you’re creating a new category with a slash (/) character in its name, use a backslash (\) before it to avoid creating subcategories. For example, if you want to create a category labeled "Sweaters/Hoodies", it should be formatted as Sweaters\/Hoodies to avoid creating parent and child categories.

Categories created via CSV import use the default URL structure in your Category URL settings. However, it is not possible to import other category attributes, such as description, category image, or SEO fields. This information must be added in the control panel, or via the API.

Now that you’re familiar with how to format products and their attributes for CSV import, you can apply this knowledge to add your catalog data to a CSV file and upload it in bulk. Depending on where you are gathering your product details from, there may be additional considerations to take into account as you adjust the data for import. Some common import scenarios include:

• Entering your product data manually
• Converting a catalog spreadsheet from a third-party distributor
• Migrating your catalog from another platform
• Migrating your catalog from an existing BigCommerce store

Entering Product Data Manually

If you don’t have an online source for your catalog data, such as a supplier spreadsheet or a CSV file from a previous store, you may need to enter all of your product information from scratch in order to import it. Review the following tips to help you with adding your products to a CSV file.

• When importing your catalog for the first time, it can be helpful to perform an initial import with the minimum required fields before adding additional product details and complex attributes. This reduces the amount of fields and formatting requirements you need to keep track of at a time.
  • After the initial import, you can also create a custom export template to streamline the fields in your CSV file as you make additional edits to your products.
• When writing product descriptions, entering them as plain text in the CSV file and styling them in the control panel can help you to avoid HTML formatting issues during import.
• If your products share a lot of variant options, such as size or color, you can create one product with all options in the control panel, then export it for easy reference when formatting other variant options in your CSV file.
  • You can also create shared variant options and apply them to your products in the control panel after the initial import. Note that shared options are only available in the v3 Products experience.
• If you don’t want to manually enter category names in your CSV file, you can assign products to categories in bulk from the control panel. Note that this method only allows you to assign products to existing categories.

Converting a Catalog Spreadsheet

If you receive a catalog data spreadsheet from a third-party source, such as a supplier or distributor, you can adjust the contents of your file to use the format of the Import/Export tool. We recommend taking the following measures to ensure a successful import:

• Make a copy of the original spreadsheet to ensure that you have a backup.
• Save the spreadsheet as a .csv file if it is using a different spreadsheet format.
• Add an Item Type column to the spreadsheet and specify the item type (Product, SKU, Rule) for each row.
• Compare the spreadsheet’s column headers to the ones present in the sample template.
  • If the information corresponds to an importable field, you can either edit the column header name to match that field, or manually match the column to the appropriate field while uploading your CSV file.
  • If the spreadsheet has an information column that doesn’t correspond to an importable field, remove that column to ensure your import is successful.
• Separate variant attributes into SKU rows and add variant rules as Rule rows.
• Make sure that the information in each field is formatted correctly. Use the information in this chapter for formatting complex attributes, and see Supported Product Fields for formatting information on all base product fields.
• If you are importing more than 1,000 images, consider breaking your CSV file into batches in order to avoid a stuck import.
  • If your products have images with larger dimensions or file sizes, consider optimizing them to reduce the import time and decrease the risk of the import stalling.

Migrating from Another Platform

If you’re moving to BigCommerce from a different ecommerce platform, you can migrate your catalog by exporting it from your original store, reformatting the product information in the CSV file, and importing it into your BigCommerce store. Learn more about migrating your products in our article on Transferring Your Catalog to BigCommerce, or see one of our platform-specific migration guides below:

• Migrating from Shopify
• Migrating from WooCommerce
• Migrating from Magento

Migrating from an Existing BigCommerce Store

If you want to transfer catalog data between multiple BigCommerce stores, such as from a pre-launch sandbox environment to your live store, you can export your products from the source store and import them into the destination store. Depending on the Import/Export experience of each store, there are different considerations and steps for migrating your products:

• If both stores use the legacy Import/Export experience, see our Guide to Transferring BigCommerce Store Data.
• If the source store uses the legacy experience and the destination store uses the modern experience, see Transferring Products from a Legacy Import Store to a Modern Import Store