Marketing Catalog API (1.3.0)

Download OpenAPI specification:

The Marketing Catalog API is an API consumed by affiliate partners. It provides affiliates with information about bol's catalog of products.

Products

Get information about a product.

path Parameters

ean

required

string (EAN) = 13 characters ^\d{13}$

Example: 0842776106209

The European Article Number, a 13 digit unique number identifying the product.

query Parameters

country-code required	string (CountryCode) Enum: "NL" "BE" Example: country-code=NL The country in which the product should have an offer.
include-specifications	boolean (IncludeSpecifications) Default: false Example: include-specifications=true Whether the product specifications should be included in the response.
include-image	boolean (IncludeImage) Default: false Example: include-image=true Whether the main product image should be included in the response.
include-offer	boolean (IncludeOffer) Default: false Example: include-offer=true Whether the best offer for the product should be included in the response.
include-rating	boolean (IncludeRating) Default: false Example: include-rating=true Whether the average rating of the product should be included in the response.

header Parameters

Accept-Language

required

string (AcceptLanguageParam)

Enum: "nl" "fr" "nl-NL" "nl-BE" "fr-BE"

Example: nl

The desired language of the result.

Responses

Response samples

Content type

application/json

{"ean": "0842776106209",
"bolProductId": 9200000099487092,
"title": "string",
"description": "string",
"url": "string",
"image": {"mimeType": "string",
"width": 0,
"height": 0,
"url": "string"
},
"rating": 4.55,
"offer": {"price": 6.99,
"strikethroughPrice": 9.45,
"deliveryDescription": "Op voorraad. Voor 23:59 besteld, morgen in huis"
},
"gpc": [{"level": 10005167,
"name": "Led-strip"
}
],
"specificationGroups": [{"title": "Geheugen",
"specifications": [{"key": "Internal Memory",
"name": "Intern geheugen",
"values": "16 GB"
}
]
}
]
}

Get the best offer for a product.

path Parameters

ean

required

string (EAN) = 13 characters ^\d{13}$

Example: 0842776106209

The European Article Number, a 13 digit unique number identifying the product.

query Parameters

country-code required	string (CountryCode) Enum: "NL" "BE" Example: country-code=NL The country in which the product should have an offer.
include-seller	boolean (IncludeSeller) Default: false Example: include-seller=true Whether the seller related to this offer should be included in the response.

header Parameters

Accept-Language

required

string (AcceptLanguageParam)

Enum: "nl" "fr" "nl-NL" "nl-BE" "fr-BE"

Example: nl

The desired language of the result.

Responses

Response samples

Content type

application/json

{"ean": "0842776106209",
"countryCode": "NL",
"condition": "NEW",
"isPreOrder": true,
"price": 6.99,
"strikethroughPrice": 9.45,
"ultimateOrderTime": "23:59",
"minDeliveryDate": "2023-08-17",
"maxDeliveryDate": "2023-08-18",
"deliveryDescription": "Op voorraad. Voor 23:59 besteld, morgen in huis",
"url": "string",
"releaseDate": "2023-10-28",
"seller": {"name": "string"
}
}

Get the media for a product.

path Parameters

ean

required

string (EAN) = 13 characters ^\d{13}$

Example: 0842776106209

The European Article Number, a 13 digit unique number identifying the product.

Responses

Response samples

200
400
404
500
503

Content type

application/json

{"ean": "0842776106209",
"images": [{"order": 0,
"mimeType": "string",
"renditions": [{"width": 0,
"height": 0,
"url": "string"
}
]
}
]
}

Get an average rating and rating distribution for a product.

path Parameters

ean

required

string (EAN) = 13 characters ^\d{13}$

Example: 0842776106209

The European Article Number, a 13 digit unique number identifying the product.

Responses

Response samples

200
400
404
500
503

Content type

application/json

{"ean": "0842776106209",
"averageRating": 4.55,
"ratings": [{"rating": 1,
"count": 0
},
{"rating": 1,
"count": 0
},
{"rating": 1,
"count": 0
},
{"rating": 1,
"count": 0
},
{"rating": 1,
"count": 0
}
]
}

Get the categories the product is placed in.

Get the categories the product is placed in on the bol website.

path Parameters

ean

required

string (EAN) = 13 characters ^\d{13}$

Example: 0842776106209

The European Article Number, a 13 digit unique number identifying the product.

header Parameters

Accept-Language

required

string (AcceptLanguageParam)

Enum: "nl" "fr" "nl-NL" "nl-BE" "fr-BE"

Example: nl

The desired language of the result.

Responses

Response samples

Content type

application/json

{"ean": "0842776106209",
"categories": [{"categoryId": 4770,
"categoryName": "Laptops",
"productCount": 0,
"subcategories": [{ }
]
}
]
}

Get the variants of the given product.

Get the variants of the given product. These variants are grouped under a key, e.g. the color or size of a shoe.

path Parameters

ean

required

string (EAN) = 13 characters ^\d{13}$

Example: 0842776106209

The European Article Number, a 13 digit unique number identifying the product.

query Parameters

country-code

required

string (CountryCode)

Enum: "NL" "BE"

Example: country-code=NL

The country in which variants are available.

header Parameters

Accept-Language

required

string (AcceptLanguageParam)

Enum: "nl" "fr" "nl-NL" "nl-BE" "fr-BE"

Example: nl

The desired language of the result.

Responses

Response samples

Content type

application/json

{"variantGroups": [{"key": "Colour",
"name": "Kleur",
"variants": [{"ean": "0842776106209",
"label": "Blauw"
}
]
}
]
}

Get the recommended products based on the given product.

path Parameters

ean

required

string (EAN) = 13 characters ^\d{13}$

Example: 0842776106209

The European Article Number, a 13 digit unique number identifying the product.

Responses

Response samples

200
400
404
500
503

Content type

application/json

{"recommendedProducts": ["0842776106209"
]
}

Search for products.

Search for products by search term (mandatory), category id and refinements. If specified via the include-relevant-categories and include-relevant-refinements parameters, the response will contain extra information about respectively the relevant categories and refinements.

query Parameters

search-term required	string non-empty Example: search-term=hp The term to search for. Multiple terms can be used by separating by space.
category-id	string (CategoryId) non-empty Example: category-id=4770 The category in which the products must be located.
refinement	Array of strings[ items non-empty ] Example: refinement=4283589652 The refinement which is used to refine the results. These correspond with the refinements used on the bol website. The available refinement values can be obtained from the 'allRelevantRefinements' section of the response of the /products/search endpoint. Example: '4283589652' (Intel Core i5).
range-refinement	Array of strings[ items >= 3 characters ] Example: range-refinement=16699:3:5 The range refinement which is used to refine the results by a given range. These correspond with the range refinements used on the bol website. The available refinement values can be obtained from the 'allRelevantRefinements' section of the response of the /products/search endpoint. A range refinement must be in the form '$refinementId:($min):($max)'. One well-known range refinement is the ratings slider. Example: '16699:3:5' (products with a rating between 3 and 5 stars).
country-code required	string (CountryCode) Enum: "NL" "BE" Example: country-code=NL The country in which the product should have an offer.
page	integer >= 1 Default: 1 The page number for a paginated query.
page-size	integer [ 1 .. 50 ] Default: 24 The desired number of items per page for a paginated query.
sort	string (Sort) Default: "RELEVANCE" Enum: "RELEVANCE" "POPULARITY" "PRICE_ASC" "PRICE_DESC" "RELEASE_DATE" "RATING" The sorting order that the results should be returned in.
include-relevant-categories	boolean (IncludeRelevantCategories) Default: false Example: include-relevant-categories=true Whether the categories for this search response should be included in the response.
include-relevant-refinements	boolean (IncludeRelevantRefinements) Default: false Example: include-relevant-refinements=true Whether the refinements for this search response should be included in the response.
include-image	boolean (IncludeImage) Default: false Example: include-image=true Whether the main product image should be included in the response.
include-offer	boolean (IncludeOffer) Default: false Example: include-offer=true Whether the best offer for the product should be included in the response.
include-rating	boolean (IncludeRating) Default: false Example: include-rating=true Whether the average rating of the product should be included in the response.

header Parameters

Accept-Language

required

string (AcceptLanguageParam)

Enum: "nl" "fr" "nl-NL" "nl-BE" "fr-BE"

Example: nl

The desired language of the result.

Responses

Response samples

200
400
406
500
503

Content type

application/json

{"page": 0,
"resultsPerPage": 0,
"totalPages": 0,
"totalResults": 0,
"results": [{"ean": "0842776106209",
"bolProductId": 9200000099487092,
"title": "string",
"description": "string",
"url": "string",
"image": {"mimeType": "string",
"width": 0,
"height": 0,
"url": "string"
},
"rating": 4.55,
"offer": {"price": 6.99,
"strikethroughPrice": 9.45,
"deliveryDescription": "Op voorraad. Voor 23:59 besteld, morgen in huis"
},
"gpc": [{"level": 10005167,
"name": "Led-strip"
}
],
"specificationGroups": [{"title": "Geheugen",
"specifications": [{"key": "Internal Memory",
"name": "Intern geheugen",
"values": "16 GB"
}
]
}
]
}
],
"allRelevantCategories": [{"categoryId": 4770,
"categoryName": "Laptops",
"productCount": 0,
"subcategories": [{ }
]
}
],
"allRelevantRefinements": {"refinements": [{"name": "string",
"values": [{"id": "string",
"name": "string"
}
]
}
],
"rangeRefinements": [{"id": "string",
"name": "string",
"min": 0,
"max": 0,
"unit": "sterren"
}
]
}
}

Get the most popular products.

Get the most popular products based on the supplied category id and refinements.

query Parameters

category-id	string (CategoryId) non-empty Example: category-id=4770 The category in which the products must be located.
refinement	Array of strings[ items non-empty ] Example: refinement=4283589652 The refinement which is used to refine the results. These correspond with the refinements used on the bol website. The available refinement values can be obtained from the 'allRelevantRefinements' section of the response of the /products/search endpoint. Example: '4283589652' (Intel Core i5).
range-refinement	Array of strings[ items >= 3 characters ] Example: range-refinement=16699:3:5 The range refinement which is used to refine the results by a given range. These correspond with the range refinements used on the bol website. The available refinement values can be obtained from the 'allRelevantRefinements' section of the response of the /products/search endpoint. A range refinement must be in the form '$refinementId:($min):($max)'. One well-known range refinement is the ratings slider. Example: '16699:3:5' (products with a rating between 3 and 5 stars).
country-code required	string (CountryCode) Enum: "NL" "BE" Example: country-code=NL The country in which the product should have an offer.
page	integer >= 1 Default: 1 The page number for a paginated query.
page-size	integer [ 1 .. 50 ] Default: 24 The desired number of items per page for a paginated query.
include-relevant-categories	boolean (IncludeRelevantCategories) Default: false Example: include-relevant-categories=true Whether the categories for this search response should be included in the response.
include-relevant-refinements	boolean (IncludeRelevantRefinements) Default: false Example: include-relevant-refinements=true Whether the refinements for this search response should be included in the response.
include-image	boolean (IncludeImage) Default: false Example: include-image=true Whether the main product image should be included in the response.
include-offer	boolean (IncludeOffer) Default: false Example: include-offer=true Whether the best offer for the product should be included in the response.
include-rating	boolean (IncludeRating) Default: false Example: include-rating=true Whether the average rating of the product should be included in the response.

header Parameters

Accept-Language

required

string (AcceptLanguageParam)

Enum: "nl" "fr" "nl-NL" "nl-BE" "fr-BE"

Example: nl

The desired language of the result.

Responses

Response samples

200
400
406
500
503

Content type

application/json

{"page": 0,
"resultsPerPage": 0,
"totalPages": 0,
"totalResults": 0,
"results": [{"ean": "0842776106209",
"bolProductId": 9200000099487092,
"title": "string",
"description": "string",
"url": "string",
"image": {"mimeType": "string",
"width": 0,
"height": 0,
"url": "string"
},
"rating": 4.55,
"offer": {"price": 6.99,
"strikethroughPrice": 9.45,
"deliveryDescription": "Op voorraad. Voor 23:59 besteld, morgen in huis"
},
"gpc": [{"level": 10005167,
"name": "Led-strip"
}
],
"specificationGroups": [{"title": "Geheugen",
"specifications": [{"key": "Internal Memory",
"name": "Intern geheugen",
"values": "16 GB"
}
]
}
]
}
],
"allRelevantCategories": [{"categoryId": 4770,
"categoryName": "Laptops",
"productCount": 0,
"subcategories": [{ }
]
}
],
"allRelevantRefinements": {"refinements": [{"name": "string",
"values": [{"id": "string",
"name": "string"
}
]
}
],
"rangeRefinements": [{"id": "string",
"name": "string",
"min": 0,
"max": 0,
"unit": "sterren"
}
]
}
}

Converter

Converts a given bolProductId to EAN.

path Parameters

bolProductId

required

string (BolProductId)

Example: 9200000099487092

The bol product ID.

Responses

Response samples

200
400
404
500
503

Content type

application/json

{"ean": "0842776106209"
}