Scrooge API Access Application no longer accepts requests.

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

Requirements

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

Technical Specifications

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

  1. Each row of the feed must represent one and only one product
  2. Empty lines are ignored
  3. 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
  4. Each line must have the same number of fields
  5. There must be a field for each of the required attributes (see Attributes)
  6. There may be a field for each of the optional attributes (see Attributes)
  7. There may be fields not defined by Scrooge. These fields are ignored
  8. 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
  9. There should be (but not required) a first line header with the interpretations of the fields. See the Example
  10. 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

Attributes

The table below summarizes the product attributes recognized by Scrooge:

You cannot include HTML notation in any of the product's attributes.

Name Type Length Required Example
Unique ID String 200 Yes 322
Name String 300 Yes Samsung Galaxy S4 16GB
Product Link String 1000 Yes http://www.someurl.co.uk/products/322.html
Image Link String 400 Yes http://www.someurl.co.uk/images/322.jpg
Additional Image Link String 400 No* http://www.someurl.co.uk/images/322/front_view.jpg
Category Name String 250 Yes Mobile phones
Price Decimal - Yes 23.22
Availability String 60 Yes In 2 days
Manufacturer String 100 Yes Samsung
MPN / ISBN String 80 Yes GF322234
EAN / Barcode Integer 13 No 9780471117094
Size String 500 No* 4,4.5,5-6,6 1/2
Weight Decimal - No 3200
InStock List - No Y
Shipping Costs Decimal - No 3.22
Color String 100 No** Black

* Required by all fashion items with sizes, additional images
** Required by all fashion items

Unique ID

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.

Example
32
232AD

Name

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.

Example
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 http or https.

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.

Example
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 http or https. Links to scripts that generate images should be avoided as it may cause download errors.

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.

Avoid adding No Image template 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.

Example
http://www.mydomain.com/photos/1.jpg
http://www.mydomain.com/photos/b&b.jpg

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.

Example
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

Category Name

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 External 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.

Example
Mobile Phones > Bluetooth
Computers - Hardware - CPUs

Price

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).

Availability

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.

Manufacturer

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.

Size

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.

"5.5,6,6.5"

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.

"5.5-6.5"

Finally, if a product is identified by two sizes you can include them using the forward slash. (/) e.g.

"5.5/42,5.5/45"

Products that are identified by sizes and the size information is not provided will not be classified.

Weight

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.

Example

For a product with a weight of 3.2kg, the value of the weight field can be:

3200

or

3.2 kg

InStock

Stock status of the product

Y
means that the product is in stock at your outlet or your warehouse and can be picked up immediately.
N
means that the product is not available in stock.

When no information is provided the value of this attributed is considered as N (no stock).

Shipping Costs

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.

Color

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.

Example
Black
green

CSV Example

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