Creating product modifiers

Use a product modifier import when you want to add customisation choices or inputs to BigCommerce products in bulk.

You can download a minimal product modifier creation example and use it as a starting point.

Required fields

To create a product modifier, leave the Modifier ID column blank on the Basic sheet and provide these fields:

Field	Example value	Notes
Product ID	103	Either Product ID or Product SKU is required.
Product SKU	CLC	Either Product ID or Product SKU is required.
Display Name	Engraving	The label shown on the storefront. This also links rows across the Basic, Option Values, and Config sheets.
Type	text	The modifier type, such as text, dropdown, swatch, product_list, or product_list_with_images.

You can also include Required and Sort Order on the same row.

info

If creating a modifier fails with an error saying an option with that label already exists, check the product's existing product options as well as its modifiers. BigCommerce product options are used for variant choices, but their labels can still clash with product modifier Display Names. For example, a variant option called Free Gift can prevent creating a product modifier with the Display Name Free Gift. Use a different modifier Display Name, or rename the existing product option if that is appropriate.

Add values

Choice-based modifier types need rows on the Option Values sheet. Link each value row to its parent modifier with the same Product ID or Product SKU and Display Name used on the Basic sheet.

Field	Example value	Notes
Product Modifier Product SKU	CLC	Matches the product from the Basic sheet.
Product Modifier Display Name	Engraving Fill Color	Matches the modifier Display Name from the Basic sheet.
Label	Black	The value shown on the storefront.
Sort Order	2	Values are shown in ascending order.
Value Data	{"colors":["#222222"]}	Required for some value types, such as swatches and product picklists.

For product picklists, use {"product_id":81} in Value Data. For swatches, use colour hexes such as {"colors":["#222222"]}.

tip

Leave the option value ID blank when creating a new value. BigCommerce will create the ID during import.

Add config

Use the Config sheet when a modifier type has extra settings, such as text length limits, file upload limits, checkbox labels, number ranges, date ranges, or product-list pricing and shipping behaviour.

For a simple text modifier, config is optional. For example, an engraving field can be created from the Basic sheet alone, then you can add text limits on the Config sheet if needed.

info

Price and weight adjustments belong to option values. Text-style modifiers such as engraving text fields cannot have adjustment rules, so use a value-based modifier such as a dropdown or rectangles list if the customisation needs to change price or weight.

Choose fields by modifier type

Different modifier types use different combinations of the Basic, Option Values, and Config sheets.

Dropdown, radio buttons, and rectangles

Use these types when the shopper chooses one value from a list.

Sheet	Required fields	Notes
Basic	Product ID or Product SKU, Display Name, Type	Type can be dropdown, radio_buttons, or rectangles.
Option Values	Product Modifier Display Name, Label	Add one row for each value. Use Sort Order to control the display order.
Config	None	Config is not usually needed for these types.

Checkbox

Use a checkbox when the shopper turns a single yes/no choice on or off.

Sheet	Relevant fields	Notes
Basic	Product ID or Product SKU, Display Name, Type	Type is checkbox.
Option Values	Label, Value Data	Use {"checked_value":true} and {"checked_value":false} to map the checked and unchecked values.
Config	Config Checkbox Label, Config Checked By Default	Use these when you want to control the checkbox label or whether it starts selected.

Swatch

Use a swatch when each value should display one or more colour chips.

Sheet	Required fields	Notes
Basic	Product ID or Product SKU, Display Name, Type	Type is swatch.
Option Values	Product Modifier Display Name, Label, Value Data	Value Data must include colours, e.g. {"colors":["#222222"]}.
Config	None	Config is not usually needed for swatches.

Product picklist

Use a product picklist when each value represents another BigCommerce product.

Sheet	Required fields	Notes
Basic	Product ID or Product SKU, Display Name, Type	Use product_list for a Picklist, or product_list_with_images when Show product image on storefront should be selected.
Option Values	Product Modifier Display Name, Label, Value Data	Value Data must include the linked product ID, e.g. {"product_id":81}.
Config	Config Product List Adjusts Inventory, Config Product List Adjusts Pricing, Config Product List Shipping Calc	Use these fields when the selected product should affect inventory, pricing, or shipping calculations.

The option value Label can be the product name, but it does not have to be. You can use a shorter storefront-friendly label as long as Value Data contains the correct product ID.

Text and multi-line text

Use text modifiers when the shopper enters custom text, such as engraving copy.

Sheet	Relevant fields	Notes
Basic	Product ID or Product SKU, Display Name, Type	Type can be text or multi_line_text.
Option Values	None	Text modifiers do not use option values.
Config	Config Default Value, Config Text Characters Limited, Config Text Min Length, Config Text Max Length, Config Text Lines Limited, Config Text Max Lines	Use character fields for text limits. Use line fields for multi_line_text.

File upload

Use file modifiers when the shopper uploads a file.

Sheet	Relevant fields	Notes
Basic	Product ID or Product SKU, Display Name, Type	Type is file.
Option Values	None	File modifiers do not use option values.
Config	Config File Types, Config File Types Supported, Config File Types Other, Config File Max Size	Use these to limit accepted file types and maximum upload size.

Import the file

1. Choose Product Modifiers in Shift.
2. Start a new import.
3. Upload your product modifier spreadsheet.
4. Map the columns to the matching product modifier fields.
5. Validate the import.
6. Start the import once validation passes.

For all supported product modifier columns, see the Product modifiers template.