Skip to main content

CSV Files

Visidea requires three types of CSV files to provide personalized recommendations:

  • Items file: Contains product catalog information.
  • Users file: Contains user account information.
  • Interactions file: Contains user-product interaction events.

All files must follow the same formatting rules:

  • UTF-8 encoded
  • Rows separated by \n
  • Fields separated by semicolon ;
  • Text fields enclosed in double quotes "
  • Double quotes in text fields escaped by a backslash \ (e.g., \")
  • Column names in the first row

Summary Table​

File TypePurposeRequired Columns (see details below)
ItemsProduct catalogitem_id, code, ...
UsersUser account infouser_id, email, ...
InteractionsUser-product interactionsuser_id, item_id, ...

1. Items File​

Purpose: Describes each product in your catalog.

Header (columns):

item_id;code;mpn;ean;name;description;brand_id;brand_name;price;market_price;discount;page_ids;page_names;url;images;stock;gender;tags;attributes

Column Descriptions:

  • item_id: Product ID (required)
  • code: Internal or SKU code
  • mpn: Manufacturer part numbers, separated by |
  • ean: EAN codes, separated by |
  • name: Product name
  • description: Product description
  • brand_id: Brand ID
  • brand_name: Brand name
  • price: Original price in euro (float, no thousand separator)
  • market_price: Discounted price in euro (if no discount, use original price)
  • discount: Discount percentage
  • page_ids: Category/page IDs, separated by |
  • page_names: Category/page names, separated by |
  • page_urls: Category/page URLs, separated by |
  • url: Product detail page URL
  • images: Image URLs, separated by |
  • stock: Product availability (0 if not published)
  • gender: Man / Woman / Unisex
  • tags: Tags, separated by |
  • attributes: JSON object of additional attributes

Example:

item_id;code;mpn;ean;name;description;brand_id;brand_name;price;market_price;discount;page_ids;page_names;page_urls;url;images;stock;gender;tags;attributes
"123";"SKU123";"MPN1|MPN2";"1234567890123";"T-shirt";"A cool t-shirt";"1";"BrandX";"29.99";"19.99";"33";"cat1|cat2";"Shirts|Summer";"/cat1|/cat2";"/product/123";"/img/1.jpg|/img/2.jpg";"10";"Unisex";"summer|sale";"{\"color\":\"blue\",\"size\":\"M\"}"

Translated Fields​

Add a column named translations that contains a JSON string. The JSON must be an array of objects; each object must contain a language property and any translated fields.

Fields that can be translated are: name, description, page_names, page_urls and url.

  • Column name: translations
  • Value: a JSON array encoded as a single CSV field (text fields enclosed in double quotes "; double quotes in the JSON must be escaped with a backslash \).

Example header (note translations column):

item_id;code;...;translations

Example row (JSON is inside the translations CSV field; inner quotes escaped with \):

"123";"SKU123";...;"[{\"language\":\"it\",\"name\":\"Joust Duffle Bag\"},{\"language\":\"it\",\"description\":\"...\"},{\"language\":\"it\",\"page_names\":\"Gear|Bags\"},{\"language\":\"it\",\"url\":\"https://...\"}]"

Notes:

  • Keep the translations field as a single CSV cell.
  • Fields not translated can be omitted from each language object.
  • Maintain CSV formatting rules (UTF-8, ; delimiter, \n row separator, double quotes around text fields, escape inner quotes with \).

2. Users File​

Purpose: Describes each user in your system.

Header (columns):

user_id;email;name;surname;address;city;zip;state;country;sex;birthday;createdDate

Column Descriptions:

  • user_id: User ID (required)
  • email: User email
  • name: First name
  • surname: Last name
  • address: Address
  • city: City
  • zip: ZIP code
  • state: State
  • country: Country (ISO 3166-1 alpha-2, e.g., US)
  • sex: Sex
  • birthday: Birthday
  • createdDate: Registration timestamp (ISO 8601, e.g., 2022-03-22T09:27Z)

Example:

user_id;email;name;surname;address;city;zip;state;country;sex;birthday;createdDate
"1";"[email protected]";"John";"Doe";"123 Main St";"New York";"10001";"NY";"US";"M";"1990-01-01";"2022-03-22T09:27Z"

3. Interactions File​

Purpose: Describes user actions on products (e.g., purchases, cart additions).

Header (columns):

user_id;item_id;action;timestamp

Column Descriptions:

  • user_id: User ID (required)
  • item_id: Item ID (required)
  • action: Action (purchase or cart)
  • timestamp: Event timestamp (ISO 8601, e.g., 2022-03-22T09:27Z)

Example:

user_id;item_id;action;timestamp
"1";"123";"purchase";"2022-03-22T09:27Z"
"1";"124";"cart";"2022-03-23T10:00Z"

Notes​

  • If a field is not available, leave it empty but keep the delimiter (e.g., ;;).
  • All files must be consistently formatted for successful import.
  • For questions or support, contact the Visidea team.