Importing products from a CSV (Excel) file

For fast import of multiple products and categories to your online store, create a text file in CSV format using popular spreadsheet editors; e.g., OpenOffice/LibreOffice Calc, Microsoft Excel, iWork, etc.

Download sample CSV file containing examples from this article.

To obtain a correctly formed example of a CSV file, manually add some categories and products and then export them to a file. Use the exported sample for creatiadng your own CSV files.

1. Составление CSV-файла

The first row in the file must contain column names without empty cells between any of them. Enter product and category information in the 2nd and further rows.

Column titles do not necessarily have to exactly match those shown in this guideline. You may type any convenient titles which you will then be able to associate with the desired product and category properties during import.

Column descriptions

values which may be specified for categories
values which must not be specified for categories
for products and SKUs, you may fill values in any columns

CSV file column Description Example Category Product
Category and product properties
Наименование Category or product name. Apple iPhone 5S
Storefront link Individual portion of the URL of the main category or product page. iphone-5s
Title This text will be added into HTML tag TITLE of the category or product page. Apple iPhone 5S
META keywords This text will be added into META tag keywords of the category or product page. Apple, iPhone, mobile phone
META description This text will be added into META tag description of the category or product page. iOS-based smartphone
multi-touch screen (capacitive)
screen size 4"...
Description Full product or category description, which may contain any HTML tags. <h3>Forward Thinking.</h3><div>iPhone 5s is purposefully imagined. Meticulously considered. Precision crafted...
Status Whether product or category must be available via common navigation. Acceptable values: 1 (visible), 0 (hidden). Hidden items remain accessible by their direct URLs. 1
Currency ISO3 code of the currency, in which product price is expressed. If not specified, then product price is imported in the default currency selected in store settings. USD
Product type Name of product type which must be assigned to the product. If a new product type is specified which is not defined in store settings, then this new product type will be created only if the user importing a CSV file has sufficient access rights for that. Mobile phones
Summary Brief description of a product to be displayed in various product listings such as categories, product sets, search results, etc. This field may contain HTML code. iPhone has always been forward thinking. And that’s exactly what iPhone 5s is now. 64-bit mobile architecture is pioneering...
Badge One of the standard badge identifiers (new, bestseller, lowprice) or custom badge HTML code. new
Tags List of tags associated with a product, comma-separated. iPhone,mobile phone,Apple
Taxable Name of tax rule to be applied to a product. The specified tax rule must be defined in store settings screen “SettingsTaxes”. VAT
Product images

Image URL or file name. If a URL is specified, then the image will be retrieved from that address and saved on the server. If a file name is specified, then the image file will be copied from the directory specified in import settings.

If more than one image must be imported for a product, create additional columns with the same name.

Product image description Description of the image specified in previous column. Front view.
Product images Another product image. iphone-5s-back.jpg
Product image description Another product image description. Back view.
Size example of a product feature

Extra product feature. The exact value format depends on the specific feature type:

  • Single value (e.g., string or number) is specified as is. If there is a measure unit in the value, then it must be specified with a whitespace character after the actual value, just like it is displayed in the store backend. Example: 12 m.
  • For features offering multiple values to a backend user (e.g, drop-down list or checkbox group), values must be specified inside curly brackets, separated by a comma. If one of the values contains a comma, then it must be specified inside double quotation marks. Example: {"38,500","38,700","38,900"}.
    The first of these values will be set as the default choice for features of type “select” (drop-down list).
  • If the imported product must be available in the feature value selection mode (as opposed to the plain SKU selection mode), then the feature values used for generating SKUs must be specified inside special double brackets: <{}>. For example, if a product must be available for ordering via the choice of the “Size” feature values, then these value must be specified in a CSV file in this form: <{M,L,XL,XXL}>.
SKU properties
SKU Internal SKU code.
If a product has only one SKU, then you may nod need to include this column in your CSV file.
SKU name The name of an SKU displayed in the storefront.
If a product has only one SKU, then you may nod need to include this column in your CSV file.
White, 32Gb
Available for purchase Specify 0 in this column if you want to temporarily make an SKU not available for ordering. The SKU will remain visible in the storefront, but customers will not be able to add it to the shoping cart. To make an SKU available for ordering again, import 1 in this column. 1
Price SKU price. The price currency is defined by the value of the “Currency” field. 649
Compare at price “Compare at” price expressed in the currency specified in the “Currency” field. 749
Purchase price Purchase price expressed in the currency specified in the “Currency” field. 590
In stock Number of SKU items available in stock specified as an integer value. Ue this column to import SKU stock values, if you do not have stocks defined in your store settings or if you have only 1 stock set up. 24
In stock @stock1 Number of SKU items available in stock named “stock1”. If you have multiple stocks set up in your store settings, then, instead of one “In stock” column, create several columns, each for one of your stocks. To facilitate the automatic detection of CSV file columns during import, write column titles as shown in this example, with the @ character (without a white space) preceding the stock name. Add a separate column for each stock to your file. 18
Primary SKU Flag of the SKU which must become the primary one within a product. Only one SKU per product can be marked as primary. 1
Product images URL or name of a product image file which must be selected in this SKU’s properties. iphone-5s.jpg

Identification columns

Each column in a CSV file corresponds to a category, product, or SKU property. Some of the columns are used for identifying catalog items. Identification is necessary to differentiate categories, products, and SKUs from each other. For example, if column “Name” is used for product identification and a name of an existing product is specified in a CSV file, then such a file will be updated during import. If there is no such product before the import, then it will be created.

You can choose the identification columns for products (categories) abnd SKUs during import, after uploading a CSV file.

Difference between categories and products

A CSV file row is imported as a category, if it contains only properties which are specific to categories: name, link to storefront, title, META tags, summary, and status. These columns are marked in the column description table with color . For products and SKUs, any properties may be specified: .

Categories and subcategories

You can import only static categories from a CSV file, import of dynamic categories is not supported. However, you can update various properties of dynamic categories via a CSV file provided that such categories already exist in your store.

By default, all imported categories are created at the same (highest) hierarchy level. If you need to place some categories at a lower level in the catalog, then add an exclamation mark before a category name; e.g.,:

Name Price
Mobile phones

To create a new category to an even lower hierarchy level, add more exclamation marks. If further categories must be placed again at a higher level, reduce the number of exclamation marks before their names:

Name Price
Mobile phones
!!Series 60

Adding products to categories

Newly imported products specified after category rows will be created inside those specific categories. Assignment of categories to products occurs only for newly imported products. When information of already existing products is updated via a CSV file, their category assignment will not be changed.

Example of adding products to various categories:

Name Price
Mobile phones
Apple iPhone 5S 649
HTC One 599

In the above example, a product named “Apple iPhone 5S” will be created in category “Mobile phones”, and product “HTC One” inside subcategory “Sale”.

Adding a product to multiple categories

You can import a product into multiple categories. To do so, copy the product line under several category lines.

Name Price
Category 1
Product 100
Category 2
Product 100

Importing products and SKUs

If a row of a CSV file contains at least one value in a column specific only to products and SKUs (such columns are marked with color ), then such a row is imported as a product or its SKU. If there are several subsequent rows with product-specific information, containing equal values in the product identification column, then such a group of rows is imported as several SKUs of one product. Product-specific information (see columns listed in table section “Category and product properties”) is imported only from the first row in that row group. SKU-specific information will be imported from all such rows.

You can import product SKUs via a CSV in one of these 2 modes: 1) plain SKU list and 2) feature value selection.

Mode 1: Plain SKU list

For products available for ordering in this mode, SKU-related information must be specified in additional rows following the row containing the product-related information so that all these rows have equal values in the product identification column. The values in the SKU identification column must be different for correct differentiation of the SKUs from each other. Below is provided a portion of a CSV file with a list of SKUs of a sample product. In this example, column “Name” is used for product identification, and column “SKU” is used for SKU identification.

Name SKU Price
Jet Snowboard Boots jet-6-white 156
Brave Jacket jet-7.5-black 157
Brave Jacket jet-8-white 160
Mode 2: Feature value selection

For products available for ordering in thise mode, SKUs are automatically generated during import and are based on all possible combinations of feature values specified inside special double brackets <{}> (see main table section with the description of feature values format). SKUs can be generated only from the values of "Checkboxes" type features.

For example, to generate SKUs based on the values of the “Color” feature, specify them as shown in the below example. In this example 3 SKUs will be generated, each for one feature value.

Name Price Available for purchase In stock Color
Apple iPhone 5S 649 1 200 <{gray,silver,gold}>

SKU-specific properties specified in such a row will be equally distributed among all generated SKUs. In the above example, the “Available for purchase” field value will be assigned and price 36990 will be set for all generated SKUs.

In stock value can be imported in different methods for automatically generated SKUs. You can select the desired method in import settings:

  • Equally distribute stock levels among all SKUs of this product (default choice).
  • Set provided stock count for all imported SKUs.
  • Don’t import stock information for automatically generated SKUs.

Should you need to generate SKUs based on the values of multiple features, then you need to specify their values in the same way. In the following example 6 SKUs will be generated, for all possible combinations of feature values specified inside special double brackets <{}>.

Name Price Color Built-in memory capacity
Apple iPhone 5S 649 <{gray,silver,gold}> <{16Gb,32Gb,64Gb}>

When it is necessary to specify individual values of price, availability for purchase, and stock count for automatically generated SKUs, they must be specified in separate rows like for product selling mode 1. In these rows, the SKU identification column must contain the feature values of each SKU, separated by comma & space, and the same values also specified in the corresponding features' columns as shown below.

Name SKU name Price In stock Color Built-in memory capacity
Apple iPhone 5S 649 <{gray,silver,gold}> <{16Gb,32Gb,64Gb}>
Apple iPhone 5S Gray, 32Gb 749 12 gray 32Gb
Apple iPhone 5S Golden, 64Gb 849 34 gold 64Gb

When importing SKUs in mode 2 "Feature value selection", for SKU identification, select the column containings SKU names.

2. File upload

To import a CSV file, open backend section “Import/Export → Import from CSV”.

Select the value delimiter used in your file. Default choice is the semicolon (;).

Select the file encoding. It is usually UTF-8 if your file created with OpenOffice or LibreOffice, or might be a national character encoding if the file was created with Microsoft Excel.

If you are using special or national characters (e.g., ©, ±, ö, and others) in your product names and descriptions, then it is recommended to save a CSV file using international encoding UTF-8 to avoid the loss of such characters.

Browse the file on your computer to upload it. After the upload is completed, all columns found in your CSV file will be displayed as a table.

When importing a large CSV file, it may be convenient to compress it into an archive before uploading. Supported archive formats are ZIP and GZ.

After a file has been uploaded, a preview table showing all file columns will appear on the page.

3. Select column associations

Shop-Script will attempt to “guess” which file columns with which properties should be associated. Manually adjust the associations where necessary.

4. Select identification columns

Select the category/product/SKU properties by which you want the import script to identify catalog entries.

Identification is very important as it “tells” the import script how categories, products, and their SKUs listed in a CSV file must be differentiated between each other. For the identification, select columns with values which must be unique for the corresponding type of catalog entries.

Products & categories identification options

Select the option which is appropriate for your case:

  • Product name: products and their categories will be identified by the values in the column for which you have selected the “Product name” property.
  • Public link: products and their categories will be identified by the values in the column for which you have selected the “Storefront link” property.
  • Product ID: categories will not be imported or updated, and products in the file will be identified by the values in the column for which you have selected the “Product ID” property. Product ID товара is a numeric ID of a product stored in database table shop_product. It is displayed on the product-editing page in the store backend.
  • SKU identification column: categories will not be imported or updated, and products in the file will be identified by the values in the column which you will select for SKU identification.
  • (skip products and categories, import only SKUs): neither categories nor products will imported or updated; only product SKUs will be imported or updated, they will be identified by the values in the column which you will select for SKU identification.

SKU identification options

Select the option which is appropriate for your case:

  • SKU code: product SKUs will be identified by the values in the column for which you have selected the “SKU code” property.
  • SKU name: product SKUs will be identified by the values in the column for which you have selected the “SKU name” property.
  • SKU ID: product SKUs will be identified by the values in the column for which you have selected the “SKU ID” property. SKU ID is a numeric ID of a product SKU stored in database table shop_product_skus.

5. Advanced settings

If necessary, specify advanced import settings:

  • Ignore category nesting when searching for matching products. When this option is enabled (recommended), existing files during import will be detected within the entire catalog, regardless of their category assignment, by the values in the product identification column. When this option is disabled, then existing products will be detected only inside the categories in which those products are specified in a CSV file.
  • Product type. The selected product type will be assigned to all new products which do not have a product type specified in a CSV file.
  • Non-HTML product descriptions. Enable to automtically add HTML tags <br> to exported product descriptions, if none of your product descriptions contain any HTML tags.
  • Product images import local path. if you have specified file names, rather than URLs, in image columns in your CSV file, then upload those files prior to import to a subdirectory of one of the root directories available for selection in this drop-down list. Then enter the path to the subdirectory with uploaded files next to the name of the selected root directory. Note that you have to upload product image files to a directory located on your server rather than your PC.
  • Unique product image URLs. If in your product image URLs equal file names are used and only the path to a file is different, then select “by file path” option. If both file path and name are the same and only the domain name differs, then select “by file path and domain name”.
  • Stock level for products with selectable features . Select one of the options to import stock count values for automatically generated SKUs, based on selectable feature values specified inside special double brackets <{}>.

6. Import options review

After specifying the desired import parameters, click on the review button at the page bottom in order to analyze your CSV file contents before it is actually imported and to evaluate the number of categories, products, and SKUs which will be imported into your store. If you are not satisfiled with the review results, change import settings and repeat the review action.

7. File import

To complete the data import, click on the confirmation button at the page bottom. Keep the import screen open in your browser until the operation is completed!


  • 0 Expert Developer October 19, 2013 03:57 #
    we can not upload selectable SKU's via CSV file??
    is that possible?
    • 0
      Mike Mike Webasyst October 21, 2013 04:19 #
      Do you mean SKUs based on feature values? No, you cannot import such SKUs using a CSV file, beacause there is no way to specify feature values for them in the file.

      Add comment

      To add a comment please sign up or login