Content through FTPS – Technical Manual

Introduction to the content feed for product information

One of the ways product information for articles you sell on bol.com can be delivered to our platform is through FTPS ‘content feeds’. 

Your product information feed can consist of:

  • a text file containing product information that your systems generate,
  • images for the products in the text file

You can upload these files to your account on our FTPS server. This upload can be automated or manual. Our platform processes the uploaded feeds hourly.

The exact specifications for automation, files and images are described in this document.

Important note: product information excludes the prices, stock and delivery promises for the products you sell. Price/stock/delivery promise together constitute your sales ‘offer’ and are processed separately. How to set up your offer management is described in the offer management documentation.

Content Feed FTPS

Steps to set-up an automated feed for product information

Step 1: Creating the text file for the content feed

The file needs to be formatted according to the following specifications:

  • text file – the extension should be .txt;
  • tab-delimited – entries need to be separated by TAB, not comma or semicolon
  • coding should be UTF8 (without BOM);
  • English attribute headers should be in line 1
  • Records start in line 2
  • 10Mb – if this size is exceeded, the file needs to be split in multiple files that each have their own headers

You can download an example content feed here.

Step 2: Formatting content according to the bol.com datamodel

Your feed file needs to follow the formatting and value rules described by our XML datamodel in order for the content to be processed correctly.

Our XML datamodel describes all accepted product attributes, their types, their formats, their importance, their possible value restrictions, and their validation criteria. Also, it provides instructions for each attribute, if necessary.

The basis of our XML datamodel is the product classification (productType).

The XML datamodel contains all the accepted product classifications (productType) in the bol.com catalogue, the product attributes per classification and the formats for the attribute values. Also described are the enrichment levels: from attributes mandatory for products appearing online to optional attributes.

Our datamodel, and consequently the datamodel XML file, is changing frequently. The most impactful changes are saved for the Quarterly Release. Smaller changes are published weekly for you to download.

An explanation of XML tags in our XML datamodel

Tag Description Instructions
<productType> The accepted product classification/product group. This is an attribute containing the definition of the product, for instance ‘Shoe’ or ‘Lamp’. If a productType is not in the XML datamodel, it does not currently exist in the bol.com catalogue.

Values are case-sensitive.

<name> The attribute name (in English) A colum header in your content file. This should go in the first line.
<chunkID> The (unique) ID for the productType.
<label> The translation of the attribute name in Dutch.
<attributes> Contains the product attributes linked to the productType.
<attribute> Contains a description of the product attribute.
<multiValue> States whether multiple values are allowed for the attribute. If true, values need to be separated by a semicolon “;”.
<attributeDefinition> A longer description of the attribute.
<enrichmentLevel> States the importance of the attribute for this productType. Enrichmentlevel 0 + 1: minimum mandatory attribute to create a product in the catalogue, publish it and make it findable in the shop.

Enrichmentlevel 2: attribute contributing to findability, navigation and shop filters.

Enrichmentlevel 3: attribute providing extra information for the customer.

<fillingInstructions> Contains extra instructions for attribute values, if available.
<possibleValues> States the list of values the attribute is restricted to, if applicable. Values are case-sensitive.
<defaultUnit> The default unit for the attribute. For instance ‘kilogram’ or ‘millimeter’. Values are case-sensitive.
<validation> States validation rules for the attribute value, like <baseType>  and <maxLength>.
<baseType> States fieldtype for the attribute. Possible baseTypes are: text, date, number, url or ean-13.
<maxLength> Maximum field length for a ‘text’ field.
<minValue> Minimum field value for a ‘number’ field.
<maxValue> Maximum field value for a ‘number’ field.
<units> List of possible units.

 

For an attribute that contains a list of possible units, you need to state a unit for the value in your feed. The syntax for the attribute unit tag is: “[attributeName]_unit”, for example: “Product Length_unit” with  the value “mm”.

Step 3: Product images

There are two ways to upload images for your products to FTPS:

  1. Through an URL to the place where your images are hosted
  2. Through uploading the images to the Images- and Images/Stills folder on FTPS
  3. If your product images are available on an online location, you can enter the URL of the image in your feed.
  1. If you want to upload the product images to the FTPS server directly, they need to fit the following criteria.
  • the name of the main product image needs to be <EAN>.jpg (without the brackets);
  • the names of the additional product images need to be <EAN>_1.jpg , <EAN>_2.jpg (without the brackets), and so on. The numbers determine the order the images will be shown in the shop;
  • the image files need to fit our format criteria for image files. If not, they will be rejected after processing.

After one week the images will be deleted from the FTPS server. This deletion will not affect the images on the shop.

Step 4: Creating an FTPS account.

In order to create an account, you need the following:

  • to be a known partner (seller or supplier) for bol.com, with a seller/supplier ID;
  • an example of your content feed file. A bol.com employee will check your formatting & content for you and help with any adjustments.

Go here to create your account.

Step 5: Start your feed

As part of the process of account creation you have received login credentials and your IP address has been whitelisted. Please note the credentials for your content feed are different from any other credentials (for instance offer or order management).

As a best practice we advise you to:

  • only place products and images you have updates for in the feed;
  • upload files at most once a day (unless your assortment is very large and changing quickly);
  • not update the exact same files multiple times.

When you enter your FTPS folder, you will find various subfolders. Use the list underneath to set-up your upload locations for your feed and product images.

FTPS Folder Structure

Directory Use
SQUARE/feed Upload location for the content feed text file
images Upload location for main product images (1 per product)
images/stills Upload location for additional product images (unlimited)
SQUARE/history Download location for processed content feed text files
SQUARE/feedback Download location for feedback on processed files

Step 6: Feedback

After your file and images have processed and are validated, we will provide you with feedback for every file. You can download the feedback files for 30 days after upload in the specified folder.

Important note: if the productType you provided was rejected (because the value was not found in our datamodel), you will not see feedback for the product.

If all products were processed successfully, you will not see feedback for your file.

Important notes on the content process

Feeds are processed twice hourly, but note that content updates can take up to 24 hours to be fully visible in the shop. The files in the content feed are always processed.  It is unnecessary to upload the same file multiple times.

Our content process decides what content will become visible in the shop. Therefore, (some of) your content updates may not become visible at all. This is to be expected.A full explanation of our content process is available at our Partner Platform.

Important updates to our datamodel: Quarterly Release and Release Notes

Our datamodel is changing frequently. We save the most impactful changes for a Quarterly Release. High-impact changes are:

  • Changes to productgroup names
  • Changes to productgroup contents
  • Productgroup deletion
  • Addition of mandatory attributes linked to a productgroup

All these changes can impact the visibility of your assortment, and the placement of your articles in the shop.

The Quarterly Release is announced, in detail, a month in advance through your account e-mail. This allows you to process the changes in your own systems before they take effect. Also, it allows you to monitor your assortment for impact.

You can find the latest Quarterly Release here.

Updates to our datamodel: weekly updates

We continuously change our datamodel and the categorization of our productgroups (the translation of productgroups to categories in the shop). We publish our current datamodel in the shape of the XML datamodel file, weekly. If you have the IT capacity, this allows you to process the changes almost as soon as they take effect.

You can find the latest datamodel here.

More questions? 

Find more answers to your questions at our Partner Platform., or contact Partnerservices.

 

 

 

bol.com Development Center