> For the complete documentation index, see [llms.txt](https://fredhopper.gitbook.io/product-discovery/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fredhopper.gitbook.io/product-discovery/sending-and-managing-product-data/flatfiles/fullprodfeed/full-feed-csv-data-format.md).

# 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:

<table><thead><tr><th width="289">Filename</th><th>Description</th></tr></thead><tbody><tr><td>categories.csv</td><td>Defines the hierarchical category structure for the product catalogue.</td></tr><tr><td>products.csv</td><td>Defines products and associates them with categories.</td></tr><tr><td>custom_attributes_meta.csv</td><td>Defines all attributes to be used and their base-type.</td></tr><tr><td>custom_attributes_values.csv</td><td>Lists the actual values for each product / attribute combination.</td></tr><tr><td>variants.csv</td><td>Defines variants and associates them with a product (optional).</td></tr><tr><td>custom_variant_attributes.csv</td><td>Lists the actual values for each variant / attribute combination (optional).</td></tr></tbody></table>

{% hint style="danger" %}
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.
{% endhint %}

## categories.csv <a href="#dataintegrationspecification-csvproductdata-categories.csv" id="dataintegrationspecification-csvproductdata-categories.csv"></a>

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**](http://en.wikipedia.org/wiki/Tab_key) (\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

<table><thead><tr><th width="224">Column</th><th>Description</th></tr></thead><tbody><tr><td><strong>category_id</strong></td><td>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.</td></tr><tr><td><strong>parent_category_id</strong></td><td>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.</td></tr><tr><td><strong>locale</strong></td><td>i18n localisation, e.g. en_GB or fr_FR.</td></tr><tr><td><strong>name</strong></td><td>Display name of the category for the defined locale.</td></tr></tbody></table>

#### **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 <a href="#dataintegrationspecification-csvproductdata-products.csv" id="dataintegrationspecification-csvproductdata-products.csv"></a>

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**](http://en.wikipedia.org/wiki/Tab_key) (\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 \_)

<table><thead><tr><th width="171">Column</th><th>Description</th><th>Allowed Values</th></tr></thead><tbody><tr><td><strong>product_id</strong></td><td>Identifier of the product</td><td>Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.</td></tr><tr><td><strong>locale</strong></td><td>i18n localisation definition</td><td>i18n localisation, e.g. en_GB or fr_FR.</td></tr><tr><td><strong>category_ids</strong></td><td>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.</td><td>A category_id should only ever contain lowercase alphanumeric characters only and should not contain underscores '_'. Whitespace, hypens, quotation marks, etc. are not allowed.</td></tr></tbody></table>

\\

#### **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 <a href="#dataintegrationspecification-csvproductdata-custom_attributes_meta.csv" id="dataintegrationspecification-csvproductdata-custom_attributes_meta.csv"></a>

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**](http://en.wikipedia.org/wiki/Tab_key) (\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 \_)

<table><thead><tr><th width="162">Column</th><th>Description</th><th>Allowed Values</th></tr></thead><tbody><tr><td><strong>attribute_id</strong></td><td>Identifier of the attribute</td><td>Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.</td></tr><tr><td><strong>type</strong></td><td>Data type of the attribute.</td><td>Those specified in base-type definition above.</td></tr><tr><td><strong>locale</strong></td><td>Language combination for which the name applies</td><td>i18n localisation, e.g. en_GB or fr_FR.</td></tr><tr><td><strong>name</strong></td><td>Language specific name of the attribute</td><td><br></td></tr></tbody></table>

#### **Example**

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

| attribute\_id | type  | locale      | name   |
| ------------- | ----- | ----------- | ------ |
| price         | float | <p><br></p> | Price  |
| colour        | set   | en\_GB      | Colour |
| colour        | set   | nl\_NL      | Kleur  |

{% hint style="danger" %}
You do not have to supply a locale value for attributes with non-localisable base-types, i.e. int, float and text.
{% endhint %}

## custom\_attributes\_values.csv <a href="#dataintegrationspecification-csvproductdata-custom_attributes_values.csv" id="dataintegrationspecification-csvproductdata-custom_attributes_values.csv"></a>

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**](http://en.wikipedia.org/wiki/Tab_key) (\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 \_)

<table><thead><tr><th width="190">Column</th><th>Description</th><th>Allowed Values</th></tr></thead><tbody><tr><td><strong>product_id</strong></td><td>Identifier of the product</td><td>Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.</td></tr><tr><td><strong>locale</strong></td><td>Language combination for which the name applies</td><td>i18n localisation, e.g. en_GB or fr_FR.</td></tr><tr><td><strong>attribute_id</strong></td><td>Identifier of the attribute as specified in the meta information.</td><td>Lowercase alphanumeric and underscore characters only (a-z, 0-9 and _). Whitespace, hypens, quotation marks etc. are not allowed.</td></tr><tr><td><strong>attribute_value_id</strong></td><td>Unique identifier of the attribute value. This is required for set and list attribute types.</td><td>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.</td></tr><tr><td><strong>attribute_value</strong></td><td>Value of the attribute for the product</td><td><br></td></tr></tbody></table>

#### **Example**

Two products in two locales (en\_GB and nl\_NL)

<table><thead><tr><th width="129">product_id</th><th width="99">locale</th><th>attribute_id</th><th>attribute_value_id</th><th>attribute_value</th></tr></thead><tbody><tr><td>p1</td><td>en_GB</td><td>colour</td><td>blue</td><td>Blue</td></tr><tr><td>p2</td><td>en_GB</td><td>colour</td><td>red</td><td>Red</td></tr><tr><td>p1</td><td>nl_NL</td><td>colour</td><td>blue</td><td>Blauw</td></tr><tr><td>p2</td><td>nl_NL</td><td>colour</td><td>red</td><td>Rood</td></tr><tr><td>p2</td><td>en_GB</td><td>promotion_code</td><td>discount_10</td><td>10% discount</td></tr><tr><td>p2</td><td>nl_NL</td><td>promotion_code</td><td>discount_10</td><td>10% korting</td></tr></tbody></table>

{% hint style="danger" %}
You do not have to supply locale values for attributes with non-localisable base-types int, float and text.
{% endhint %}

## variants.csv <a href="#dataintegrationspecification-csvproductdata-variants.csv" id="dataintegrationspecification-csvproductdata-variants.csv"></a>

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**](http://en.wikipedia.org/wiki/Tab_key) (\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 \_)

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

#### **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 <a href="#dataintegrationspecification-csvproductdata-custom_variant_attributes.csv" id="dataintegrationspecification-csvproductdata-custom_variant_attributes.csv"></a>

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**](http://en.wikipedia.org/wiki/Tab_key) (\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                                                       | <p><br></p>                                                                                                                                                                                                                                     |

#### **Example**

One product variant in two locales (en\_GB and nl\_NL)

<table><thead><tr><th width="135">variant_id</th><th width="91">locale</th><th width="126">attribute_id</th><th width="194">attribute_value_id</th><th>attribute_value</th></tr></thead><tbody><tr><td>v543</td><td><br></td><td>price</td><td><br></td><td>100.00</td></tr><tr><td>v543</td><td>nl_NL</td><td>size</td><td>small</td><td>Klein</td></tr><tr><td>v543</td><td>en_GB</td><td>size</td><td>small</td><td>Small</td></tr></tbody></table>

{% hint style="danger" %}
You do not have to supply locale values for attributes with non-localisable base-types int, float and text.
{% endhint %}