Conventions

As a general rule in the Marketing Catalog API, products are identified using EANs. EAN is a European standard for identifying products.

Design

As the Marketing Catalog API is only for retrieving information from bol, all endpoints work using GET requests. Affiliates have no way to create, modify or delete product information on our platform.

Including extra information

We included the basic product information in the main getProduct endpoint. A user may request more information by setting include<X> in query parameters. This convention is also followed in the search and lists endpoint.

Extra inclusion parameters

include-specifications

include-seller

include-relevant-categories

include-relevant-refinements

include-image

include-offer

include-rating

Not all inclusions are supported on all endpoints.

If a user cannot get enough information from these endpoints, they make a second request to a more specialised endpoint.

Language

In requests

Some endpoints include text that may vary by language.

In these cases an Accept-Language header is mandatory.

If a product’s information is not available in the requested language, the user will be returned a 406 Not Acceptable status code.

In responses

All responses containing language dependent text will be returned with a Content-Language header. The officially supported language codes of bol are nl, fr, nl-NL, nl-BE and fr-BE.

Attempting to send other codes will result in a 406 Not Acceptable.

Countries

Bol operates in two countries, the Netherlands and Belgium. Different countries may have different products available and different prices for those products. As a result some of our endpoints take a country code as a query parameter.

In these cases the country-code query parameter is mandatory.

The two mentioned countries are NL and BE respectively.

Attempting to send other codes will result in a 400 Bad Request.

Some products will not have offers in one country. In this scenario you may receive a valid response for one country code and a 404 Not Found status code for the other.

Caching

Bol provides product information to affiliates that may be cached. As some product information is more volatile than others it is recommended to not cache it for as long. The recommended cache lifetime of a response will be provided to affiliates through the use of the cache-control response header.

An endpoint’s data may not be appropriate to cache, such as the offer endpoint. In this case we return a response with a cache-control: no cache header. Not having a cache-control header does not mean a response should not be cached. It just means we do not provide a cache recommendation.