Product Content

The product content section of the API can be used to send your product content information to bol.com. It will eventually fully replace the Content FTP option. For new connections we recommend only using the Content API.

Product content API endpoints

Logical process flow

The diagram below illustrates a simplified version of the flow you will use to add or update new content on bol.com:

Product content flow
Figure 1. Product content flow

Retrieve the datamodel

The bol.com datamodel is a JSON file that contains all bol.com product classifications. This file is updated daily and we recommend importing this file often to stay up to date.

A product classification is the most basic level for classifying a product. It describes the location of the product in a store or category. It will list products at the level of, for example…​

  • Sneaker

  • Board game

  • Game console

  • Etc

In this example a sneaker, based on its other characteristics, can end up in the fashion store, the sports store, or both.

The datamodel contains all 4000+ classifications available on the bol.com platform. They are listed in alphabetic order and are not grouped by store or category.

The datamodel will show which attributes are applicable to each classification. It will also show if the attribute is required and if it allows any value or if a value must be selected from a predefined list.

Use the datamodel to find the correct classification for your product and determine the required attributes and values you wish to send.

The enrichmentLevel value

The datamodel will show the enrichmentLevel for each value per attribute. This determines if the attribute is required.

  • enrichmentLevel 0 and 1 are required. Without this the product will not be shown on the webshop.

  • enrichmentLevel 2 and 3 are optional.

Creating content

From v6 the productContents model has changed, so that product images are no longer part of the attributes, but are now assets. If you upload any images using the v6 datamodel without migrating up to the v6 API, the images will not appear. If you are on v6 and use the v5 datamodel, you can still add images using the old method for now, but we will eventually deprecate it and we ask that you migrate your image model as soon as possible.

Based on the classification (GPC code) you have selected from the datamodel you can build your JSON/XML payload to send to the Content API.

You select only the attributes that you want to send and use these in your request.

An example of a create product content request:

{
    "language": "nl",
    "productContents": [
        {
            "internalReference": "4007249040657",
            "attributes": [
                {
                    "id": "EAN",
                    "values": [
                        {
                            "value": "4007249040657"
                        }
                    ]
                  }
                ],
            "assets": [
            {
              "url": "http://my.image.com/1234.jpg",
              "labels": [
              "primary, front"
              ]
            }
          ]
        }
}

Supported languages

Every upload must first announce the language it will be sending its content in. Currently we support Dutch (nl), Flemish(nl-BE), Wallonia (fr-BE), and French (fr).

  • French content in the fr locale will be visible in France and Wallonia, while the locale fr-BE is specific to Wallonia. Therefore, you are recommended to use fr instead of fr-BE unless you are targeting only that region.

  • The nl locale will show content to both the Netherlands and Dutch-speaking Belgium, while nl-BE will be specific to the Dutch-speaking part of Belgium.

Check the create product content reference for more information.

Internal reference

The internal reference is the unique product identifier which you have to supply for each product. This could be the product EAN or your own custom product identifier. This value is not shown on the site, but is used to link specific feedback to the uploaded products. Failing to provide an internal reference will result in an error.

Basic product information

For all content added we need at minimum the EAN to process the data. When you are sending content for an entirely new product you are also required to provide the classification by sending the GPC code.

Entirely new product

Are you sending content for an entirely new product for the bol.com platform? In that case you are also required to provide the classification when sending content for the first time.

If you are updating content for existing items, you do not need to send any classification information.

You can specify the classification by setting the GPC Code attribute. The value you provide is listed either:

  • As the id in the chunks attribute in the JSON datamodel

  • Or the chunkId of the productType in the XML datamodel.

For more information see the bol.com datamodel.

Search the datamodel by product name and use the associated ID. For example:

{
  "id" : "30000924",
  "name" : "Nagelknipper",
}

For example, if you wish to add a card game you should provide:

"id": "GPC Code",
"values": [
   {
      "value": "80006362"
   }
]

Build the rest of your response

After providing the basic data, you can now list all the other attributes that you intend to send. Each attribute is send as an ID / value combination.

The ID in the API corresponds to the ID in the datamodel.

Please note that all the ID elements in the datamodel are always in English, but the value you provide must always be in the language you specified.

For example, when adding a card game you could provide the amount of players.

The datamodel will show:

<attribute>
    <name>Maximum Number of Players</name>
    <label>Maximaal aantal spelers</label>
    <multiValue>false</multiValue>
    <attributeDefinition>Wat is het maximaal aantal spelers? Indien dit attribuut niet relevant is, vul een 0 in.</attributeDefinition>
    <enrichmentLevel>1</enrichmentLevel>
    <validation>
        <baseType>number</baseType>
    </validation>
</attribute>

The corresponding API request will look like this:

{
    "language": "nl",
    "productContents": [
        {
            "internalReference": "0630509892495",
            "attributes": [
                {
                    "id": "EAN",
                    "values": [
                        {
                            "value": "0630509892495"
                        }
                    ]
                },
                {
                    "id": "Maximum Number of Players",
                    "values": [
                        {
                            "value": "2"
                        }
                    ]
                }
            ]
        }
    ]
}

In this case you are updating an existing card game. If this had been a new card game, a classification would also need to have been provided, in addition to all other enrichmentLevel '0' and '1' attributes.

{
   "language": "nl",
   "productContents": [
      {
         "internalReference": "0630509892495",
         "attributes": [
            {
               "id": "EAN",
               "values": [
                  {
                     "value": "0630509892495"
                  }
               ]
            },
            {
               "id": "GPC Code",
               "values": [
                  {
                     "value": "Kaartspel"
                  }
               ]
            },
            {
               "id": "Maximum Number of Players",
               "values": [
                  {
                     "value": "2"
                  }
               ]
            }
         ]
      }
   ]
}

Sending content in bulk

To send content in bulk, please use a different internal reference for every distinct product.

{
   "language": "nl",
   "productContents": [
      {
         "internalReference": "mytest01",
         "attributes": [
           ...
         ]
      },
      {
         "internalReference": "mytest02",
         "attributes": [
           ...
         ]
      }
   ]
}

For information on creating product families with bulk uploads, see Creating product families.

Managing images via the Content API

You can add images to your products via the Content API as primary or additional images. Every product can be supplied with product information and images from multiple sources, such as bol.com and/or partners. Images are added through assets as part of the productContents.

Labeling images

Images can be labeled as part of the image asset. Images take at least 1 and up to 2 labels each, and the labels determine how the images appear on the carousel of the product page. For more information about how to apply labels to an image, refer to the current datamodel. The following process applies to determining the order in which images are shown on the product page:

  1. If there are labeled images, they are placed in the order based on the product category configuration. Images without a label will be placed in the free positions in the carousel based on the known position or quality score.

  2. If no label has been linked to the images, but the images have been supplied with the metadata Primary and/or additional image, this information is used to order the images (position 1: primary, position 2: additional image, position 3: additional image).

  3. When delivering the images without a label or metadata for a primary or additional image, the quality score is used to order the images for a product.

The following example shows how to add multiple labeled images to a product:

{
    "language": "nl",
    "productContents": [
        {
            "internalReference": "MyImages-test",
            "attributes": [
                {
                    "id": "EAN",
                    "values": [
                    {
                        "value": "2005050638782"
                    }
                  ]
                }
              ],
      "assets": [
      {
        "url": "https://myimage.com/example/20050506387821200×1007.jpg",
        "labels": ["front"]
      },
      {
        "url": "https://myimage.com/example/20050506387821174×1200.jpg",
        "labels": ["second"]
      },
      {
        "url": "https://myimage.com/example/20050506387821200×1200.jpg",
        "labels": ["third"]
      }
    ]
    }
  ]
}

Verifying product content posts

Like all requests in the bol.com Retailer API, your content POST is also added to our queue. After posting you will receive a process status response.

{
   “id”: 451896776,
   “eventType”: “CREATE_PRODUCT_CONTENT”,
   “description”: “Create content for products.”,
   “status”: “PENDING”,
   “createTimestamp”: “2020-06-30T14:02:22+02:00”,
   “links”: [
      {
         “rel”: “self”,
         “href”: “https://api.bol.com/retailer/process-status/451896776”,
         “method”: “GET”
      }
   ]
}

Use the process-status endpoint to check the status of your request. At first it will always have status PENDING. This will change after it was successfully processed, which can possibly take several minutes.

{
   “id”: 451896776,
   “entityId”: “704e8b77-1252-4b3a-a479-3b46c0d50ca2”,
   “eventType”: “CREATE_PRODUCT_CONTENT”,
   “description”: “Create content for products.”,
   “status”: “SUCCESS”,
   “createTimestamp”: “2020-06-30T14:02:22+02:00”
}

If the upload is successful you will receive a SUCCESS status and an entityId.

Retrieving a validation report

For a successful upload of content you can retrieve a report detailing all successful added attributes but also all the problems we encountered. You can use this report to fix any reported problems and send a new request.

Use the get validation request endpoint and the entityID you received to fetch the report.

response:

{
   "productContents": [
      {
         "internalReference": "mytest01",
         "status": "VALIDATED_OK"
      }
   ]
}

In case of a problem you would see:

{
    "productContents": [
        {
            "internalReference": "internalReference123",
            "rejectedAttributes": [
                {
                    "attributeId": "Weight",
                    "rejectionErrors": [
                        {
                            "code": 2014,
                            "message": "Invalid unit"
                        },
                        {
                            "code": 2005,
                            "message": "Invalid number"
                        }
                    ]
                }
            ],
            "status": "VALIDATED_WITH_ATTRIBUTE_FAILURES"
        }
    ]
}

The validation report consists of:

  • Validation information for all uploaded products: was your uploaded content accepted by bol.com?

  • Validation status on the product level (see table 1)

  • Error codes for all errors (see table 2)

Currently we do not validate images, videos and PDFs. We only check if the field is an URL.
The validation report is available for 28 days. After this period, you can no longer retrieve the validation report.

Validation Report product-level status types with their meaning

Table 1. Product level status and meaning.
Product-level status Meaning

VALIDATED_OK

The product has passed the validation with zero errors

VALIDATED_WITH_ATTRIBUTE_FAILURES

The product has passed the validation and the attributes that have failures won’t be processed

REJECTED

The product is rejected and no validation errors are given

REJECTED_WITH_ATTRIBUTE_FAILURES

The product is rejected and validation errors are given back

Validation report error codes

Table 2. Validation report error codes
Error codes Meaning

1000

Whole product rejected

2000

unknown attribute error

2001

Invalid multiple values

2002

Attribute ID does not exist

2003

Invalid numeric text

2004

Invalid EAN

2005

Invalid number

2006

Invalid integer

2007

Invalid isodate

2008

Invalid isodatetime

2009

Invalid URL

2010

Invalid date

2011

Invalid fraction

2012

Invalid LOV

2013

Unknown basetype

2014

Invalid unit

2015

Invalid text

2016

Invalid values were supplied (empty string or invalid HTML)

2017

No values were supplied for the attribute

2018

Invalid GPC Code

2019

Disabled GPC Code

99999

UNKNOWN