CSV Data Feed Specification Edit the file on GitHub
This document describes the structure of the CSV file provided by merchants to Scrooge. We do not require a specific document template as long as the required product attributes are included (see attributes description).
Scrooge strongly suggests the use of the XML feed type. However we provide the CSV feed type as an alternative for merchants who cannot use the XML feed.
Table of Contents
In general, the CSV file must meet the following requirements:
- Must be encoded in UTF-8
- Must conform to the CSV RFC
- Doesn't repeat the same products more than once (see Unique ID)
- Includes V.A.T. in prices
A CSV file according to the CSV RFC is a collection of records. Each record is one line in the CSV file and consists of one or more fields separated by commas.
For a CSV Data Feed to be accepted by Scrooge the following requirements must apply
- Each row of the feed must represent one and only one product
- Empty lines are ignored
- The field separator must be the same for each row. We suggest the comma as separator but we accept any separator accepted by the CSV RFC
- Each line must have the same number of fields
- There must be a field for each of the required attributes (see Attributes)
- There may be a field for each of the optional attributes (see Attributes)
- There may be fields not defined by Scrooge. These fields are ignored
- The position and meaning of each field must be fixed e.x if the second field is the price, this must hold for all rows
- There should be (but not required) a first line header with the interpretations of the fields. See the Example
- The value of each field must be according to the standards. They must be properly quoted as defined by the CSV RFC. This is necessary for multi valued fields that must be comma separated like size
The table below summarizes the product attributes recognized by Scrooge:
You cannot include HTML notation in any of the product's attributes.
|Additional Image Link||String||400||No*||
|MPN / ISBN||String||80||Yes||
|EAN / Barcode||Integer||13||No||
* Required by all fashion items with sizes, additional images
** Required by all fashion items
This attribute represents the unique identifier of a product in your database. The value of this field must remain the same through a product's lifecycle and cannot be reused in other products.
If the title of a product changes between updates so that it no longer refers to the same product (e.g. from Sony LDF700 to Sony LDF800) then the product will be disabled. It is important to note that Unique IDs must always refer to the same product.
A Unique ID cannot refer to more than one product. In such a case the product will be updated only the first time it's encountered in the data feed.
In case your e-commerce application supports more than one languages your data feed should only include definitions in the English language to avoid duplication.
The title of the product. It is essential for the title to include all necessary attributes of the product even though some of them might be included in other parts of the CSV as well (i.e. manufacturer, model, color, version, part number, etc). The more accurate the title, the quicker the product will be classified.
The title of products that are second hand or refurbished must clearly state their condition otherwise they will be disabled from the content team. Note the quotes in values that include the comma separator.
Nokia 5800 XpressMusic "A,B TV controller"
Your product title should not include information about the product guarantee, shipping costs, payment methods, special bundles or marketing actions.
The URL that links to your shop's page for the specified product. It must be a
valid URL starting with
Product links should not be URL-encoded.
This link must only point to a product page and not a category page or a collection of products page.
http://www.mydomain.com/products/1 http://www.mydomain.com/products/product.php?itemid=1 http://www.mydomain.com/products/product.php?itemid=1&somevar=3 http://www.mydomain.com/products/product.php?itemid=1&somevar=3
The product's image location. It must be a valid URL starting with
https. Links to scripts that generate images should be avoided as it may cause
It's better to include high resolution images in your data feed. Images are downloaded by Scrooge and proper thumbnails are created.
Images must not be watermarked.
Image links should not be URL-encoded.
No Imagetemplate images because if you later change it Scrooge might not update it. If a product doesn't have an image yet, you can just send an empty image link. If you later change it the image will be updated normally.
Additional Image Link
It is used for additional photographs of the product. Additional photos of the same product from different angles or with a different presentation or combinations of the above add value to the presentation of the product in Scrooge.
This field is optional but recommended, except for fashion categories where additional images are required. It can occur multiple times in the feed, once for each different photograph. It has the same limitations as Image Link.
http://www.mydomain.com/photos/1.jpg http://www.mydomain.com/photos/b&b.jpg http://www.mydomain.com/photos/product1/front.jpg http://www.mydomain.com/photos/product1/sides.jpg http://www.mydomain.com/photos/product1/packaged.jpg
The product's category path. It is essential that this attribute includes the
full path of the product's category. For example, if the product is an
Hard Drive then the category name attribute should look like
Computers > External Hard Drives
Avoid ambigious categories containing different products (e.g. Printers and Scanners) as it will slow down the classification process of your products.
Mobile Phones > Bluetooth Computers - Hardware - CPUs
It's the products retail price including V.A.T.
The price of the product must apply to everyone without any special conditions (e.g. offers, discounts pending on location etc).
This product's shipping availability as used throughout your shop.
Scrooge uses a fixed set of availability descriptions that will be crosslinked to the ones provided in your feed.
- Available in store / Delivery 1 to 3 days
- refers to products that are available for pick up at your outlet.
- Delivery 1 to 3 days
- refers to products that can be delivered to your customer within 1 to 3 days.
- Delivery 4 to 10 days
- refers to products that can be delivered to your customer within 4 to 10 days.
- Upon order
- refers to products that are ordered upon customer request.
The manufacturer of the product
The manufacturer name must be also include in the title regardless if it is included in this attribute.
The manufacturer attribute must point to the actual manufacturer of the product and not the manufacturer this product is used for in cases of spare parts or accessories.
MPN / ISBN
The unique manufacturer identifier of the product. It is used to identify a product and classify it.
This attribute is required for categories where the Manufacturer Product Number is required to identify a product with different configurations (e.g. storage, color, etc)
If the product is a Book then this field must include the
ISBN of the book.
Books without their ISBN information will not be classified
EAN / Barcode
The international article number (EAN) used for the identification of retail products.
This attribute is optional but is strongly recommended for categories where retail products have the same product brand but variations in weight, colour etc. A unique EAN is allocated to each separate retail product.
If the product comes in sizes you can include all available sizes in this attribute seperated by commas.
For example, a sport shoe available in 5.5, 6, and 6.5 your
CSV will include
the following attribute. Note the quotes in all the examples.
You can also use
1/2 as a half size indicator
"5 1/2,6,6 1/2"
In case of clothes, sizes can be in one of the following formats:
"XXS, XS, S, M, L, XL, XXL, XXXL" "Extra Small, Small, Medium, Large, Extra Large" "00, 0, 2, 4, 6, 8, 10, 12, 14, 16"
If a product fits a size range (e.g. socks) then you can declare the size as a range using the dash (-). e.g.
Finally, if a product is identified by two sizes you can include them using the forward slash. (/) e.g.
Products that are identified by sizes and the size information is not provided will not be classified.
The product's weight used by your platform to calculate shipping costs in grams. If you wish to provide
it in kilograms you can do so by adding
kg to the value string.
For a product with a weight of
3.2kg, the value of the weight field can be:
Stock status of the product
- means that the product is in stock at your outlet or your warehouse and can be picked up immediately.
- means that the product is not available in stock.
When no information is provided the value of this attributed is considered as
The product's shipping cost regardless of the customer's location. If the
product shipping cost is known beforehand you can include the shipping cost here.
If this product is eligible for free shipping, you can indicate it by providing
0 as a value for this attribute.
Shipping costs included here should be independent of the shipping location. If this is not the case , then this attribute should be blank.
Shipping costs will be displayed along with your other product information as long as they are accurate every time. If, even for one product, shipping costs are not accurate then they will be removed from all products in your data feed.
The color of the product. The color attribute functions as a property of the specific product and cannot cover multiple product entries.
It should contain the color of the product as depicted in the product image.
In case multiple colors for a given model exist, they should be submitted as different products with separate Unique IDs.
The CSV excerpt below is an example of a compatible CSV data feed. The first line in the header. Note that according to the CSV RFC the fields that include a comma are properly quoted, like name in the third line that uses double quotes to include a quote in the name. Also note that fields without a value, like ean in the third line, are blank so that the number of fields in each line is the same.
id,name,link,image,additionalimage,category,price_with_vat,manufacturer,mpn,ean,instock,availability,size,weight,color 322233, MadBiker 600, http://www.mywebstore.co.uk/product/322233, http://www.mywebstore.co.uk/product/322233.jpg, http://www.mywebstore.co.uk/product/322233/front.jpg, Outdor > Extreme Sports, 322.33, SuperGlasses, ZHD332, 9780471117094, N, Pre Order, "5.5,6", 360, Black 322234, "MadBiker 600 ""Extreme""", http://www.mywebstore.co.uk/product/322234, http://www.mywebstore.co.uk/product/322234.jpg, http://www.mywebstore.co.uk/product/322234/front.jpg, "Outdor, Extreme Sports", 322.33, SuperGlasses, ZHD333, , N, Pre Order, "5.5,6, 6.5", , White