Product Content API

The Content API is available for all sellers since May 1st 2020.

The product content section of the API can be used to send your product content towards bol.com.

The technical documentation for developers can be found on https://api.bol.com/retailer/public/redoc/v4#tag/Content

Logical process flow

 

1. Get product data model (NOT AVAILABLE VIA THE API)

You can get the product content data model here.

 

2. Post product content according to the data model (endpoint: Post product content)

  • You can use this POST request to deliver content to Bol.com, according to the defined data model (1).
  • After the POST, we will return a response with an id and a status update : PENDING / SUCCESS / FAILURE

Notes:

  • A maximum of 100 products or 1.5 MB can be put in one request
  • Please supply dutch content with `nl` as locale, Nl-nl will not end up on the website. 
  • In order to receive feedback on your uploaded content per product, you must supply an internal reference (internalReference field). This value must be unique per product.

 

3. Request if upload has been successfully processed (endpoint: Get process status by ID)

With the ID you get after posting content (2) you can check if the process is completed (status = SUCCESS). Then you will get an entityId, you can use to retrieve feedback on your uploaded content (4).

Notes:

  • This upload id has a maximum size of 100 characters

 

4. Get validation feedback on the uploaded product content (endpoint: Get validation report)

To retrieve feedback on your upload you can use this GET request. You can use the entityId from the “Get process status by ID” endpoint (3).

The feedback is available as a validation report and 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.

 

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

 

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

Example responses

Example response 1 – Supplied content VALIDATED_OK

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

 

Example response 2 – Supplied Content VALIDATED_WITH_ATTRIBUTE_FAILURES

{
 "productContents": [
  {
   "internalReference": "ref0122",
   "status": "VALIDATED_PRODUCT_WITH_ATTRIBUTE_FAILURES",
   "rejectedAttributes": [
    {
     "attributeId": "Weight",
     "errors": [
      {
       "code": 2014,
       "description": "Invalid unit"
      },
      {
       "code": 2006,
       "description": "Invalid integer"
      }
     ]
    }
   ]
  }
 ]
}

 

Example response 3 – Supplied Content REJECTED

{
 "productContents": [
  {
   "internalReference": "ref0124",
   "status": "REJECTED",
   "errorCode": 1000,
   "errorDescription": "Unable to create or link the supplied product to a product of bol.com"
  }
 ]
}

 

Example response 4 – Supplied Content REJECTED

{
 "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"
      }
     ]
    }
   ]
  }
 ]
}