Guide · Products import

Products

How to structure a spreadsheet that creates, updates or deletes products in BigCommerce — with variants, options, images, videos, custom fields, metafields, quantity breaks and modifiers all in the same file.

1. File structure

The import file is a standard CSV, or an .xlsx workbook. There is one system column: Command.

The Command column

This column decides what action to take for each product row.

2. Check the file before you run it

After uploading you get a Check file step. It reads the file only — nothing is sent to BigCommerce — and tells you:

• How many rows, and how many items. These differ: one product can span a row for itself, a row per extra image, and a row per variant.
• Which columns were understood, and which will be ignored. Worth reading — an unrecognised header is skipped silently, so a typo like Modifer Name would otherwise do nothing at all. Where the name is close to a real column, a suggestion is offered.

From there you can run a dry run. It does everything a real import does — the same matching, the same checks against your store — but writes nothing. Afterwards, History shows for every row exactly what would have changed, and anything that would have failed, with the same message the real run would give.

Worth doing before any REPLACE or DELETE, and before the first run of a file you did not produce yourself.

3. How rows are matched to existing products

For every command except NEW, the importer first has to find the product you mean. It tries the identifier columns your file provides, strongest first, and stops at the first one that matches:

1. Product ID — the BigCommerce ID. Exact, and needs no lookup, so it is both the safest and the fastest. Export your products first to get these.
2. Variant ID — resolved to the product that owns the variant.
3. SKU — the product's own SKU first, then variant SKUs.
4. UPC — same two steps as SKU.
5. MPN
6. Name — last resort, since names are not unique.

A column that is missing or left blank is skipped. If an identifier matches several products the row fails rather than guessing — add a Product ID to say which one you mean. Products with no SKU at all are fine: they are matched by Name, UPC, MPN or Variant ID.

To pin matching to one column, add [ID] to its header. For example SKU [ID] matches rows on SKU while letting you change the Name in the same file — without it, Name would also be treated as an identifier.

4. Base product fields

Include only the columns you want to change. A column you leave out, or leave blank, is never sent, so it cannot overwrite what is already in BigCommerce. A cell holding only whitespace counts as absent too.

• SKU — the product's stock-keeping unit. Optional; see matching above.
• Product ID — BigCommerce product ID. Recommended for updates.
• Name — product title.
• Type — physical or digital. Defaults to physical.
• Price — base price of the product.
• Weight — required for a physical product.
• Description — HTML is allowed.
• Is Visible — true or false.

5. Brand

• Brand Name (also accepted as Brand or Vendor) — the brand as text. If your store has no brand with that name, it is created. Matching is exact, so H&M and H & M stay two different brands — the same as in the BigCommerce admin.
• Brand ID — use this if you already know the ID. It takes priority and needs no lookup.

6. Categories

Only one of the three is used per row, strongest first: Category IDs → Category Paths → Category Names. Give two and the weaker one is not read at all, so do not expect the sets to be combined.

• Category Paths — full paths, e.g. Men/Shoes;Sale. Because / separates the levels, use ; between paths. This is the reliable way to say which category you mean.
• Category IDs — BigCommerce category IDs, e.g. 11,30. Fastest, since nothing has to be looked up.
• Category Names — just the last part of the name. Only works while that name is unique in your store. If two branches both have a "Shoes" category the row fails and tells you which paths clashed, rather than filing the product under both.
• Category Command — MERGE (default) adds these categories and keeps the others; DELETE removes the product from these categories only; REPLACE makes these the complete list, dropping any others.

A path or name that does not exist fails the row on purpose — a typo that silently skipped a category would not show up until the storefront was wrong. Create the category first, then re-run. If your file has no category columns, existing assignments are left alone.

7. Images

There is no limit on how many images a product can have. Supply them whichever way suits your file — you can mix all three:

• Image URL, or numbered Image URL 1, Image URL 2, … columns.
• Several URLs in one cell, separated by ;.
• Repeat the product's row, putting another image on each one. Only the identifier columns need filling in on the repeats.

Then:

• Image Alt — alt text. Worth setting; search engines read it.
• Image Position — display order, normalised to 1..N.
• Image Command — MERGE (default) adds new images and keeps the ones already there, so re-running the same file changes nothing; DELETE removes just the listed images; REPLACE removes every existing image, then adds the listed ones.

Naming an image exactly

Without an Image ID an image row is matched by its filename stem, because BigCommerce renames what you upload — towel1.jpg is stored as d/382/towel1__89452.jpg. That match is deliberately fuzzy, and it has a consequence: two genuinely different pictures whose URLs end in the same basename are treated as the same image, and the second updates the first.

The export writes Image ID for every image, so a re-imported export addresses each one directly. An ID that matches nothing falls back to the stem rather than failing the row — that is what lets a file exported from one store still upload its pictures into another.

The thumbnail can be moved

Image Is Thumbnail only ever takes true: BigCommerce clears the flag on the previous thumbnail itself, so sending false would leave the product with no thumbnail at all.

Images are never removed unless you ask. If your file has no image columns at all, existing images are left completely alone. On a variant row, Image URL sets that variant's own image instead of a product image. If BigCommerce cannot fetch one of your URLs, the product still imports and the failure is reported as a warning on that row.

8. Variants and options

• Parent SKU — leave empty on the main product row. Fill it with the main product's SKU on variant rows.
• Variant Title 1 — option name, e.g. "Color". Up to 3 options per product.
• Variant Value 1 — option value, e.g. "Red".
• Variant ID — BigCommerce variant ID. Include it when you rename a SKU, so the right variant is updated.
• Variant Command — MERGE (default) updates the variant if it exists, otherwise adds it; UPDATE updates only, and a variant that cannot be found is reported instead of added; DELETE removes just that variant; REPLACE removes all existing variants, then adds the ones in your file.

A variant is found by Variant ID first, then SKU, then by its combination of option values — so changing a SKU updates the existing variant rather than creating a duplicate. Options and option values you have not used before are created for you. If your file has no variant columns, existing variants are left untouched.

Variant display order cannot be set from the file: BigCommerce orders variants by their option values, not per variant.

How an option looks on the storefront

By default BigCommerce draws a variant option as buttons. Add Variant Option Type 1 (matching Variant Title 1) to choose:

• rectangles — buttons. The default, and what BigCommerce picks on its own.
• dropdown — a select list.
• radio_buttons — radio buttons.
• swatch — colour chips. These need a colour per value.

For a swatch, give each value its colour on that value's row with Variant Swatch Colors 1 — a hex like #FF0000, or two separated by a semicolon for a two-tone chip (#000000;#FFFFFF). The # is optional. Variant Swatch Image 1 uses an image instead.

Turning an existing option into a swatch needs a colour for every one of its values, because BigCommerce only accepts the whole set at once. If any are missing, the import says which ones and leaves the option as it was — the variants themselves still import.

9. Videos

One video per row, repeating the product's row the way price tiers do:

• Video URL — paste the YouTube link straight from the address bar. A watch link, a youtu.be short link, an embed, a Short or a live URL all work. The bare video id works too.
• Video Title, Video Description, Video Position.
• Video Command — MERGE (default) adds and updates the listed videos; DELETE removes just those; REPLACE makes the listed ones the only ones.

Only YouTube — BigCommerce does not accept any other provider. Videos are matched by their video id, so re-running the same file changes nothing.

10. Quantity-break pricing

A product can have several price tiers, so each tier goes on its own row — repeat the product's row and fill in a different quantity band:

• Bulk Pricing Min Quantity / Bulk Pricing Max Quantity — the band. Use 0 as the max for an open-ended top tier ("50 or more").
• Bulk Pricing Type — percent (percent off), price (a fixed price per unit), or fixed (a fixed amount off). Defaults to percent.
• Bulk Pricing Amount — the number that goes with the type.
• Bulk Pricing Command — MERGE (default) adds and updates the listed tiers; DELETE removes just those bands; REPLACE makes the listed tiers the only ones.

Tiers are matched by their quantity band, so re-running the same file updates the same tiers rather than adding duplicates.

11. Modifiers

Modifiers are extra choices on the product page that can change the price — engraving, gift wrap, a text box for a message. Each choice goes on its own row; rows sharing a Modifier Name build one modifier.

• Modifier Name — what the shopper sees. Must be unique within the product.
• Modifier Type — dropdown (default), radio_buttons, rectangles, swatch, product_list, or the free-input types text, multi_line_text, numbers_only_text, date, file, checkbox.
• Modifier Required — true or false.
• Modifier Value — one choice. Leave blank for the free-input types, which have no choices.
• Modifier Price Adjuster and Modifier Price Adjustment — relative adds an amount, percentage adds a percentage. Leave both blank for no price change.
• Modifier Command — MERGE (default) adds and updates; DELETE removes the named modifier; REPLACE keeps only the modifiers, and the values, your file lists.

Re-running the same file does not pile up choices. A choice with no price columns filled in is left exactly as it is, so you can add a new option without disturbing the pricing of the existing ones.

12. Custom fields and metafields

Both use a column per field, named after the field itself — so the columns are whatever your file needs:

• Custom Field: Material — a custom field named "Material". These show on the product page in your theme.
• Metafield: forix.colour — a metafield with namespace forix and key colour. Leave the namespace off (Metafield: colour) and it goes in the custom namespace. Metafields are for apps and integrations rather than display.
• Variant Metafield: forix.fit — the same thing on a variant row, for a metafield belonging to that one variant. Its own Variant Metafield Command works the same way.

Custom Field Command and Metafield Command — MERGE (default) adds and updates the listed fields; DELETE removes just those; REPLACE makes the listed ones the only ones.

Re-running the same file changes nothing — a field that already exists is updated in place. That matters because BigCommerce itself allows two custom fields with the same name, so a naive import would add another copy every time. Fields your file does not mention are left alone.

The export writes these columns too, named after whichever fields your products actually use — so an export can be edited in a spreadsheet and imported straight back without losing them.

13. Other supported fields

• Shipping — Is Free Shipping, Fixed Shipping Cost
• Tax — Tax Class ID, Product Tax Code
• Order limits — Min Order Quantity, Max Order Quantity
• Pre-order — Is Preorder Only, Preorder Release Date, Preorder Message
• Price display — Is Price Hidden, Price Hidden Label
• Storefront — Layout File, Warranty, Availability Description, Is Condition Shown, Bin Picking Number, Gift Wrapping Options Type
• Social sharing — Open Graph Type, Open Graph Title, Open Graph Description, Open Graph Use Product Name, Open Graph Use Meta Description, Open Graph Use Image
• Related Products — comma-separated product IDs

Boolean columns accept true/false, and also 1/0 and yes/no. Dates are best written as 2027-01-31T00:00:00+00:00 — BigCommerce stores the instant and reports it back in your store's timezone, so the text may differ slightly on the next export while meaning the same moment.

14. Example file

Command,SKU,Parent SKU,Name,Type,Price,Weight,Description,Is Visible,Image URL,Variant Title 1,Variant Value 1,Variant Title 2,Variant Value 2
NEW,TSHIRT-001,,My Awesome T-Shirt,physical,20.00,0.5,"<p>Best t-shirt ever</p>",true,https://example.com/tshirt.jpg,,,,
NEW,TSHIRT-RED-M,TSHIRT-001,,physical,20.00,0.5,,true,https://example.com/red.jpg,Color,Red,Size,M
NEW,TSHIRT-RED-L,TSHIRT-001,,physical,20.00,0.5,,true,https://example.com/red.jpg,Color,Red,Size,L
NEW,TSHIRT-BLUE-M,TSHIRT-001,,physical,20.00,0.5,,true,https://example.com/blue.jpg,Color,Blue,Size,M
UPDATE,TSHIRT-001,,My Updated T-Shirt,,,,,,,,,,
DELETE,OLD-PRODUCT,,,,,,,,,,,,

15. Complete column reference

Every column the importer reads, written exactly as the header must appear in your file. These are the same names the Export page writes, so an exported file can be edited and imported straight back. A header that is not on this list is ignored — the Check file step lists those before you run, with a suggestion when the name is close.

Identity and command

Core fields

Inventory

Identifiers

Categories and brand

Strongest first: Category IDs are used as given, Category Paths are resolved through the tree, Category Names must be unique or the row fails.

SEO and URL

Shipping and tax

Order limits, pre-order and price display

Storefront and Open Graph

Images

One image per repeated parent row, or several URLs in one cell separated by ;. Image URL 1, Image URL 2 … are accepted too, and each list column takes the same numbering.

Videos

YouTube only — BigCommerce refuses any other type. Paste a watch URL and the ID is pulled out of it.

Quantity-break pricing

One tier per repeated parent row. Tiers are matched by quantity band, not by ID, so re-running a file updates the same tiers instead of stacking new ones.

Modifiers

One value per repeated parent row; rows sharing a Modifier Name build one modifier.

Custom fields and metafields

The column name carries the field name, so you choose it. A DELETE row may leave the cell empty — the column name is what names the field to remove.

Variant rows

A variant row is a row with Parent SKU filled. Every core, price, inventory and shipping column above works on it as well; these are the columns that only mean something there.

16. BigCommerce's own limits

These are the platform's limits, not the app's. Nothing here can be raised by a setting, and a row that crosses one fails with BigCommerce's own message — which is usually terse. Knowing the numbers in advance is cheaper than reading the error.

Source for the table above: BigCommerce's Importing Your Catalog from Scratch support article. Unlike the API behaviours described elsewhere in this guide, these figures are quoted from BigCommerce's documentation rather than measured against a live store.