Importing Products from a CSV - Evance 5.x (Razzmatazz) and Later

The ability to add and update product data in bulk from a CSV file enables you to save time over manual entry. However, we advise using the Evance control panel to understand product fields before using this more advanced facility. 

This article assumes you have knowledge of using a spreadsheet software such as Microsoft Excel and saving to CSV format. 
Please ensure you follow the correct guide for your version of Evance (version numbers are found at the bottom of the Settings page in Evance).

Before you begin

Product imports can be complicated. So it's important to understand key concepts of the product importer before getting started.

  • Columns & headings
    Your CSV file must include column headings/titles in the first row. There is no naming convention, fixed sequence or number of columns required.
    You will be asked to map each column from your CSV to a property of the Product object, a sub-object or related object. For example, an "Image" column may be mapped to the Product Media sub-object.

  • Reference numbers
    Evance recognises products by their System ID, Quickfind code or SKU. System IDs and Quickfind codes are generated by Evance for new products.
    SKU reference numbers are defined by you. If you are updating existing products you MUST supply at least one of these reference numbers. We recommend maintaining unique SKU reference numbers for all of your products, including variants.

  • Contextual columns & rows
    The importer is contextually aware of sub-objects per row. This means it knows when it encounters a row with columns of the same type. For example, a row with two Image columns will be recognised as two different product media sub-objects. This means you can import a significant amount of data per row. Nevertheless, we recommend importing CSV files for products of the same type to avoid confusion within the data.

  • Naming conventions
    There are no strict naming conventions for column titles/headings. However, following the naming conventions within this article will make life easier for you when matching your columns during the import set-up process.

  • Remote file imports
    Evance is capable of importing images and downloads into its Media Library when it encounters external absolute URLs. However, it is unable to import protected files requiring log in, or may be blocked by some hosts. 

  • Background processing
    Once you start an import you may leave the importer and Evance will send you an email once the import is complete. You can check back at any time to see the progress of your import. 

Data formats in columns

We've tried to make Evance forgiving, but some fields require specific formatting.

Money

Monetary values should be supplied as a decimal only. For example:

  • £9.99 should be supplied as 9.99
  • 99p should be supplied as 0.99
  • $1,234 should be supplied as 1234.00
  • 1.234,99 should be supplied as 1234.99
Dates

To avoid issues between American and European formats, Date formats should ideally be supplied in one of the following formats:

  • 22 Jan 2019
  • 22 January 2019
  • 2019-01-22  (yyyy-mm-dd)
  • 01/22/2019 (US Format - mm/dd/yyyy)
  • 22-01-2019 (EU Format - dd-mm-yyyy)
Note: supplying dates separated by slashes will assume an American format (mm/dd/yyyy). 

 


Available import fields

Please read the instructions for each field carefully - some fields require precise settings which you should be aware of for a successful import. We have broken Product imports into the following sections:


Product identifiers

Evance will recognise products to update when it encounters one of the following identifiers. 

Quickfind

Read only, integer - maintained by Evance.

A sequential ID generated by Evance for each new product. Whilst you may use Quickfind codes to update products, you should leave this field blank for rows representing a new product.

SKU

String up to 30 characters. Maintained by you.

The SKU (Stock Keeping Unit) is your own unique reference for each product. This includes variants. Whilst SKU is optional we recommend that you set a unique reference for all of your products as early as possible. 

Top tips
A consistent pattern for SKUs makes them easier to use. Unbroken strings (no spaces) are more accurate in search.

System ID

Read only, integer - maintained by Evance.

The unique non-sequential ID assigned to your product by Evance. Used only when importing product data from an export. You should exclude this column when importing new product data.

 


Product properties

Properties that belong directly to a product object should not be repeated on the same row.

Band Reference

String up to 16 characters (optional)

Products may be assigned to a single band, which groups products together into a single classifier that can span different product types. This is usually used to associate products by profit margin. When importing products you should use the Band Reference (not its title).

If no product Band is found with the reference supplied a new Product Band is created - you will then need to maintain the new product band separately from within the Evance control panel.

Optional, may be set for some entries and not for others.

Barcode

EAN Barcode

Must be a valid barcode number.

Condition

String

Must be one of the following:

  • new (default)
  • used
  • refurbished

Discontinued

Y or N only (optional, defaults to N)

Has this product been discontinued and is no longer available for purchase on your website? If so enter Y or if not and your product is still available for purchase enter N. This column is optional, but if you decide to use this column you will be required to enter the correct value per line.

Discontinued Date

Date (optional)

Optional, but if you set the Discontinued field to Y you should enter the date the product is no longer available for purchase on your site. Leave blank if Discontinued is set to N.

Discontinued Reason

String up to 255 characters (optional)

A short description explaining why this product is no longer available for purchase. Perhaps it has been superseded by another in your database. Or perhaps it is no longer manufactured. Please do not enter HTML in this field. This field is optional even if your product has been Discontinued.

Is Active

Y or N only (optional, defaults to Y)

Whether the product is active and visible on the website (Y), or whether it should be hidden from public view (N).

Is Featured

Y or N only (optional, defaults to N)

Whether the product is marked as a featured product (Y), or not (N). Usage of this property may depend upon your website's theme.

Is Indexable

Y or N only (optional, defaults to Y)

Whether the product should be indexed by search engines (Y), or not (N).

Is Purchasable

Y or N only (optional, defaults to Y)

Whether the product may be purchased online (Y), or whether it is not (N).

Is Searchable

Y or N only (optional, defaults to Y)

Whether the product should be included in search results (Y), or not (N).

Long Description

Text/HTML

Well written and informative content, which is rich in search engine friendly keywords, will encourage sales and help you get found on search engines such as Google.

Required when creating new products. Optional when updating products.

Top tips
Avoid using suppliers' default long descriptions. If you are importing copy from supplier data, take the time to read Long Descriptions and rewrite the copy to suit your brand communication style.

Manufacturer

String up to 32 characters (optional).

The name of the product manufacturer. If no product Manufacturer is found with the name supplied a new Manufacturer is created. You will then need to maintain the new Manufacturer separately from within the Evance control panel.

Optional, may be set for some entries and not for others.

Manufacturer Model

String up to 30 characters (optional).

The manufacturer model for this product. For example, 'Xs' is a model in the 'iPhone' range of phones manufactured by Apple.

Manufacturer Range

String up to 30 characters (optional).

The manufacturer range this product belongs to. For example, 'iPhone' is a range of phones manufactured by Apple.

Max Lead Time

Integer (optional, defaults to 1).

The number of days it typically takes to dispatch the product when out of stock. Not how long it takes to arrive at the customer's doorstep, which is subject to their shipping option when checking out. 

Recommended, this property is used to estimate delivery dates during checkout.

Maximum Order

Integer 0 to 999 (optional, defaults to 0).

The maximum quantity a user may purchase in a single order. Defaults to 0 (zero) for unlimited.

Meta Description

String up to 255 characters (optional).

A brief keyword rich, yet concise description of your product. The purpose of the meta description is to add additional keywords to your search criteria and is often used by Search Engines in natural listings.

Meta Ketwords

String up to 255 characters (optional).

A tightly linked comma separated list of keywords and/or phrases that best describe your product. These may include alternative names the product is known as or common spelling mistakes the product may be found under. Importantly your meta keywords are used by some search engines for keyword relevancy and also by Evance within the internal search algorithm. We recommend trying to limit your keywords/phrases to around 14 comma separated entries.

Meta Title

String up to 120 characters (optional).

The title that appears in your browser's title area, or in search engine results. If not set, your product's title will be used instead.

Min Lead Time

Integer (optional, defaults to 1).

The number of days it typically takes to dispatch the product when in stock. Not how long it takes to arrive at the customer's doorstep, which is subject to their shipping option when checking out.

Recommended, this property is used to estimate delivery dates during checkout.

Minimum Order

Integer 1 to 999 (optional, defaults to 1).

The minimum order quantity a user may add to cart.

Packaged Depth

Integer in millimetres (mm).

The outer packaged depth of the product measured in mm as an integer. 

Optional, but recommended for use with shipping calculations.

Packaged Height

Integer in millimetres (mm).

The outer packaged height of the product measured in mm as an integer. 

Optional, but recommended for use with shipping calculations.

Packaged Width

Integer in millimetres (mm).

The outer packaged width of the product measured in mm as an integer. 

Optional, but recommended for use with shipping calculations.

Part Number

String up to 100 characters (optional).

The manufacturer part number for this product.

Shipping Class

String up to 64 characters (optional).

The name of the shipping classifier to be used for this product when calculating shipping on this product. This field is optional and if omitted the default Shipping Class will be used.

If no Shipping Class is found with the name supplied a new Shipping Class is created. You will then need to maintain the new Shipping Class separately from within the Evance control panel.

Optional, may be set for some entries and not for others.

Short Description

String up to 255 characters.

Concise promotional copy written to entice further reading. Usage varies per Theme.

Required when creating new products. Optional when updating products. Should not contain HTML.

Sales End

Date (optional).

The date on which to stop selling this product. For example, for a date of '01 Jan 2019' the last day of sales is '31 December 2018'. Optional per line, which means you may set it on some products and not on others. Leave blank to continue selling indefinitely.

Sales Start

Date (optional).

The date on which to begin selling this product. Optional per line, which means you can set the Sales Start date on some products and not on others. Leave blank to start immediately.

Superseded by Quickfind

Integer (optional).

If you have Discontinued a product and would like to keep a record of a product that superseded it then you can add the Quickfind code for the new product. 

Optional, may be set for some entries and not for others.

Superseded by SKU

String up to 30 characters.

An alternative to "Superseded by Quickfind". If you have Discontinued a product and would like to keep a record of a product that superseded it then you can add the SKU code for the new product. 

Optional, may be set for some entries and not for others.

Tax Class

String up to 64 characters (optional).

The name of the tax classifier to be used when calculating sales tax for this product. This field is optional and if omitted the default Tax Class will be used.

If no product Tax Class is found with the name supplied a new Tax Class is created. You will then need to maintain the new Tax Class separately from within the Evance control panel.

Optional, may be set for some entries and not for others.

Template

String up to 40 characters.

The web page template reference name to use from your current Theme.

Leave blank to use the default template.

Title

String up to 120 characters.

Product titles should be short and concise, but descriptive enough to search relevant. We do not accept HTML in product titles.

Required when creating new products. Optional when updating products.

Type

'product' or 'variant'.

There are currently two types of product.

  • Product (default)
    A product with its own URL.
  • Variant
    A basic variant does not have its own URL. See the section on Variants below.
If you do not include a Type column Evance will assume all rows of data represent a Product with its own URL.

URL

String up to 255 characters - optional.

Product URLs must...

  • start with /product
  • NOT contain spaces
  • NOT be a fully qualified or absolute URL
  • contain letters (a-z), numbers (0-9), dashes (-) or underscores (_)
  • be in lowercase

If you exclude the URL column, or leave the field blank, Evance will attempt to generate a URL on your behalf based on the Product's title. For example, a product with title "iPhone Brace Case" will import as "/product/iphone-brace-case".

Weight

Decimal in Kilograms (kg).

The gross packaged weight of the product measured in kg as a decimal. 

Optional, but recommended for use with shipping calculations.

 


Variants

There are two types of variants in Evance:

  • Basic Variants (Type of 'variant')
    A basic variant does not have its own web page and does not appear within product categories. A basic variant will appear as an option on the product page it is associated with (its master product). To add a Basic Variant to a Product your row must have a Type column with a value of 'variant'.

  • Advanced Variants (Type of 'product')
    These are products with their own web page and may appear in a product category as a product in their own right. But, may be associated with a master product as a variation. To link a Product as a Variant of another product your row needs a Type column with a value of 'product' and may be associated to its parent product using one of the properties below.

Variant of Quickfind

Integer (optional)

The quickfind code of this product's master/parent product.

Cannot be used when creating a new master/parent product within the same CSV.

Variant of SKU

String (optional)

The SKU of this product's master/parent product.

Variant of System ID

Integer (optional)

The Product ID of this product's master/parent product.

Cannot be used when creating a new master/parent product within the same CSV.

 

Example

Adding a parent and variant

A variant MUST be defined after its parent/master product if the parent/master is also new within the same CSV. 

SKU Type Variant of SKU Size
MY-001-S product S
MY-001-M variant MY-001-S M
MY-001-L variant MY-001-S L
MY-001-XL variant MY-001-S XL

 


Prices

Price imports can be done on a single row or as an individual import with multiple prices set on a product across multiple rows. 

Currency

3 character ISO code (e.g. GBP)

The currency of all prices supplied for the row represented as the 3 character ISO code for the currency e.g. GBP. This field is optional and only required when importing prices that differ from your website's default currency. If you supply the currency code for one row you must supply it for all entries.

Required for multi-currency imports (see multi-currency example below)

Current Price

Money (optional)

The current/offer price for a quantity of 1 unit of your product. 

You should supply an unformatted decimal number to the decimal specifications of your Currency. For GBP this is 2 decimal places, however Evance supports up to 6 decimal places. 

The price you enter may be including or excluding tax depending on the "Includes Tax" field, or the default Tax settings for your website.

Includes Tax

Y or N only (optional)

Whether prices defined for this price object are inclusive or sales tax (Y) or exclusive of sales tax (N). Optional, if excluded the prices will be set according to your website's tax rules.

List Price

Money (optional)

The standard (not on offer) price for a quantity of 1 unit of your product. 

Optional when updating products, required when importing new products. You should supply an unformatted decimal number to the decimal specifications of your Currency. For GBP this is 2 decimal places, however Evance supports up to 6 decimal places. 

The price you enter may be including or excluding tax depending on the "Includes Tax"  field, or the default Tax settings for your website.

Price Access

String (optional)

Define non-public price lists granted to users with a given Access Role.

Leave blank, or exclude this column for public pricing.

Price Type

String (optional)

Must be one of the following:

  • buy (default)
  • hire
Note: this column may only be defined once per row and should appear before prices.

Price Zone

String (optional)

Define regional pricing limited to a geographic zone. Must be the name of an existing Geozone. Requires a Premium plan.

Leave blank, or exclude this column for non-regional pricing.

Quantity

Integer (optional)

Required for volume based pricing (see below for an example). Defaults to 1.

RRP

Money (optional)

The recommended retail price for your product is an optional setting that may be set for some entries and not for others. You should supply an unformatted decimal number to the decimal specifications of your Currency. For GBP this is 2 decimal places, however Evance supports up to 6 decimal places. 

The price you enter may be including or excluding tax depending on the "Includes Tax" field, or the default Tax settings for your website. 

 

Example

Volume pricing - single row

Evance's contextual processing allows you to define quantity based pricing per row. 

SKU Quantity Price Quantity Price Quantity Price
MY-001 1 9.99 5 9.75 10 9.50

Notice we have added columns for each quantity and price. Whilst this adds columns to our spreadsheet is does allow you to import more advanced pricing information within a single sheet.


Example

Volume pricing - multiple rows

Importing volume pricing across multiple rows is usually done as a separate CSV import.

SKU Quantity Price
MY-001 1 9.99
MY-001 5 9.75
MY-001 10 9.50

 

Example

Multi-currency - single row

Evance's contextual processing allows you to define multiple currency based pricing per row. This is applicable to stores with Locale capabilites (requires the Catalogue Premium or Ecommerce Premium plans)

SKU Price Currency Price Currency
MY-001 9.99 GBP 12.00 USD

 

Example

Multi-currency - multiple rows

You can import prices for products in a separate CSV with each price on its own row.

SKU Price Currency
MY-001 9.99 GBP
MY-001 12.00 USD

 


Media (images & videos)

You can import product media with other product data on a single row per product, or as an individual import across multiple rows.

Image

String up to 150 characters.

There are to ways to import images:

  • Manual import
    Specify a content URL to a relevant Media Library image directory. Your images must be uploaded into a sub-folder of /content/images to take advantage of Evance's auto-sizing. For example, if you upload your images to "~/content/images/products/ " your CSV field must start with this URL. Image URLs are case sensitive and the reference supplied in your CSV file must be an exact match to the images location.

  • Remote import
    Specify remote/external URLs to images on another host. Evance will attempt to import each image into the media library.

Please be aware that Evance will not check the validity of the URL supplied and if entered incorrectly the image will not appear on your website and you will need to manually remove and/or re-enter the image from within the control panel. However Evance will check whether the image is already assigned to the product to avoid duplication.

Media Title

String up to 100 characters.

Usage depends on your Theme. This may be used as an alt tag for the image, or as a label in an image gallery for the product.

Media Type

Must be one of the following:

  • photo (default)
  • video
  • rotate
Exclude this column for image/photo imports.

Primary Image

Y or N only

The "Primary Image" for the product needs to be specified in the column previous to the "Image" (see example below).

Note: even if this is the first image to be assigned to the product, you need to set the image as the "Primary Image" for the product.

Video Url

String up to 150 characters (optional).

Define a YouTube, Vimeo or self-hosted video in your Media Library.

Required for Media Type 'video'.

 

Example

Defining a primary image

The example below illustrates how to define the primary image as well as using Account URI for ~/content and importing a remote/external image.

SKU Primary Image Image Image
MY-001 Y ~/content/images/filename.jpg https://domain.com/path-to-image.jpg

 


Downloads

You can import product download data from a CSV. This includes data for downloads you wish to manually upload and for downloads you would like Evance to save from a remote host.

Download Description

String up to 255 characters (optional).

Allows you to offer more information about a download on a product page.

Download Title

String up to 60 characters (optional).

Allows you to display a download title instead of a file name on product pages.

Download Url

String up to 150 characters.

There are to ways to import downloads:

  • Manual import
    Specify a content URL to a relevant download directory in your Media Library. Your downloads must be uploaded into one of the following folders or a sub-folder of:

    • ~/content/downloads

    • ~/content/pdf

    • ~/content/private
      If you are importing files which require purchase (i.e. digital goods), files should be upload into this directory or to a sub-folder of this directory.

  • Remote import
    Specify remote/external URLs to downloads on another host. Evance will attempt to import each download into an appropriate media library. This gives you less control over where downloads are stored and may not be appropriate for sensitive/purchasable downloads.

Please be aware that Evance will not check the validity of the URL supplied and if entered incorrectly the download will not appear on your website and you will need to manually remove and/or re-enter the download from within the control panel. However Evance will check whether the download is already assigned to the product to avoid duplication.

 


Categories

You can import a product into one or more category hierarchies, either as multiple columns when importing product data or as a separate import for each product across multiple rows. 

Category

String

Contains a category hierarchy which must adhere to the following:

  • Category hierarchy strings must always start from the root category.
  • Categories must be separated by a right angle bracket (>) to denote hierarchy.
  • Categories should not have commas (,) in their names.
You may associate a product with one or more categories (see example below). 

 

Example

Assigning a product to multiple categories

An example of importing a product into two category hierarchies: 

SKU Category Category
MY-001 Men > Suits Men > Jackets


Evance is capable of performing a lookup of the category hierarchy and recursively creating categories as required. To avoid duplication Evance will check whether a product already exists within a category before adding it. 

Specifications

Evance will attempt to match existing specification headers and values for consistency and if it cannot find them it will add them as new entries. However, Evance is unable to cope with spelling mistakes or variations in headings or values so you will need to maintain a pattern manually when importing through CSV. For instance 50W, 50 W, 50 Watts will all be classed as different entries.

{heading}

String up to 50 characters (optional)

Unlike other columns the Technical Specification option may be used any number of times. Your column header should not actually read "Technical Specification" but should be the Heading or Classification for your specification. 

For example, if you have a light bulb with a Wattage of 50 Watts your header may be called Wattage and your entry for the row would be 50 Watts.

 

Example

Multiple specifications per row

You may import columns with custom headings to represent a specification.

SKU Size Colour Material
MY-002 Small Red Cotton
MY-002 Medium Black Leather

As you can see the column headers for technical specifications may be custom. Once you have imported specifications you can manage their finer points within the global product specifications manager. For example, you may wish to add colour or image swatches for Colour or Material.


Stock

There are several core product settings associated with stock:

Preferred Warehouse

Y or N (optional, defaults to N)

Is this Warehouse (see below) the preferred warehouse to dispatch items from?

Stock Alert Level

Integer (optional, defaults to 0)

The quantity in stock across all warehouses considered low for this product. Optional, however if you decide to import stock alert levels you should set a value 0 or greater for all entries.

Stock Quantity

Integer

The number of items in stock you have in the Warehouse (see below).

Stock Reorder Quantity

Integer

The number of items to suggest ordering when the warehouse reaches a low stock alert.

Suspend on Depletion

Y or N only (optional, defaults to N)

Specify whether the product is to remain purchasable on your website when out of stock. Set to N to continue taking orders. Set to Y to stop receiving orders. This column is optional, however if you decided to import Suspend on Depletion values you should set to either Y or N for all entries.

Warehouse

String up to 60 characters

The name of the warehouse for the stock level you wish to import.

Warehouse Location

String up to 45 characters (optional)

The shelf location reference where the stock is located within the warehouse.

Warehouse Stock Alert

Integer

The private stock level specific to this Warehouse (see above) where your warehouse manager receives a low stock notification by email.

 

Example

Multiple warehouse entries - single row

It is possible to import multiple warehouse stock levels on a single row.

SKU Warehouse Stock Quantity Warehouse Stock Quantity
MY-001 Shed 23 Box under desk 5

 


Example

Multiple warehouse entries - multiple rows

It is possible to import stock levels for products in a separate CSV file with each row representing a stock entry.

SKU Warehouse Stock Quantity
MY-001 Shed 23
MY-001 Box under desk 5

 


Related products

You can relate a product to others using a Quickfind or SKU. This may be done on a single row or as an independent import across multiple rows.

Related by Quickfind

Integer

The Quickfind code of the product we wish to relate to the current product row.

Related by SKU

String

The SKU of the product we wish to relate to the current product row.

 

Example

Relating products on a single row

To avoid errors with interpreting relationship codes, Evance requires each relationship to have its own column.

SKU Related SKU Related SKU
MY-001 MY-002 MY-003

 

Example

Relating products on separate rows

To avoid errors with interpreting relationship codes, Evance requires each relationship to have its own column.

SKU Related SKU
MY-001 MY-002
MY-001 MY-003

 


Locale restrictions

Applicable to stores with multi-regional facilities. Requires a Premium plan or higher.

Alternative URL

String (optional)

Allows you to define an alternative page for the locale if the Locale Status is ''hidden'.

Locale Reference

String 5 characters.

Must be a locale identifier string associated with a Channel Locale. For example, 'en-gb'.

Locale Status

String

Must be one of:

  • hidden
  • enquire only
  • purchasable (default)

 


Content fragments

In addition to a Product's short and full description, you can import additional content fragments.

Fragment reference

String up to 40 characters.

The reference name within your Product's template file.

Product editable regions

Fragment HTML

HTML

The text/html to display on the product page within the editable area referenced.