BigCommerce product import template: shaping a supplier spreadsheet into Product, Variant and Image rows

What the BigCommerce product import template is

A supplier spreadsheet lists a duvet cover as three rows, one per size, each named in capitals with the size on the end: LINEN DUVET COVER SAGE KING. The King row’s price reads +£5.00, its weight 1.3kg and its barcode 5.06012E+12. BigCommerce’s product import template wants a different shape: one Product row, a Variant row for each size directly beneath it and an Image row for each photo, with prices and weights as bare numbers.¹²

The template is a sample CSV file, linked from BigCommerce’s guide Importing Your Catalog from Scratch. It holds “all available import fields” and “several example products that demonstrate the format for each product attribute”.¹ The copy downloaded on 4 October 2026 had 50 columns, starting Item, ID, Name, Type, SKU and Options, and 13 example products with 57 Variant rows and 48 Image rows beneath them.⁷

An export of your own products gives “a CSV file formatted for product import” too.³ If you start from the sample, delete the example products first, “as they include product and category IDs that are not compatible with your store”. Files can be up to 20 MB, and up to 10,000 products import “without performance being affected”.¹

Modern or Legacy: two importers, two sets of columns

BigCommerce runs two product importers, and they read different columns. The Legacy one is for “stores with a single storefront channel”, on the v2 or v3 product experience; the Modern one works with one storefront or several, needs v3, and “is a prerequisite for enabling Multi-Storefront”.⁸ The sample above is the Modern template, and the Legacy guide links its own.⁹¹²

To tell which your store has, export one product and read the header. Item, ID and Name mean Modern; Item Type, Product ID and Product Name, the Bulk Edit names, mean Legacy.⁵¹¹ A Legacy store on v3 can switch from a banner at Products › Import and roll back from the same banner, until Multi-Storefront is on: “You cannot revert back to the legacy Import/Export experience after enabling Multi-Storefront.”⁸

The columns that matter, and the rows they sit on

A supplier row maps onto perhaps fifteen of the template’s 50 columns.⁷ Each row’s Item value decides which columns count on it, for example Options on a Variant row and Image URL (Import) on an Image row.⁵

Two rules sit behind the table. First, “Unless otherwise indicated, do not leave blank values in the CSV file”, so a column you have nothing for comes out, and Product URL, Free Shipping, Is Visible, Is Featured, Tax Class, Product Condition and Show Product Condition must be filled in or removed for new products.⁵¹ Second, field names are case sensitive.¹

Variant, Image and Video rows “must be located under the Product row they correspond to”.¹ A Variant row leaves ID, Name and Type blank, and its Price is “the absolute price of the variant”, or blank for the Product row’s price; Weight works the same way.² A product can have up to 600 variants.¹ Each photo is an Image row with its link in Image URL (Import), plus Image is Thumbnail (TRUE or FALSE) and Image Sort Order. A variant’s own photo goes in Variant Image URL on its row.²

The Options cell holds each option as a formula. BigCommerce’s radio button example is Type=Radio|Name=Size|Value=M, Dropdown and Rectangle take the same shape, and a Swatch adds a hex code. Two options sit “directly after each other or on separate lines in the cell”.²

Where supplier files break the import

BigCommerce’s help has steps for a spreadsheet “from a supplier or distributor”, and the step list below follows them.² The errors come from the values in the cells.

Units and currency in number columns. Weight reads 1100g, 1.3kg and 1.5 KG, and Price £44.99. A unit or symbol “in a numbers-only field like Price or Weight” fails with “Invalid [field] format. [field] must be float.”⁴ The unit is the store’s, set under Settings › Website and “applied globally”: Pounds, Ounces, Kilograms, Grams or Tonnes, and Inches or Centimeters.¹¹³ So those weights become 1.1, 1.3 and 1.5 in a store set to kilograms, or 1100, 1300 and 1500 in grams.

Half-empty columns. A supplier fills Width on some rows only. On the Modern import a blank cell returns “[field] is missed”, and the fix is to fill it in or remove the column.⁴ The blanks allowed are the ones BigCommerce notes, such as a Variant row’s Price.² So each column is completed from a source or dropped whole, and finding those values is what product data enrichment means in practice.

Names where numbers go. The category arrives as Bedding > Duvet Covers and the brand as LOWMERE HOME LTD. The Modern import takes “the category’s ID only, not its name”, and “Categories cannot be created by CSV import”; brands go in as a Brand ID and cannot be created either.⁵³¹⁴ A category’s ID ends the address of its Edit category page, and a brand’s is in the address bar when you view it.¹⁵ Mapping supplier categories onto your own tree comes first.

Rows out of place. Sort a supplier sheet by price after adding the Item column, and Variant rows leave their product. BigCommerce’s invalid Item field error covers rows “not added underneath a Product row”, as well as an Item value “misspelled or not properly capitalized”.⁴

Barcodes the spreadsheet has rewritten. A spreadsheet program “automatically converts numerical product identifiers, such as SKUs or UPCs, to scientific notation”, BigCommerce warns, which is how an EAN comes to read 5.06012E+12.⁴ Its fix in Excel is to open the CSV through Data › From Text/CSV and deselect Changed Type. In Google Sheets, untick Convert text to numbers, dates, and formulas.⁴ UPC/EAN and MPN are “typically assigned by a product’s manufacturer”, so lost digits come back from the product, as GTIN, EAN, UPC and MPN explained sets out.¹⁵

Images the import cannot fetch. A file name, a thumbnail, a TIFF. Images “must be hosted and have a referenceable URL”, as JPEG, GIF, WebP or PNG up to 8 MB, ideally 1280 × 1280 pixels: “They cannot be TIFF, BMP, or PDF file formats.”¹ A blank or partial link fails with “image_url must be present if uploading by url”, and “API server error: code 400” means the host “may be blocking API access”.⁴ Enough failures stall the import, and BigCommerce suggests batches above 1,000 images.⁴²

Fetching each link first finds those failures before the importer does. For a musical instrument retailer, that meant 3,566 dead links caught before export, out of 12,015.

One supplier row, before and after

Here is the King row against the Modern columns, with the kind of row each value lands on.

Each size has its own barcode, and an EAN is one form of GTIN, so it goes in Global Trade Number on the Variant row: a variant-level GTIN “can be created and updated via the modern Product Import/Export experience”. The Modern pages’ lists of variant fields leave the barcode columns out, though, so check one after a test import.¹⁵²⁶

The whole duvet cover is five rows, with the Product row carrying a base SKU of its own, as in the sample template.⁷

The King’s Options cell reads Type=Rectangle|Name=Size|Value=King. The Double’s and the Super King’s differ only in the value.²

On a Legacy store the King is a SKU row with [RT]Size=King in Product Name. A Rule row below the product’s SKU rows, matched by Product Code/SKU, takes the price: the supplier’s surcharge as [ADD]5, or the whole price as [FIXED]39.99. The category goes in by name, as Bedding/Duvet Covers.¹⁰

Building the file, step by step

1. Check which importer you have, from the header row of an export.⁵¹¹
2. Start from BigCommerce’s file, the sample or an export, with its header row exact and the example products deleted.³¹
3. Work on a copy of the supplier’s file, saved as CSV, and keep the column map, as supplier data onboarding explains.²
4. Rename headers to the template’s, letter for letter, and drop columns with no importable field.²
5. Lay out the rows: each Product row with its Variant and Image rows beneath it, every ID blank. Do not sort anything afterwards.¹
6. Write values the Modern way: bare numbers in the store’s units, TRUE or FALSE, category and brand IDs, and 1 in Channels for the default storefront.⁵¹
7. Fill in or remove every column, and keep codes as text, avoiding the Numbers app, which BigCommerce says “is known to cause errors”.⁵⁴¹
8. Check every image link, and split files above 1,000 images.²
9. Import one simple product first. The Preview page shows the first product before anything imports, and each error gives “the CSV line it occurred on”.¹⁴

When it is not obvious

A size the supplier adds later. On the Modern import, “New variants cannot be added or deleted to a product with existing variants via CSV import”, and trying returns “The display name: [Option Name] has already been used on this product”.²⁴ So every size goes in together, though BigCommerce’s suggested order still works: base products first, then all the Variant rows added to an export.² Legacy can add a size with a new SKU row.⁸ Variants: size and colour covers what counts as one product.

A colour with no hex code. A Swatch option needs one, as in Value=Red[#FF5500], and suppliers send colour names. Picking the code is a decision for a person; Radio, Dropdown and Rectangle options take the name alone.²

Before you click Start import

All of this happens in the spreadsheet, before BigCommerce sees a row, and it is what RefynData’s product data enrichment service does with a supplier file: each SKU or barcode matched to the real product and checked against its source, gaps filled with a link to where each value came from, measures converted to one unit, spelling variants folded onto one value, and every item filed into your own category tree. We prepare supplier spreadsheets for BigCommerce: a Google Sheet or Excel file, one tab per category, laid out for BigCommerce’s own importer in the format your store uses, and nothing goes live until you sign it off.

Whichever way the file is built, back up your product data first, as BigCommerce advises, and import one simple product before the rest.⁴ Then keep the supplier’s column map, because the next delivery will bring the same surcharges and the same thumbnails.