Importing Product Options (v3)
In addition to creating them in the control panel, you can create and update variant options for your products by importing a CSV file. This can be a faster alternative to entering products one-at-a-time in the control panel if you have a large number of products with options that you need to update.
Rules for both variant options and modifiers can also be created and updated using import. However, modifier options themselves cannot be created or updated using import; those must be created in the control panel.
This article covers the standard experience for importing and exporting product options. See Importing Complex Attributes for information on the modern import experience.
Product Option Import/Export (v3)
This article covers the product option import functionality for stores using the new Add Products control panel experience which uses our Catalog v3 API. If you have an older store and are using the v2 experience, see Importing Product Options (v2).
Supported Variant Options
The following variant options can be created in the v3 catalog through a CSV import:
- Multiple Choice
- Swatch
Adding Rows for Options and Rules
To create a new option or rule for an existing product using a CSV, you first need to export the products that will be using it. Use the Bulk Edit export template. You should make a backup copy of your export file in case you need to revert the product back. For full instructions on how to export products, see Importing and Exporting Products.
In your spreadsheet app, open your exported CSV file and add a row directly under the product that will have the new option or rule.
In the new row, format the following columns:
Column Name | Format |
Item Type | Use SKU to create variant options. You will use a SKU Item Type row to define or change a variant's:
|
Product ID | This value is automatically assigned by BigCommerce and should be left blank when creating new variant options. |
Product Name | This field should be formatted using option or rule markup. See Formatting Variant Options and Formatting Rules below to see how. |
Product Code/SKU | The unique product code that identifies this variant. |
Using the Option Set and Option Set Align fields can cause duplicated variants upon import. Delete these columns from your CSV before importing, or create a custom export template that excludes them.
When you are done making changes, save your file (keep the CSV format) 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 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]Size=Small | |
Rectangle List | [RT]OptionName=Value | [RT]Size=Small | |
Swatch | Color | [CS]OptionName=Value:#hexcode | [CS]Color=Blue:#0000FF |
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.
Note:
- The Product Name of an existing option cannot be updated via CSV. Changing an option's name in your CSV will result in a new option being created upon import. Update option names in the control panel or via the API.
- If a single SKU has multiple options, separate them with a comma when formatting. For example, for a SKU 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 to the product_images/import folder using WebDAV. The file name and URL in the CSV must match exactly.
Formatting Rules for Import
To create a rule for a variant or modifier option via CSV import, you’ll need to format the appropriate column using the formulas in the table below. In a CSV file, rule rows appear beneath any SKU rows a product may have.
Rule Type | Column | Action | Format | Example |
Adjust Price | Price | Add an amount | [ADD]# | [ADD]5 |
Remove an amount | [REMOVE]# | [REMOVE]30% | ||
Set a fixed amount* *Not compatible with [FIXED] modifier rules. | [FIXED]# | [FIXED]15 | ||
Adjust Weight | Product Weight | Add an amount | [ADD]# | [ADD]3 |
Remove an amount | [REMOVE]# | [REMOVE]5 | ||
Set a fixed amount* *Not compatible with [FIXED] modifier rules. | [FIXED]# | [FIXED]10 | ||
Show a Different Image | Product Image File - 1 | Show this image |
Full image URL OR |
http://mybcstore.com/product_images/import/filename.jpg filename.jpg * Image file must already be online or uploaded to your product_images/import folder before import. * The file name can only be used for image files uploaded to your product_images/import folder. |
Make Unavailable for Purchase | Allow Purchases | Don’t allow purchases | N | |
Allow purchases | Y | |||
Stop Processing Rules | Stop Processing Rules | Stop processing rules | Y |
Rules are associated to variants using the variant’s Product Code/SKU.
In our example spreadsheet below, we’ve added a rule to say our large mug variant has a price of $25, and a weight of 0.7 lbs. Note that the Product Code/SKU for the rule matches the Product Code/SKU of the variant we are creating the rule for.
On the storefront, we can see the price and weight update when the large variant is selected.
Note:
- For Price, use #% to calculate a percentage instead of a fixed amount.
- Image URLs must link to file that is online and publicly accessible. Supported file types are JPEG/JPG, GIF, WebP, and PNG.
Sale prices and MSRPs on products with v3 variants cannot be imported with CSV. See Using Sale Pricing for instructions on how to set sale prices for these products.
Below is an example of how you would add a price change rule for a modifier option using an import.
In the control panel, we’ve already created a modifier option that is a checkbox named Add engraving?.
In our CSV spreadsheet, we’ve added a new rule row to our spreadsheet to add $5 to the price when that box is checked (our checked value is Yes).
Note that the modifier option itself is not represented in CSV imports/exports, only its associated rules. Modifier options cannot be created or updated using an import.
After importing, the new rule appears on the storefront:
It also now appears under Customizations › Rules when editing the product in the control panel.
FAQ
Is it possible to import shared variants in bulk in a CSV file?
No, shared variants cannot be imported with CSV.
Can I have duplicate names/SKUS for products?
No. Product option imports are subject to the same requirements as product imports.
Can I change the option type of existing variant options using CSV import?
No, editing an existing option's type in the CSV will not change the option type when imported. You can edit the option type in the control panel or via the API.