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

After you’ve become accustomed to importing simple products, you’re ready to start adding more complicated attributes to your CSV file. In this chapter, we’ll walk you through the prerequisites and instructions for creating variants, images, videos, and custom fields.

In addition to the general requirements for product import, each complex attribute has its own prerequisites. Click the links in the list below to learn more about attribute-specific requirements:

• Variant requirements
• Image requirements
• Video requirements
• Custom field requirements

Variant Requirements

• When creating product variants via CSV import, you must include the following fields:
  • Item
  • ID
  • SKU
  • Options
  • Type (required for the base product, but must be left blank for variants)
  • Name
  • Price
  • Weight (physical products only)
• You must leave the ID fields blank when creating new variants.
• Each product can have a maximum of 600 variants.
• A swatch variant option value can have up to three colors assigned to it.
• You must use a publicly available image URL when assigning swatch pattern images.
  • Pattern image file types must be JPEG/JPG, GIF, WebP, or PNG.
• Pick lists created via CSV import are variant options, not modifier options.
• Only simple products (products without variant or modifier options) can be included in a pick list.
• Shoppers can only select one value at a time in a particular option; multiple values cannot be selected from the same option.
• New variants cannot be added or deleted to a product with existing variants via CSV import.
• Modifiers cannot be created via CSV import.
• Shared variant options cannot be assigned to products via CSV import.

Image Requirements

• When adding new images to products, you must include the following fields:
  • Item
  • ID (required, but must be left blank)
  • Image URL (Import)
• The "Image is Thumbnail" field is not required, but must either be filled in or removed from the CSV file to successfully import new images.
• The image URL can have a maximum of 1,024 characters.
• Images must be hosted and have a referenceable URL. Non-HTTP/HTTPS URLs are not supported.
  • If you are hosting your images in WebDAV, you must use the full URL path, not the WebDAV file name.
• Image file types must be JPEG/JPG, GIF, WebP, or PNG. They cannot be TIFF, BMP, or PDF file formats.
• 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.
• The maximum file size for product images is 8 MB.
• Only one image can be added per variant.

Video Requirements

• When adding new videos to products, you must include the following fields:
  • Item
  • ID (required, but must be left blank)
  • YouTube ID
• Only YouTube videos are supported.
• Videos cannot be added to variants.

Custom Field Requirements

• Each product can have a maximum of 200 custom fields.
• Custom field names and values each have a maximum character limit of 250.
• When adding new custom fields, do not include an ID. If you include an existing custom field ID when adding a new custom field to an existing product in your CSV file, the existing custom field will be updated upon import instead of creating a new custom field.
• You must use straight quotes (" ") instead of curly quotes (“ ”) to wrap your custom field elements.
  • If your spreadsheet program automatically converts straight quotes to smart quotes, you will need to update your program’s preferences to use straight quotes by default.
• When adding quotation marks (" ") to custom field values, you must use the HTML character code (") in order to prevent import errors. All other special characters can be entered normally.
  • Example [{"name":Color,"value":""Blue""}]
• Newline characters are not supported in custom fields.

Our CSV importer allows you to import product variants in addition to simple products. To create variant options, you will need to add variant rows under your product and format the variant information for each combination of options.

We recommend creating the base products first, exporting them to a new CSV file, adding the variant rows, then re-importing to update your products with variants. Additionally, you can see examples of products with variants in our sample template.

Adding Rows for Variants

To create a new variant option for an existing product using a CSV, you first need to export the products that will be using it. You should make a backup copy of your export file in case you need to revert the product back.

In your spreadsheet program, open your exported CSV file and 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:

• Current Stock (if tracking inventory on the variant level)
• Low Stock (if tracking inventory on the variant level)
• Cost Price
• Retail Price
• Sale Price
• Free Shipping
• Fixed Shipping Cost
• Width
• Height
• Depth
• Variant Image URL

When you are done making changes, save your file and re-import it back into your store.

Formatting Variant Options for Import

To specify which type of variant option you are importing, you will need to format the Options column of your new variant row, using the formulas below. For details on importing pick lists as variant options, see Formatting Variant Pick Lists.

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

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

If a single SKU has multiple options, you can list them directly after each other or on separate lines in the cell when formatting. For example, for a SKU variant that is blue color and medium size, the Options column would look like:

Type=Swatch|Name=Color|Value=Blue[#0000FF]Type=Radio|Name=Size|Value=M

or:

Type=Swatch|Name=Color|Value=Blue[#0000FF]
Type=Radio|Name=Size|Value=M

Formatting Variant Pick Lists

Pick lists created via CSV import are variant options instead of modifier options, which have the following differences:

• Variant pick lists cannot be created in the control panel; only via CSV import or an API request. However, existing variant pick lists can be edited in the control panel.
• Like all variant options, variant pick lists are required for the shopper, meaning they must select a product from the list.
• Each pick list variant option will generate a unique SKU in combination with other variant options.
  • For example, if you create a product with 5 size options and 4 pick list options, the product will have 20 variants, each with a unique SKU.

Pick list options use the following format:

Type=PicklistWithImages|Name=Name|Config=[AdjustsInventory=FALSE;AdjustsPricing=FALSE;ShippingCalc=none]|Value=Product Name[ProductID=#]

Edit each element of the pick list option to configure your desired pick list settings. Note that the bolded elements are case-sensitive.

• Type — enter one of the following pick list types:
  • Picklist — displays each pick list product in a radio button list on the storefront product display page
  • PicklistWithImages — displays each pick list product with their thumbnail image in a radio button list on the storefront product display page
• Name — the name of the pick list that is visible on the storefront product display page
• Config — consists of the following configuration elements. The Config selections of each value in a pick list option must match.
  • AdjustsInventory — enter TRUE to update the stock of the pick list product when selected and ordered, or FALSE to not track inventory
  • AdjustsPricing — enter TRUE to add the selected pick list product’s price to the base product, or FALSE if you want to set a custom price for the variant
  • ShippingCalc — enter one of the following values:
    • none — the selected product will not adjust the base product’s weight or package dimensions (length, width, and/or height)
    • package — the selected pick list product’s dimensions will be added to the base product’s package dimensions
    • weight — the selected pick list product’s weight will be added to the base product’s weight
• Value — enter the product name you want to display in the pick list, which can be different from the product’s name in your catalog. Add the pick list product’s ID in brackets.

In the example below, we’ve added three new rows to create a pick list for our product, a shirt with accessories.

In your CSV file, you can add images to your products by adding a row under the corresponding product and entering the image information. As the fastest way to assign product images, importing allows you to specify a sort order and designate the thumbnail image, giving you control over how product images are presented to shoppers. Images can be added to base products, or to individual variants.

Adding Images to Products

To add product images via CSV, you first need to export your products or use our sample template to create new products. In your spreadsheet program, open your exported CSV file and add a row directly under the product that will have the new image. To upload multiple images for a single product, create a new row beneath the Product row for each image.

In the new row, format the following columns:

In the Image URL (Import) column, enter the full path (such as https://cdn.bigcommercestore.com/images/product-image.png) of the image for each product.

When you are ready, import your products to add images.

Adding Images to Variants

Each product variant can have one image associated with it. This image appears on the storefront product display page when a shopper selects the option values that correspond to the variant.

Unlike base product images, variant images are added to the Variant row instead of creating a new Image row. After you’ve added your variant information to your CSV file, locate the Variant Image URL column and paste the full URL path of your image on your variant’s row.

Since only one image can be added per variant, there is no need to specify its sort order. Additionally, image descriptions are not supported on variant images. When you’ve added your images to their corresponding variant rows, import your CSV file in the control panel.

With our CSV importer, you can add YouTube videos to your products, along with video titles, descriptions, and apply a sort order. Note that videos cannot be added to variants.

To add YouTube videos to your products via CSV, open your CSV file in your preferred spreadsheet program and add a row directly under the product that will contain the new YouTube video. Remember to leave the ID field empty.

In the new row, format the following columns:

When you are ready, import your products to add YouTube videos.

Our CSV importer allows you to create and update custom fields on your products in bulk. In your spreadsheet app, open your exported CSV file and locate the product that you want to add custom fields to. Enter your custom fields in the Custom Fields column of the product row.

Your custom fields must be entered in the following format to ensure they import successfully.

Each custom field must be wrapped in curly brackets { }. If you are adding multiple custom fields to a product, separate each name-value pairing with a comma within the square brackets [ ]. When you are ready, import your products to create their custom fields.

Now that you’re familiar with the different item types that can be created via import, you’re ready to add your catalog 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 format 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 one BigCommerce store to another

Entering Product Data Manually

If you’re a brick-and-mortar store entering into ecommerce with a wide variety of products, you may need to enter all of your product information from scratch in order to import it. See the list below for helpful tips to keep in mind as you add 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 field and formatting requirements you need to keep track of at a time.
• 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.
  • Alternatively, you can create shared variant options and apply them to your products in the control panel after the initial import.
• If you don’t want to gather your category IDs to assign products to categories via import, you can assign products to categories in bulk from the control panel.

Converting a Catalog Spreadsheet

If you receive product information from a supplier or distributor as a digital spreadsheet, you can reformat the source file so that it can be imported successfully into your BigCommerce store.

• 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 column to the spreadsheet and specify the item type (Product, Variant, Image, Video) for each row.
• Compare the spreadsheet’s column headers to the ones present in the sample template.
  • For information that corresponds to an importable field, edit the column header name to match that field. The spelling and casing must match in order to prevent import errors.
  • 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 any variant, image, or video information into its own row under the associated product.
• Make sure that the information in each field is formatted correctly. Use the information in this chapter for formatting complex attributes, and see our Table of Supported 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 export your catalog as a CSV file and reformat the information to import 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

There are several reasons you might want to transfer the contents of an existing BigCommerce store to a new one, such as:

• Moving data from a pre-launch environment (sandbox store) to a production environment (live store)
• Duplicating content to another store to test design changes or customizations
• Cloning store data for use on another storefront

Depending on the Import/Export experience of each store, there are different steps you will need to take to ensure the import is successful. See the following chapters to learn more:

• Transferring Products from One Modern Import Store to Another
• Transferring Products from a Legacy Import Store to a Modern Import Store