Product modifiers template

Create and update BigCommerce product modifiers using Shift.

Product modifiers are used when a shopper can customise a product without changing which product variant is fulfilled. Examples include engraving text, gift wrap, insurance, file uploads, swatches, and product add-ons.

tip

Check out our step-by-step guides for how to import & export.

Quick start

The best way to get started is to run an export and use the file as a guide to the format required.

If you are creating product modifiers, follow the creating product modifiers guide or download the minimal product modifier creation example.

To see the fields included on export, download the full product modifiers export example.

Product modifier imports use three sheets:

• Basic - one row per modifier.
• Option Values - one row per value for choice-based modifiers such as dropdowns, rectangles, swatches, and product lists.
• Config - one row per modifier for type-specific settings such as text limits, checkbox labels, file limits, date limits, number limits, and product-list behaviour.

Exports may only contain the sheets selected during export, so an export without config fields might only include Basic and Option Values.

Import & export columns

Basic sheet

Fields	Description
Mode	The import mode for this row. See import modes for more information.
Modifier ID	The unique identifier provided by BigCommerce for an existing product modifier. This field is required to update or delete an existing modifier when you are not matching by display name.
Product ID	The unique identifier for the product that the modifier is attached to. Either Product ID or Product SKU is required.
Product SKU	The SKU for the product that the modifier is attached to. Either Product ID or Product SKU is required.
Name	The unique internal modifier name generated by BigCommerce. 🔒 This field is read-only. Use Display Name when creating or matching modifiers.
Display Name	The storefront label for the modifier, e.g. Engraving, Include Insurance?, or Gift Wrap. Display Name is also used as a secondary key to match a modifier to its option values and config rows when creating new modifiers.
Type	How the modifier is displayed or collected on the storefront. Allowed values are: date, checkbox, file, text, multi_line_text, numbers_only_text, radio_buttons, rectangles, dropdown, product_list, product_list_with_images, and swatch.
Shared	Whether the modifier is based on a shared modifier. 🔒 This field is read-only.
Required	Whether the shopper must complete the modifier before adding the product to cart. Allowed values: Yes, No, 1, 0, True, False.
Sort Order	Product modifiers are ordered ascending by this numeric field.

info

product_list and product_list_with_images are both BigCommerce Picklist modifier types. Use product_list_with_images when the BigCommerce admin option Show product image on storefront should be selected.

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.

Option Values sheet

Choice-based modifier types can have one or more option values. For example, an Include Insurance? dropdown could have values of Yes and No.

Text, multi-line text, numbers-only text, date, and file modifiers do not use option values.

Fields	Description
Product Modifier Modifier ID	The parent Modifier ID. Use this to attach the value to an existing modifier.
Product Modifier Product ID	The parent product ID. Used with Product Modifier Display Name when Modifier ID is not available.
Product Modifier Product SKU	The parent product SKU. Used with Product Modifier Display Name when Modifier ID is not available.
Product Modifier Display Name	The parent modifier Display Name. This is important when creating new modifiers because it links new option value rows to the matching modifier row in the Basic sheet.
ID	The unique identifier for the modifier option value. This field is required to update or delete an existing option value.
Label	The storefront label for the option value, e.g. Yes, No, Red, Small, or Product with engraving.
Is Default	Whether the option value is selected by default. This is not supported for swatch modifiers. Allowed values: Yes, No, 1, 0, True, False.
Sort Order	Modifier option values are ordered ascending by this numeric field.
Price Adjustment Type	How the value changes the product price. Allowed values are: relative, percentage.
Price Adjustment Value	The amount used by Price Adjustment Type.
Weight Adjustment Type	How the value changes the product weight. Allowed values are: relative, percentage.
Weight Adjustment Value	The amount used by Weight Adjustment Type.
Value Data	JSON data required by some modifier types. For product lists, use a product ID, e.g. {"product_id":81}. For swatches, use colour hexes, e.g. {"colors":["#BABBA8"]}. For checkboxes, use the checked state, e.g. {"checked_value":true}.

info

Price and weight adjustment rules apply to modifier values. Text-style modifiers such as engraving text fields cannot have adjustment rules. If a text customisation needs to change price or weight, model that choice with a value-based modifier such as a dropdown or rectangles list.

Adding an option value

To add a new value to an existing modifier, add a new row to the Option Values sheet and link it to the parent modifier using the parent Modifier ID, Product ID or Product SKU, and Display Name. Leave the option value ID blank so BigCommerce creates a new value.

For example, to add a Black value to an existing Engraving Fill Color swatch:

Product Modifier Modifier ID	Product Modifier Product SKU	Product Modifier Display Name	ID	Label	Is Default	Sort Order	Price Adjustment Type	Price Adjustment Value	Value Data
192	CLC	Engraving Fill Color		Black	No	2	relative	14.99	{"colors":["#222222"]}

Config sheet

Config columns are used for type-specific modifier settings. Fill in only the columns that apply to the modifier type.

Fields	Description
Product Modifier Modifier ID	The parent Modifier ID. Use this to attach config to an existing modifier.
Product Modifier Product ID	The parent product ID. Used with Product Modifier Display Name when Modifier ID is not available.
Product Modifier Product SKU	The parent product SKU. Used with Product Modifier Display Name when Modifier ID is not available.
Product Modifier Display Name	The parent modifier Display Name. This links config rows to the matching modifier row in the Basic sheet when creating new modifiers.
Config Default Value	Default value for date, text, multi_line_text, and numbers_only_text modifiers. Date values must use ISO-8601 ATOM format.
Config Checked By Default	For checkbox modifiers, whether the checkbox is checked by default. Allowed values: Yes, No, 1, 0, True, False.
Config Checkbox Label	For checkbox modifiers, the label shown next to the checkbox.
Config Date Limited	For date modifiers, whether the selectable dates are limited.
Config Date Limit Type	For date modifiers, the type of date limit. Allowed values are: earliest, range, latest.
Config Date Earliest Value	For date modifiers, the earliest selectable date.
Config Date Latest Value	For date modifiers, the latest selectable date.
Config File Types	For file modifiers, whether all file types or specific file types are allowed. Allowed values are: all, specific.
Config File Types Supported	For file modifiers, a JSON array of supported file groups, e.g. ["images"] or ["images","documents"].
Config File Types Other	For file modifiers, a JSON array of custom file extensions.
Config File Max Size	For file modifiers, the maximum upload size in KB. BigCommerce's maximum is 524288.
Config Text Characters Limited	For text and multi_line_text modifiers, whether the character count is limited.
Config Text Min Length	For text and multi_line_text modifiers, the minimum character count.
Config Text Max Length	For text and multi_line_text modifiers, the maximum character count.
Config Text Lines Limited	For multi_line_text modifiers, whether the number of lines is limited.
Config Text Max Lines	For multi_line_text modifiers, the maximum number of lines.
Config Number Limited	For numbers_only_text modifiers, whether the entered number is limited.
Config Number Limit Type	For numbers_only_text modifiers, the type of number limit. Allowed values are: lowest, range, highest.
Config Number Lowest Value	For numbers_only_text modifiers, the minimum allowed number.
Config Number Highest Value	For numbers_only_text modifiers, the maximum allowed number.
Config Number Integers Only	For numbers_only_text modifiers, whether only whole numbers are allowed.
Config Product List Adjusts Inventory	For product_list and product_list_with_images modifiers, whether selecting and purchasing a listed product adjusts that listed product's inventory.
Config Product List Adjusts Pricing	For product_list and product_list_with_images modifiers, whether selecting a listed product adds that product's price to the main product price.
Config Product List Shipping Calc	For product_list and product_list_with_images modifiers, how the selected product affects shipping calculations. Allowed values are: none, weight, and package.

info

Config values are used when creating new modifiers. To change config for an existing modifier, update it in BigCommerce and run a fresh export before making further changes in Shift.

Supported actions

Shift supports:

• Creating, updating, and deleting product modifiers.
• Creating, updating, and deleting modifier option values.
• Creating modifiers with type-specific config.

Shift does not support:

• Importing modifier value images. The adjusters.image_url field is not included in the template.
• Updating config fields on existing modifiers.

Import modes

Use Import modes to control the import behaviour.

The Mode column on import is used to determine what kind of update action is performed for each modifier row.

Mode	Action
Merge	Existing items are updated. New items are created. Missing columns or empty column values are ignored. This is the default mode.
Update	Existing items are updated. New items are ignored. Missing columns or empty column values are ignored
Create	New items are created. Existing items are ignored.
Replace	Existing items are deleted and recreated. New items are created. This is the same as a Delete followed by a Merge.
Delete	Existing items are deleted.
Skip	This item is ignored

Export filters

You can filter modifiers that are exported by choosing to export modifiers for products that match one of the following filters:

• ID
• Brand
• Categories
• Purchasability
• Condition
• Date Updated
• Is Visible
• Keyword
• Name

tip

As you reduce the number of items in your export, or change what data should be included, the estimate of the number of records and duration of the export will be updated.

info

An accurate estimate for product modifiers cannot be provided so only an indication is given.