Product Content

The Product Content API enables you to create content for existing or new products on bol. It also allows you to keep a track of all the uploaded content for your products.

The Product Content API offers the following endpoints:

Create content for a product: Allows you to create content for products.
Get an upload report by upload id: Allows you to view the upload report of the product content submitted through upload id.

Logical process flow

The diagram below illustrates the steps to perform while adding or updating content for your products on bol:

Figure 1. Product Content flow

Understanding the data model

The data model is a JSON file that contains all the product classifications that are available on the bol platform.

This file is updated daily and it is recommended to import this file often to stay up to date.

The product classifications are manageable sub-sections that helps you to analyse and identify the category of your product in the store. It allows you to arrange your product with a group of similar products that share related characteristics. Some examples of product categories are listed below:

Sneaker
Board game
Game console

For example, a sneaker, based on its characteristics, can be put up in a fashion store, a sports store, or both.

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

The data model clearly defines the attributes applicable to each classification. It defines all the mandatory and optional elements required to create the product content. Additionally, it also explains if a particular value is allowed or the value needs be selected from the predefined list.

Use can use the data model to:

Identify the product classification for your product.
Determine all the required attributes and/or allowed values for your product.
Identify the enrichment level of the attributes.

The table below lists some commonly used terms in the data model and their definitions for your reference.

Table 1. Data model terms and their definitions
Terms used in the data model	Definitions
`chunks`	Specifies the product classification of the product that enables you to identify the specific category of related products that your product belongs to.
`attributes`	Specifies the characteristics of the product.
`lovs`	Specifies the predefined list of values applicable for an attribute. Values that are not on this list will be declined.
`lovid`	Specifies a limited list of allowed values for a particular lov. Values that are not on this list will be declined.
`enrichmentLevel`	Specifies the level where the attribute exists within each chunk. It offers the following levels: Level `0` and `1` - Mandatory for publishing the products on the webshop. Level `2` - Optional.
`condition`	Specifies the condition that needs to be fulfilled for publishing the attribute. For more information, see Conditional attributes.
`distinctiveFeatureIds`	Specifies the attributes that distinguish the products in a product family. For more information, see Distinctive features.
`asset`	Specifies an image or a document related to the product. It can be an image of the product to a manual.
`labels`	Specifies a word that describes an asset. For example, FRONT, SIDE, ON MODEL, MANUAL and ENERGY LABEL.

Conditional attributes

A conditional attribute is a tag used to mark an attribute whose relevance is dependent upon one or more other attributes. Conditional attributes reduce the need to enrich irrelevant attributes thereby saving the overall time needed to enrich a product.

Every product classification category can have a few or many conditional attributes. A mandatory or optional attribute might have a condition applied. This condition is identified as a prerequisite that needs to be fulfilled for a specific attribute to become relevant and deliver content. For example, the attribute diameter is not relevant for a square or rectangular table.

An attribute can have one or multiple conditions. In case of multiple attributes, the attributes are combined with either AND or OR to provide clarity about whether all or any one of the mentioned conditions need to be fulfilled. Additionally, the values per condition are also mentioned.

An example of how the conditions are applied to an attribute is given below:

{
  "id": "Processor Generation",
  "lovId": "Processor Generation",
  "enrichmentLevel": 2,
  "condition": {
    "and": {
      "conditions": [
        {
          "in": {
            "attributeId": "Type of Computer Processor",
            "values": [
              "Intel Core i3",
              "Intel Core i7",
              "Intel Core i5"
            ]
          }
        },
        {
          "notNull": {
            "attributeId": "Processor Codename"
          }
        }
      ]
    }
  }
}

In the aforementioned example, a product belonging to the product classification category of Laptop will have the Processor Generation attribute only when the following conditions are fulfilled:

Processor Codename attribute has a value assigned to it (notNull).
Type of Computer Processor attribute has any one of the following three values defined:
- Intel Core i3
- Intel Core i7
- Intel Core i5

Usage of conditions is not mandatory however is still recommended to prevent redundancy.

Retrieving the data model

Once you have identified your product classification (GPC Code) from the data model, you can now build your JSON payload to send to the Product Content API.

You can select any attributes and assets that you want to send in your request.

For more information on how to create a product content request with demo endpoints, see Product content - Demo Endpoints.

From v6 onwards the productContents model has changed, therefore the product images are no longer a part of the attributes, but are now assets. It is recommended to use the same data model version as your API version.

Creating product content

Step 1 - Selecting the language

In order to proceed with uploading your content request, you first need to specify the language for the supplied content. The supported languages are:

Table 2. Supported Languages
Language Name	Geographic Visibility
`nl`	Netherlands and Dutch-speaking Belgium
`nl-BE`	Dutch-speaking part of Belgium only
`fr`	France and Wallonia
`fr-BE`	Wallonian regions only

Use the nl-BE and fr-BE options only to target Dutch-speaking part of Belgium and Wallonian regions specifically. For more information, see Create product content Redoc.

Step 2 - Specifying the EAN

The EAN is a unique product identifier that you have to supply for each product. EAN is required to process all the content that you send for your products. It is visible on the website and is used to link specific feedback to the uploaded products.

Absence of the EAN attribute will result in unsuccessful upload of the submitted product content. This is notified through the DECLINED processing state of the submitted attribute in the upload report.

Step 3 - Creating content

The product content can be created in the following ways:

For an entirely new product.
For an existing product.

Sending content for an entirely new product on the bol platform requires you to provide the product classification by sending the GPC Code in your request.

To find the exact value of the GPC Code for your product, refer to the id value in the chunks section of the data model. For updating the content of the existing items, you do not need to send any product classification information.

For more information, see the bol.com data model.

Creating content for entirely new product

Search the data model by the product name and use the associated id. For example:

{
  "id": "80006362",
  "name": "Kaartspel"
}

For example, if you wish to add a card game, provide the following value:

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

List all the other attributes and assets that you intend to send. Each attribute is sent as an id and corresponding value(s) combination. The id in the API corresponds to the id in the data model.

All the id elements in the data model are always in English, but the value you provide must be in your specified language.

For example, if you want to update an existing card game by providing the amount of players in the card game, the corresponding API request in the data model is shown below:

{
  "language": "nl",
  "attributes": [
    {
      "id": "EAN",
      "values": [
        {
          "value": "0630509892495"
        }
      ]
    },
    {
      "id": "Maximum Number of Players",
      "values": [
        {
          "value": "2"
        }
      ]
    }
  ],
  "assets": [
    {
      "url": "http://example.com",
      "labels": "FRONT"
    }
  ]
}

For a new card game, you would also need to provide a product classification, in addition to all other enrichmentLevel '0' and '1' attributes as shown below:

{
    "language": "nl",
    "attributes": [
        {
            "id": "EAN",
            "values": [
                {
                    "value": "0630509892495"
                }
            ]
        },
        {
            "id": "GPC Code",
            "values": [
                {
                    "value": "80006362"
                }
            ]
        },
        {
            "id": "Maximum Number of Players",
            "values": [
                {
                    "value": "2"
                }
            ]
        }
    ],
    "assets": [
        {
            "url": "http://example.com",
            "labels": "FRONT"
        }
    ]
}

Sending content for an existing product

The content for an existing product can be updated by sending the content for a group of attributes and assets all at once.

Updating the content for multiple existing products is not supported. You can only update a group of attributes and assets within a single product.

To send the content for a group of attributes and assets, use a different id for every distinct attribute. An example of the API request for sending content for a group of attributes and assets for a single product is shown below:

{
    "language": "nl",
    "attributes": [
        {
            "id": "EAN",
            "values": [
                {
                    "value": "4719072852627"
                }
            ]
        },
        {
            "id": "Number of Cores",
            "values": [
                {
                    "value": "6"
                }
            ]
        },
        {
            "id": "Battery Life",
            "values": [
                {
                    "value": "5"
                }
            ]
        }
    ],
    "assets": [
        {
            "url": "https://example.com/front.jpg",
            "labels": [
                "FRONT"
            ]
        },
        {
            "url": "https://example.com/side.jpg",
            "labels": [
                "SIDE"
            ]
        },
        {
            "url": "https://example.com/size-guide.jpg",
            "labels": [
                "SIZE GUIDE"
            ]
        }
    ]
}

Step 4 - Managing product descriptions, images, videos and documents

Every product on the bol platform can be supplied with product information and assets. The assets include all types of visual content such as images, videos, manuals or other or supporting documents that can be added to the product.

Assets with only valid labels are processed.

Adding product descriptions

Enhance your product descriptions by using HTML tags that beautifully illustrate the uses and benefits of your product. These HTML tags help you to present your descriptions in a visually appealing manner drawing attention to the major points.

Following are the supported HTML tags:

<b> - Formats the text as bold.
<br> - Produces a line break in the text.
<h3> - Defines the third level heading.
<li> - Represents an item in a list.
<ol> - Creates an ordered list.
<ul> - Creates an unordered list.
<p> - Formats the text as standard paragraph or main body text.
<strong> - Highlights a text section as important in terms of content.

All other HTML tags are not supported within the product descriptions and hence will be rejected by the system.

Interpreting the data model for assets

While specifying the assets for your product, it is crucial to provide a correct label to your assets. Labelling allows you to identify the type of asset associated with the product.

The list of valid labels applicable to your product can be found within the specific chunk category of the product in the data model.

The table below describes the fields in the data model that are used to assign labels to your products:

Table 3. Fields within labels
Field name	Interpretation
`id`	Specifies the identifier of the label. For example, `FRONT`, `USP`.
`name`	Specifies the name of the label.
`mediaType`	Specifies the type of media required for the label. For example an `IMAGE`, `PDF` or a `VIDEO`.
`enrichmentLevel`	Specifies the current level of the label based on the publishing requirements of an asset. Level `1` - Specifies that the label and the corresponding asset is mandatory for publishing the associated product. Level `2` - Specifies that the label is optional for publishing the associated product. `Any` - Specifies that any asset with `mediaType` as `IMAGE` is sufficient for publishing the associated product.

Adding labels to products

The examples below mention how to analyse labels and add assets to your products:

Example 1

To add a manual for a laptop in your assortment:

Locate the chunk Laptop (30007661) in the data model.
Navigate to the labels section within the Laptop category.
Locate to the section where id is MANUAL.

{
"id" : "MANUAL",
"name" : "Handleiding",
"mediaType" : "PDF",
"enrichmentLevel" : 2
}

This section provides you all the details for adding a manual to your laptop. The value of the mediaType is PDF, indicating that a PDF file type is required for this asset. The enrichmentlevel 2, indicates that this asset is not mandatory.

For more information on relevant labels for your product, refer to the data model.

Example 2

To add CE MARKING label to a kids playhouse in your assortment:

Locate the chunk Speelhuis (80002674) in the data model.
Navigate to the labels section within the Speelhuis category.
Locate to the section where id is CE Marking.

{
"id" : "CE MARKING",
"name" : "CE Markering",
"mediaType" : "PDF",
"enrichmentLevel" : 1
}

This label signifies that your CE MARKING document should be a PDF file type.

Provide a valid URL with the label CE MARKING within the assets element in the request body of the Create content for a product endpoint. The enrichmentLevel 1 signifies that this asset is mandatory.

For more information on relevant labels for your product, refer to the data model.

Labelling the images

The Product Content API enables you to not only add but also label your product images in various categories. Labelling enables bol to organise the images in an efficient manner resulting in an optimised user-experience.

The image of the product is addressed as an image asset. Each image can have minimum one and maximum two labels each. All the images of your products can be labelled through assets in the request body. Based on the label assigned to an image, its location is determined on the carousel of the product page.

The set of labels may differ based on each chunk category. To identify the relevant labels for your product, refer to the latest data model.

The order determining how the images will be displayed on the product page is given below:

Labelled images are organised based on the product category configuration.
Images without a label are organised in free positions at the carousel based on their quality scores.
If no label has been provided to the images, but the images are provided with the metadata such as, PRIMARY or ADDITIONAL, then these images are organised in the following manner:
- Position 1: Primary image
- Position 2: Additional image
- Position 3: Additional image
Images without a label or metadata for a primary or additional image, use the quality score to organise themselves for a product.

For more information on labelling images, refer to the latest data model.

Adding videos

The video of the product is addressed as a video asset. Videos are relevant for every product regardless of the chunk they belong to. Therefore, the current data model does not include a specific video section in the chunks.

A valid product video must contain the following two elements:

The VIDEO label.
A valid URL pointing directly to a video file.

A YouTube URL is not considered a valid video URL.

Adding CE Marking

Various chunks in the data model require a valid CE MARKING to be present for each product in that chunk. This ensures that the product is safe to use according to European standards.

You can add CE MARKING to your products as an asset. This label is present in the labels section within chunks in the data model.

For more information on how to add this label to your products, refer to the Example 2 explained above.

Absence of a valid CE MARKING will result in the product going offline.

Step 5 - Verifying product content uploads

After creating the content for your product and sending the request, you will receive a response on the Process Status. Use the process-status endpoint to check the status of your request.

The status of the request will change from PENDING to SUCCESS after the provided product content has been saved and the processing has started. An upload report will be created thereafter.

Retrieving a upload report

Once the product content is successfully uploaded, you can also retrieve an upload report.

Due to our asynchronous way of processing content it is recommended to have a threshold of at least one hour prior to requesting the upload report to ensure the completion of the processing.

The upload report offers you:

Indication on the overall status of the upload report.
Detailed processing information per attribute/asset through status and subStatus.
Detailed subStatusDescriptions that describe the status of the provided content element.

For more information on the upload statuses, sub statuses and why the submitted attribute was DECLINED in the upload report, see status and sub status codes.

You can use the insights from the upload report to fix any reported problems and send a new request.

Use the Get an upload report by upload id endpoint and the uploadId you received to fetch the upload report as shown in the example below:

{
    "uploadId": "06488b79-e6c9-4cd7-888b-79e6c9bcd7db",
    "language": "nl",
    "status": "IN_PROGRESS",
    "attributes": [
        {
            "id": "EAN",
            "values": [
                {
                    "value": "0630509892495"
                }
            ],
            "status": "PUBLISHED",
            "subStatus": "VALID_EAN",
            "subStatusDescription": "EAN is valid."
        },
        {
            "id": "GPC Code",
            "values": [
                {
                    "value": "80006362"
                }
            ],
            "status": "DECLINED",
            "subStatus": "REJECTED",
            "subStatusDescription": "The system has opted for the product information of others."
        },
        {
            "id": "Maximum Number of Players",
            "values": [
                {
                    "value": "2"
                }
            ],
            "status": "DECLINED",
            "subStatus": "IDENTICAL_VALUE_AS_BEFORE",
            "subStatusDescription": "No change detected."
        }
    ]
}

The upload report is available only for 28 days. After this period, you cannot retrieve the report. Once all the content changes have been processed, the status of each element will be either PUBLISHED or DECLINED and later the status of the upload report will change to COMPLETED.