Full Feed CSV Data Format

This page describes the data format to follow when implementing a CSV integration with Fredhopper.

Overview

Fredhopper uses 6 CSV files to model your item data and import this into FAS. These are:

Filename	Description
categories.csv	Defines the hierarchical category structure for the product catalogue.
products.csv	Defines products and associates them with categories.
custom_attributes_meta.csv	Defines all attributes to be used and their base-type.
custom_attributes_values.csv	Lists the actual values for each product / attribute combination.
variants.csv	Defines variants and associates them with a product (optional).
custom_variant_attributes.csv	Lists the actual values for each variant / attribute combination (optional).

If your data model is such that there is no concept of variants, then the two variant CSV files can be omitted. Whilst these files have a .csv extension, the data columns are in fact separated by double tab characters rather than a comma.

categories.csv

The categories.csv file must adhere to the following guidelines:

• All categories must be provided in a file named categories.csv

• Columns are separated by double tabs (\t\t)

• UTF-8 encoded with standard PC end of line sequencing (\r\n)

• Only printable characters, i.e. no control characters

• All columns are in the defined order and have the defined headers

• The last line in the file should be blank (0 character length)

• All category_id and parent_category_id values must start with a lowercase letter

• The category_id and parent_category_id can only contain lowercase alphanumeric characters (a-z and 0-9)

• The category_id and parent_category_id values must never contain hyphens '-' or underscores '_'

• The best practice is to set the top-level category_id value as 'catalog01'

• The parent_category_id of the root category must point to itself

• The top-level category is always a single category

Column	Description
category_id	Unique identifier of the category. A category id should only ever contain lowercase alphanumeric characters only and should not contain underscores '_'. Whitespace, hypens, quotation marks, etc. are not allowed.
parent_category_id	Parent identifier of the category. A category id should only ever contain lowercase alphanumeric characters only and should not contain underscores '_'. Whitespace, hypens, quotation marks, etc. are not allowed.
locale	i18n localisation, e.g. en_GB or fr_FR.
name	Display name of the category for the defined locale.

Example

A single universe (catalog01) called 'Store' in English with two locales (en_GB and nl_NL)

category_id	parent_category_id	locale	name
catalog01	catalog01	en_GB	Shop
catalog01	catalog01	nl_NL	Winkel
women	catalog01	en_GB	Women
women	catalog01	nl_NL	Dames
shoes	women	en_GB	Shoes
shoes	women	nl_NL	Schoenen

products.csv

The products.csv file must adhere to the following guidelines:

• All products must be provided in a file named products.csv

• Columns are separated by double tabs (\t\t)
• UTF-8 encoded with standard PC end of line sequencing (\r\n)

• Only printable characters, i.e. no control characters

• All columns are in the defined order and have the defined headers

• The last line in the file should be blank (0 character length)

• The product_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)

Column	Description	Allowed Values
product_id	Identifier of the product	Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
locale	i18n localisation definition	i18n localisation, e.g. en_GB or fr_FR.
category_ids	Identifiers of the lowest level categories in which the product resided. In case a product is in multiple categories the id's they should be separated by a space.	A category_id should only ever contain lowercase alphanumeric characters only and should not contain underscores '_'. Whitespace, hypens, quotation marks, etc. are not allowed.

Example

One product in two locales (en_GB and nl_NL) that is in the Shoes category

product_id	locale	category_ids
p1	en_GB	shoes
p1	nl_NL	shoes

custom_attributes_meta.csv

The custom_attributes_meta.csv file must adhere to the following guidelines:

• All meta data for the attributes must be provided in a file named custom_attributes_meta.csv

• Columns are separated by double tabs (\t\t)
• UTF-8 encoded with standard PC end of line sequencing (\r\n)

• Only printable characters, i.e. no control characters

• All columns are in the defined order and have the defined headers

• The last line in the file should be blank (0 character length)

• The attribute_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)

Column	Description	Allowed Values
attribute_id	Identifier of the attribute	Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
type	Data type of the attribute.	Those specified in base-type definition above.
locale	Language combination for which the name applies	i18n localisation, e.g. en_GB or fr_FR.
name	Language specific name of the attribute

Example

Two attributes, one localisable (set) and one not (float)

attribute_id	type	locale	name
price	float		Price
colour	set	en_GB	Colour
colour	set	nl_NL	Kleur

You do not have to supply a locale value for attributes with non-localisable base-types, i.e. int, float and text.

custom_attributes_values.csv

The custom_attributes_values.csv file must adhere to the following guidelines:

• All product attribute data must be provided in a file named custom_attributes_values.csv

• Columns are separated by double tabs (\t\t)
• UTF-8 encoded with standard PC end of line sequencing (\r\n)

• Only printable characters, i.e. no control characters

• All columns are in the defined order and have the defined headers

• Line breaks and other formatting can be used in the attribute_value fields only, e.g. the html tag <br> can be used to add a line break to descriptive text

• The last line in the file should be blank (0 character length)

• The attribute_value_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)

Column	Description	Allowed Values
product_id	Identifier of the product	Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
locale	Language combination for which the name applies	i18n localisation, e.g. en_GB or fr_FR.
attribute_id	Identifier of the attribute as specified in the meta information.	Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
attribute_value_id	Unique identifier of the attribute value. This is required for set and list attribute types.	A unique value_id must be assigned to each unique value that exists for the attribute across the catalogue. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
attribute_value	Value of the attribute for the product

Example

Two products in two locales (en_GB and nl_NL)

product_id	locale	attribute_id	attribute_value_id	attribute_value
p1	en_GB	colour	blue	Blue
p2	en_GB	colour	red	Red
p1	nl_NL	colour	blue	Blauw
p2	nl_NL	colour	red	Rood
p2	en_GB	promotion_code	discount_10	10% discount
p2	nl_NL	promotion_code	discount_10	10% korting

You do not have to supply locale values for attributes with non-localisable base-types int, float and text.

variants.csv

The variants.csv file must adhere to the following guidelines:

• All variants must be provided in a file named variants.csv

• Columns are separated by double tabs (\t\t)
• UTF-8 encoded with standard PC end of line sequencing (\r\n)

• Only printable characters, i.e. no control characters

• All columns are in the defined order and have the defined headers

• The last line in the file should be blank (0 character length)

• The product_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)

Column	Description	Allowed Values
variant_id	Unique identifier of the variant	Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
product_id	Unique identifier of the product to which this variant is related	Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
locale	Language / country combination for which the variant applies	i18n localisation, e.g. en_GB or fr_FR.

Example

One product in one locale (nl_NL) with two variants

variant_id	product_id	locale
v543	p1	nl_NL
v544	p1	nl_NL

custom_variant_attributes.csv

The custom_variant_attributes.csv file must adhere to the following:

• All variant attribute data must be provided in a file named custom_variant_attributes.csv

• Columns are separated by double tabs (\t\t)
• UTF-8 encoded with standard PC end of line sequencing (\r\n)

• Only printable characters, i.e. no control characters

• All columns are in the defined order and have the defined headers

• Line breaks and other formatting can be used in the attribute_value fields only, e.g. the html tag <br> can be used to add a line break to descriptive text

• The last line in the file should be blank (0 character length)

• The attribute_value_id values can only contain lowercase alphanumeric and underscore characters (a-z, 0-9 and _)

Column	Description	Allowed Values
variant_id	Identifier of the variant	Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
locale	Language / country combination for which the name applies	i18n localisation, e.g. en_GB or fr_FR.
attribute_id	Identifier of the attribute as specified in the meta information.	Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
attribute_value_id	Unique identifier of the attribute value. This is required for set and list attribute types.	A unique value_id must be assigned to each unique value that exists for the attribute across the catalogue. Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.
attribute_value	Value of the attribute for the variant

Example

One product variant in two locales (en_GB and nl_NL)

variant_id	locale	attribute_id	attribute_value_id	attribute_value
v543		price		100.00
v543	nl_NL	size	small	Klein
v543	en_GB	size	small	Small

You do not have to supply locale values for attributes with non-localisable base-types int, float and text.