Your product data file should be a simple .csv table, with each row containing all the attributes of a given product, such as the item ID, the URL of the product page, a link to a product image, etc.
You must format the file to conform to the specifications and guidelines described below.
If your product data file contains more than a million items, please contact Emarsys support before importing it.
You can upload gzip compressed product data files to Emarsys. If your file runs to several hundred megabytes in size, you may consider compressing it.
Contents
General rules
- Use a CSV export library that is compatible with the standard CSV format.
- Use a comma to separate fields in a row.
- In fields containing multiple values, use a pipe (|) to separate the values. Example:
…,John Lennon|Paul McCartney|George Harrison|Ringo Starr,... - When a field does not have any value, leave it empty. Example:
value1,,value3,value4 - Do not use newline characters, either unquoted or quoted, in the fields.
- Use UTF-8 encoding.
- Include the field names in the first row (header) and make sure that all the subsequent rows contain the values corresponding to the fields listed in the header.
- Do not use more than 255 columns.
- Do not use field values longer than 64 KB.
Redundant (starting and trailing) white spaces are automatically trimmed unless they are quoted (e.g. 1, 2, 3 is the same as 1,2,3).
Need an example? Click here to see how a product data file looks like in the Emarsys CSV format or download a sample file.
Standard product data fields
Field |
Required | Type | Example | Description |
|---|---|---|---|---|
item |
Yes | String | BOOK0012 | - The unique ID used in your web store to identify the product. |
| - Do not include SKU-level product variants in the product data file. A good rule of thumb is to consider an item unique if it has a unique URL in your online store. | ||||
title |
Yes | String | The Hitchhikers guide | - The name of the product. |
| - Do not include any promotional text. | ||||
link |
Yes | URL | http://www.buy.me/hitch/ | - The URL of the items product page. |
| - Start with the protocol, such as http or https. | ||||
| - Do not encode the URL. | ||||
image |
No | URL | http://www.buy.me/hitch_thumb.jpg | - The URL for the product image. |
| - Start with the protocol, such as http or https. | ||||
| - Our best practice recommendation is to use a 800-pixel wide image to ensure that it looks good on retina displays. | ||||
| - Do not use images larger than 1 MB or 1280 x 1280 px. | ||||
- For high-resolution product images, use the zoom_image field. | ||||
| - If you only have high-res product images, we can create the thumbnails for you automatically. Learn more. | ||||
zoom_image |
No | URL | http://www.buy.me/hitch_fullres.jpg | - The URL for the high-resolution product image. |
| - Start with the protocol, such as http or https. | ||||
category |
No | Click here for details* | Fiction > Sci-Fi | English literature > Sci-Fi | The list of category paths in which the given item belongs. |
available |
No | Boolean | true | - The current availability of the product in your store. |
- Use either lower case (true) or all-caps (TRUE). | ||||
| - Make sure to keep this field up to date. | ||||
| - If possible, include all the items you have ever offered on your website. This will improve the analysis of historical data and makes it possible for Emarsys to recommend available alternatives for items no longer for sale. | ||||
- Submit products currently unavailable as false. | ||||
description |
No | String | Douglas Adams seminal work of fiction. | A brief description of the product. |
price |
No | Float | 13.99 | - The current product price you display to your customers in your web store. |
| - Do not include the currency. | ||||
| - Always use the period (.) as the decimal mark. | ||||
msrp |
No | Float | 17.99 | - The original price of the product (i.e. the price before discounts). |
- msrp should either equal or be higher than price. If msrp is lower, it will not be shown in email recommendations. | ||||
| - Do not include the currency. | ||||
| - Always use the period (.) as the decimal mark. |
* In this field, you can use multiple values.
Other predefined fields
Field |
Required | Type | Example | Description |
|---|---|---|---|---|
album |
No | String* | Let it be | The title of the album(s) on which the product was released. |
actor |
No | String* | Brad Pitt | The actor(s) associated with the product. |
artist |
No | String* | Janis Joplin | The artist(s) associated with the product. |
author |
No | String* | Douglas Adams | The author(s) associated with the product. |
brand |
No | String* | Nike | The brand name(s) of the product. |
year |
No | Integer | 1984 | The publication year of the product. |
* In these fields, you can use multiple values.
Product categories
In the category field, you submit the product category path of your items according to the product categorization system of your online store. A category path describes the location of each product in the category hierarchy. It is a >-separated list of subcategories that starts with the top-level category.
For example, a small bicycle store may have the following category hierarchy:
Bikes
Road Bikes
Mountain Bikes
Parts
Road
Tyres
Chains
MTB
Tyres
Chains
In this structure, Bikes and Bikes > Road Bikes are both valid category paths, while Road Bikes in itself is not, since it is not a top-level category.
The category path for bike1, an awesome road bike, is Bikes > Road Bikes, which can be submitted in your product data file like this:
item, title, category,... bike1, Awesome Road Bike, Bikes > Road Bikes, …
Emarsys Predict supports an unlimited number of category levels, while Smart Insight can handle a maximum of five levels. If there are more than 5 levels, Smart Insight keeps the top 5 and ignores the rest.
Items with multiple categories
Sometimes you may want to categorize products into multiple categories. For example, our bike shop sells pedal1, a universal hybrid pedal, which works on both road bikes and mountain bikes. As such, it belongs to both Parts > Road > Pedals and Parts > MTB > Pedals, so pedal1 belongs to a list of categories. The elements of lists should be separated by a | (pipe) within the category field.
item, title, category, ... pedal1, Universal Hybrid Pedal, Parts > Road > Pedals | Parts > MTB > Pedals,...
Custom fields
Besides the standard and predefined product data fields, you can also add other product information to your data file by using custom fields. The names of custom fields has to begin with the c_* prefix (e.g. c_color or c_size).
Make sure not to use the predefined field names in the names for custom fields. An example of a custom field name to avoid is c_available_colors as available is a standard field.
Custom fields are not validated by Emarsys.
Field localization
If you run a web store in multiple markets or languages, it may be necessary to also include the localized versions of standard product data fields in your product data file. Name your localized fields using the pattern [field name]_[language identifier], that is, the name of the standard product data field must be followed by an underscore and the language identifier (for example, title_it for the Italian title of a book).
All standard and predefined product data fields can be localized, except for item.
To learn more about localization, see our article on Localized Websites.
Disambiguation
Since several product attributes, such as categories, authors and actors, can be used to build statistical models, it is important to use them canonically. For example, the author J. K. Rowling should always be spelled the exact same way in the product data file. When there are more identical strings representing different values of a given attribute, they should be disambiguated consistently, for example J. Doe and J. Doe(2).
Resizing images with the Emarsys image proxy
Certain Emarsys apps, such as product recommendations, work properly with smaller images. If you only have high-resolution product images, Emarsys can create their thumbnail versions for you. To use this automatic image resizing service, simply replace the image URL with the following URL pattern in the image field:
https://imgfly.scarabresearch.com/w_<thumbnail image width in pixels>/<image URL>
Make sure to start the URL of the original image with the protocol, which can be either http or https, and to use the standard URL syntax.
Our best practice recommendation is to use 800-pixel wide images to ensure that they look good on retina displays too.
Examples
This is how a product data file looks like in the Emarsys CSV format. Click here to download a sample file.
item,link,title,image,category,price,msrp,available,brand,description,zoom_image 103,http://www.lifestylelabels.com/steven-by-steve-madden-pryme-pump.html,"elegant red pump",http://www.lifestylelabels.com/media/catalog/product/cache/1/small_image/210x/9df78eab33525d08d6e5fb8d27136e95/s/t/steven-by-steve-madden-pryme-pump.jpg,"Shoes > Pump",299,0,true,"Steve Madden","Nothing will turn his head faster than you wearing the sexy Pryme pump from Steven by Steve Madden. This daring pump has a pretty patent leather upper with light shirring, a double stitch detail surrounding the collar, and a vampy almond shaped toe.",http://www.lifestylelabels.com/media/catalog/product/s/t/steven-by-steve-madden-pryme-pump.jpg 108,http://www.lifestylelabels.com/nine-west-women-s-lucero-pump.html,"glittering red pump",http://www.lifestylelabels.com/media/catalog/product/cache/1/small_image/210x/9df78eab33525d08d6e5fb8d27136e95/n/i/nine-west-women-s-lucero-pump.jpg,"Shoes > Pump",289.99,0,true,"Nine West","The Lucero pump from Nine West may just leave him at a loss for words. This flirty pump has a leather upper, a pretty almond-shaped toe with a slight V-cut vamp, leather linings, and a cushioned insole for long-wearing comfort.",http://www.lifestylelabels.com/media/catalog/product/n/i/nine-west-women-s-lucero-pump.jpg 112,http://www.lifestylelabels.com/womens-golf-shoes.html,"womens golf shoes",http://www.lifestylelabels.com/media/catalog/product/e/c/ecco-womens-golf-flexor-golf-shoe.jpg,"For Women > Shoes > Golf",159,0,false,"Ecco","Sporting with style, this is a durable and super-comfortable golf shoe built for performance.",http://www.lifestylelabels.com/media/catalog/product/e/c/ecco-womens-golf-flexor-golf-shoe.jpg
The above file without white spaces:
item,link,title,image,category,price,msrp,available,brand,description,zoom_image 103,http://www.lifestylelabels.com/steven-by-steve-madden-pryme-pump.html,"elegant red pump",http://www.lifestylelabels.com/media/catalog/product/cache/1/small_image/210x/9df78eab33525d08d6e5fb8d27136e95/s/t/steven-by-steve-madden-pryme-pump.jpg,"Shoes>Pump",299,0,true,"Steve Madden","Nothing will turn his head faster than you wearing the sexy Pryme pump from Steven by Steve Madden. This daring pump has a pretty patent leather upper with light shirring, a double stitch detail surrounding the collar, and a vampy almond shaped toe.",http://www.lifestylelabels.com/media/catalog/product/s/t/steven-by-steve-madden-pryme-pump.jpg 108,http://www.lifestylelabels.com/nine-west-women-s-lucero-pump.html,"glittering red pump",http://www.lifestylelabels.com/media/catalog/product/cache/1/small_image/210x/9df78eab33525d08d6e5fb8d27136e95/n/i/nine-west-women-s-lucero-pump.jpg,"Shoes>Pump",289.99,0,true,"Nine West","The Lucero pump from Nine West may just leave him at a loss for words. This flirty pump has a leather upper, a pretty almond-shaped toe with a slight V-cut vamp, leather linings, and a cushioned insole for long-wearing comfort.",http://www.lifestylelabels.com/media/catalog/product/n/i/nine-west-women-s-lucero-pump.jpg 112,http://www.lifestylelabels.com/womens-golf-shoes.html,"womens golf shoes",http://www.lifestylelabels.com/media/catalog/product/e/c/ecco-womens-golf-flexor-golf-shoe.jpg,"For Women>Shoes>Golf",159,0,false,"Ecco","Sporting with style, this is a durable and super-comfortable golf shoe built for performance.",http://www.lifestylelabels.com/media/catalog/product/e/c/ecco-womens-golf-flexor-golf-shoe.jpg
Note that Emarsys considers both files exactly the same as redundant white spaces and redundant quoting are ignored. Also note that values containing the separator character must be enclosed in double-quotes (e.g. "Foo, Bar").