Product Content

Product content API

Introduction

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

Logical process flow

Shown below is simplified version of the flow you follow 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 an XML file that contains all bol.com Product Classifications. This file is updated weekly and we recommend importing this file often to stay up to date.

A product Classification is the most basic level to classify a product. It does describe the location of the product in a store or category. It will list products at the level of e.g.:

  • Sneaker

  • Boardgame

  • Gameconsole

  • Etc

In this example, a sneaker, based on it’s other characteristics can end up in either the fashion store or 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.

Per classification the datamodel will show which attributes are applicable to that 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 you product, determine the required attributes and values you wish to send.

The enrichmentLevel

Per attribute the datamodel will show it’s enrichmentLevel value. This determines if the attribute is required to be entered.

  • 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

Based on the classification 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"
                        }
                    ]
                },
                {
                    "id": "Weight",
                    "values": [
                        {
                            "value": "14.5",
                            "unitId": "mm"
                        }
                    ]
                }
            ]
        }
    ]
}

Supported languages

Every upload must first announce the language it will be sending it’s content in. Currently we support Dutch ('nl'), Flemish('nl-BE'), Wallonia ('fr-BE') and French ('fr'). Check the create product content 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 least 1 piece of information in order to process the data:

  • EAN

Entirely new product

Are you sending content for an entirely new product for the bol.com platform? In that case it is also required that you 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 Product Classification attribute. The value you provide is listed as the <name> of the <productType> in the Datamodel.

For example, if you wish to add a cardgame you would provide:

"id": "Product Classification",
"values": [
   {
      "value": "Kaartspel"
   }
]

Build the rest of your response

After providing the very basics, 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 <name> in the datamodel.

Please note that all the <name> 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 cardgame 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:

{
    "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 cardgame. If this had been a new cardgame, a classification would also have needed to be provided. (in addition to all other enrichtmentLevel 0 and 1 attributes!)

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

Sending content in bulk

It is possible to send us content in bulk, please make sure to use a different internal reference for every distinct product.

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

Sending multivalue attributes

For some attributes we accept more than 1 value, you can add several values within this one attribute while sending new content. This is for example used when sending several images describing different views of your product.

{
    "language": "nl",
    "productContents": [
        {
            "internalReference": "MyImages-test",
            "attributes": [
                {
                    "id": "EAN",
                    "values": {
                        "value": "2005050638782"
                    }
                },
                {
                    "id": "Still Image URL",
                    "values": [
                        {
                            "value": "https://myimage.com/example/20050506387821200×1007.jpg"
                        },
                        {
                            "value": "https://myimage.com/example/20050506387821174×1200.jpg"
                        },
                        {
                            "value": "https://myimage.com/example/20050506387821200×1200.jpg"
                        }
                    ]
                }
            ]
        }
    ]
}

Images via the Content API

You can add images to your products via the Content API as primary image or additional image. Every product can be supplied with product information and images from multiple sources (bol.com and/or their partners). The seller dashboard contains a new feature, which makes it possible to ‘label’ images about their appearance. Via the Content API it is not yet possible to add a label to a picture (this will be available in the future). For now, the following process applies to which image is shown on the product page and in which order:

  1. If there are labeled images, these images 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” then 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 (primary/additional image) the quality score is used to order the images for a product.

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 take up to 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 SUCCESS status and an entityId.

Retrieving a validation report

For a successful upload of content you can retrieve a report detailed 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?

  • Currently do not validate images, video’s and PDFs. We only check if the field is an URL.

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

  • Error codes for all errors (see table 2 below)

  • Note: The validation report is available for 28 days. After this period, you cannot retrieve the validation report anymore.

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

99999

UNKNOWN