Product Content API

Content API

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.

The API Reference for developers can be found at: https://api.bol.com/retailer/public/redoc/v4#tag/Content

Logical process flow

Shown below is simplified version of the flow you follow to add or update new content on bol.com.

Step 1 – Get 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.

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.

Step 2 – Post your content using the API

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 content API POST request:

{
   “language”: “nl”,
   “productContents”: [
      {
         “internalReference”: “4007249040657”,
         “attributes”: [
            {
               “id”: “EAN”,
               “values”: [
                  {
                     “value”: “4007249040657”
                  }
               ]
            },
            {
               “id”: “Weight”,
               “values”: [
                  {
                     “value”: “14.5”,
                     “unitId”: “mm”
                  }
               }
            ]
         }
      ]
   }

Step 2.1 Choose language

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 API Reference for more information.

Step 2.2 Choose 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.

Step 2.3 Send basic information

For all content added we need at least 1 piece of information in order to process the data:

  • EAN

Step 2.3a

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 specific 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”
   }
]

 

 

Step 2.4 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”
                  }
               ]
            }
         ]
      }
   ]
}

 

Use POST https://api.bol.com/retailer/content/product to send us your content.

2.5 Send us 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”: [….
         ]
      }
   ]
}

2.6 Send 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”
                  }
               ]
            }
         ]
      }
   ]
}

 

Step 3 – Verify your POST

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.

GET https://api.bol.com/process-status/451896776

{
   “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.

Step 4 – Get your Validation report and fix any problems

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

In this example:

https://api.bol.com/retailer/content/validation-report/704e8b77-1252-4b3a-a479-3b46c0d50ca2

response:

{
   “productContents”: [
      {
         “internalReference”: “mytest01”,
         “status”: “VALIDATED_OK”
      }
   ]
}

In case of a problem you would see:

{
   “productContents”: [
      {
         “internalReference”: “ref0124”,
         “status”: “REJECTED_WITH_ATTRIBUTE_FAILURES”,
         “errorCode”: 1000,
         “errorDescription”: “Unable to create or link the supplied product to a product of bol.com”,
         “rejectedAttributes”: [
            {
               “attributeId”: “Number of USB ports”,
               “errors”: [
                  {
                     “code”: 2006,
                     “description”: “Invalid integer”
                  }
               ]
            },
            {
               “attributeId”: “EAN”,
               “errors”: [
                  {
                     “code”: 2004,
                     “description”: “Incorrect EAN”
                  }
               ]
            }
         ]
      }
   ]
}

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.

 

4.1 Validation Report product-level status types with their 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

 

4.2 The following error codes exist in the validation report.

 

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