API documentatie

De documentatie van de bol.com API blijft voortdurend in ontwikkeling. Je kunt hier altijd terecht voor de meest recente handleiding, regels en richtlijnen.

Schemes and host

https://api.bol.com

get

/catalog/v4/products/{productId}

The products operation gets detailed information for products.

parameters

Name	Location	Data type	Required	Description
productid	Path	Number	Yes	The unique id for one or more products (comma separated).
includeattributes	Query	Text	No	Return the full set of attributes for the products as key-value pairs. Note that by using the key-value pairs, more attributes are available as key-value pair than as elements. “true”: return key-value pair attributes. “false”: return no key-value pair attributes
offers	Query	Text	No	all, cheapest, secondhand, newoffers, bolcom – default: bestoffer. The parameters can be combined using a comma, for instance offers=cheapest,secondhand returns the cheapest 2nd hand offer. Note that bestoffer returns only the best offer, making further filtering pointless
format	Query	Text	No	json (default): the response is returned in JSON. xml: the response is returned in XML
country	Query	Text	No	Signifies whether the shopping context is Dutch (NL; default) or Belgium (BE). This can influence search ranking, and whether some products and offers are returned

responses

200	400	404	500
The complete information of a product.	Bad request - The request was incorrect. Please check the Developer Guide to correct the request.	Unauthorized - There was an error obtaining authorization or authentication. This might be caused by incorrect Hmac headers.	Internal Server Error – The server could not understand the request

get

/catalog/v4/offers/{productId}

The offers operation returns the available offers for a given product

parameters

Name	Location	Data type	Required	Description
productid	Path	Number	Yes	The unique id for a product.
format	Query	Text	No	json (default): the response is returned in JSON. xml: the response is returned in XML
offers	Query	Text	No	all, cheapest, secondhand, newoffers, bolcom – default: bestoffer. The parameters can be combined using a comma, for instance offers=cheapest,secondhand returns the cheapest 2nd hand offer. Note that bestoffer returns only the best offer, making further filtering pointless
country	Query	Text	No	Signifies whether the shopping context is Dutch (NL; default) or Belgium (BE). This can influence search ranking, and whether some products and offers are returned

responses

200	400	404	500
The offers of a product.	Bad request - The request was incorrect. Please check the Developer Guide to correct the request.	Unauthorized - There was an error obtaining authorization or authentication. This might be caused by incorrect Hmac headers.	Internal Server Error – The server could not understand the request

get

/catalog/v4/search

The searchresults operation returns product information by supplying keywords or ISBN/EAN. The operation has filtering and paging options.

parameters

Name	Location	Data type	Description
q	Query	Text	The search query, e.g., “Harry Potter” should return. This can be one or more keywords or an EAN/ISBN.
pids	Query	Number	You can request more than one product at a time by using this parameter.
ids	Query	Number	The category id to use for filtering. More than one id can be provided, separated with a comma (only “1 category + X refinements” can be used to filter.). CategoryId’s can be 1 to 512 characters long. Most of the time, they are 4 or 10 characters long. Example: 87,8293. Valid id’s can be retrieved with operation GET /catalog/v4/lists with categories and refinemets a dataoutput.
dataoutput	Query	Data Output	choose to return refinements,categories, and or products. Mutiple values are allowed, use comma to separate. Default is products.
offers	Query	Text	all, cheapest, secondhand, newoffers, bolcom, bestoffer – default: bestoffer. The parameters can be combined using a comma, for instance offers=cheapest,secondhand returns the cheapest 2nd hand offer. Note that bestoffer returns only the best offer, making further filtering pointless
sort	Query	Sorting method	The way the products are sorted, e.g., by price.
offset	Query	Number	The number of results to skip before returning any results. This can be used for paging purposes. E.g. offset 3 will skip the first 3 results.
limit	Query	Text	Number of products that is returned by the operation. The default is 10 products
includeattributes	Query	Boolean	Return the full set of attributes for the products as key-value pairs. Note that by using the key-value pairs, more attributes are available as key-value pair than as elements. true: return key-value pair attributes. false: return no key-value pair attributes
format	Query	Text	json (default): the response is returned in JSON. xml: the response is returned in XML
country	Query	Text	Signifies whether the shopping context is Dutch (NL; default) or Belgium (BE). This can influence search ranking, and whether some products and offers are returned

responses

200	400	404	500
The complete information of the request.	Bad request - The request was incorrect. Please check the Developer Guide to correct the request.	Unauthorized - There was an error obtaining authorization or authentication. This might be caused by incorrect Hmac headers.	Internal Server Error – The server could not understand the request

get

/catalog/v4/lists/?ids={categoryid}

parameters

Name	Location	Data type	Required	Description
ids	Query	Number	Yes	The category id to use for filtering. More than one id can be provided, separated with a comma (only “1 category + X refinements” can be used to filter.). CategoryId’s can be 1 to 512 characters long. Most of the time, they are 4 or 10 characters long. Example: 87,8293. Valid id’s can be retrieved with operation GET /catalog/v4/lists with categories and refinemets a dataoutput.
dataoutput	Query	Text	No	choose to return refinements, categories, and or products. Mutiple values are allowed, use comma to separate. Default is products.
sort	Query	Sorting method	No	The way the products are sorted, e.g., by price.
offers	Query	Text	No	all, cheapest, secondhand, newoffers, bolcom – default: bestoffer. The parameters can be combined using a comma, for instance offers=cheapest,secondhand returns the cheapest 2nd hand offer. Note that bestoffer returns only the best offer, making further filtering pointless
limit	Query	Number	No	Number of products that is returned by the operation. The default is 10 products
offset	Query	Number	No	The number of results to skip before returning any results. This can be used for paging purposes. E.g. offset 3 will skip the first 3 results.
includeattributes	Query	Text	No	Return the full set of attributes for the products as key-value pairs. Note that by using the key-value pairs, more attributes are available as key-value pair than as elements. “true”: return key-value pair attributes. “false”: return no key-value pair attributes
listid	Query	Number	No	The ID of a specific list
format	Query	Number	No	json (default): the response is returned in JSON. xml: the response is returned in XML
country	Query	Text	No	Signifies whether the shopping context is Dutch (NL; default) or Belgium (BE). This can influence search ranking, and whether some products and offers are returned
retailid	Query	Number	No	A retail id is defined as a collection of one or more category/refinement id’s. They are often used for promotion campaigns and can be combined with category/refinement id’s for additional filtering if needed. Example url: https://api.bol.com/catalog/v4/lists/?retailid=2991&apikey={apikey}&format=json

responses

200	400	404	500
The complete information of the request.	Bad request - The request was incorrect. Please check the Developer Guide to correct the request.	Unauthorized - There was an error obtaining authorization or authentication. This might be caused by incorrect Hmac headers.	Internal Server Error – The server could not understand the request

get

/catalog/v4/recommendations/{productId}

The recommendation operation returns product IDs or products that are recommended based on an input product id. The operation returns a maximum of 20 recommendations.

parameters

Name	Location	Data type	Required	Description
productid	Path	Number	Yes	The product ID for which the recommendations are given
includeattributes	Query	Boolean	No	Return the full set of attributes for the products as key-value pairs. Note that by using the key-value pairs, more attributes are available as key-value pair than as elements. “true”: return key-value pair attributes. “false”: return no key-value pair attributes. Default is true.
offers	Query	Boolean	No	all, cheapest, secondhand, newoffers, bolcom – default: bestoffer. The parameters can be combined using a comma, for instance offers=cheapest,secondhand returns the cheapest 2nd hand offer. Note that bestoffer returns only the best offer, making further filtering pointless
limit	Query	Number	No	Request a number of recommendations that will be returned. Note that the max products is 20, but fewer recommendations may be available. Default is 10.
offset	Query	Number	No	Skip the first n recommendations.
format	Query	Text	No	json (default): the response is returned in JSON. xml: the response is returned in XML
country	Query	Text	No	Signifies whether the shopping context is Dutch (NL; default) or Belgium (BE). This can influence search ranking, and whether some products and offers are returned

responses

200	400	404	500
An array of products	Bad request - The request was incorrect. Please check the Developer Guide to correct the request.	Unauthorized - There was an error obtaining authorization or authentication. This might be caused by incorrect Hmac headers.	Internal Server Error – The server could not understand the request

get

/catalog/v4/relatedproducts/{productid}

This call returns all related products for a given product

parameters

Name	Location	Data type	Required	Description
dataset	Query	Text	No	use ‘productfamily’ as value to get the related productfamilies (For example a different color of the same product) or ‘accessories’ to get the accessories(For example a memory card for a digital camera). You can also use both (comma separated) to get both, productfamilies and accessories. Default=’productfamily,accessories’
format	Query	Text	No	json (default): the response is returned in JSON. xml: the response is returned in XML
country	Query	Boolean	No	Signifies whether the shopping context is Dutch (NL; default) or Belgium (BE). This can influence search ranking, and whether some products and offers are returned

responses

200	400	404	500
The related products of a given product.	Bad request - The request was incorrect. Please check the Developer Guide to correct the request.	Unauthorized - There was an error obtaining authorization or authentication. This might be caused by incorrect Hmac headers.	Internal Server Error – The server could not understand the request

get

/utils/v4/ping

This utility can be used to test the basic communication. Sending a successful ping will result in a HTTP 200 status response.

parameters

Name	Location	Data type	Required	Description
-	-	-	-	No data is required

responses

200	500
“Hello world!” message	Internal Server Error – The server could not understand the request

Definitions

AttributeGroup

Attribute	Min	Max	Data type	Required	Description
Attributes	1	-	Entry	Yes	A list of attributes that are logically grouped together, e.g, System Requirements
Title	1	1	Text	Yes	The name of the group, e.g., System Requirements

Entity

Attribute	Min	Max	Data type	Description
Id	1	1	Text	The ID of the entity.
Value	1	1	Text	The value of the entity
Label	1	1	Text	The text label for the entity

ParentCategoryPaths

Attribute	Min	Max	Data type
ParentCategories	1	-	ParentCategory

ParentCategoryPath

Attribute	Min	Max	Data type	Description
id	1	1	Text	The id of the parent category
name	1	1	Text	The name of the parent category

TrackList

Attribute	Min	Max	Data type	Description
DiscNumber	1	-	Text
Track	1	-	Track	The individual tracks

Track

Attribute	Min	Max	Data type	Description
Title	1	-	Text	The title of the track
TrackNumber	1	-	Track	The tracknumber of the track

Entry

Attribute	Min	Max	Data type	Description
Key	1	1	Text	The key of the entry.
Value	1	1	Text	The value of the entry
Label	1	1	Text	The text label for the key

CategoryRefinement

Attribute	Min	Max	Data type	Required	Description
id	1	1	Number (0 – 512 positions long)	Yes	Id of the category
name	1	1	Text	Yes	Name of the category
productCount	1	1	Number	Yes	The number of categories in the refinement

MediaEntry

Attribute	Max	Data type	Required	Description
type	1	Text	No	Url of the ExtraSmall Image
key	1	Text	No	Url of the Small Image
url	1	Text	No	Url to the specified medium

Offers

Attribute	Min	Max	Data type	Required	Description
Offer	1	-	Offer	Yes	See definition of Offer
bol.com	0	1	Number	No	The number of bol.com offers for the product
NonProfessionalSellers	0	1	Number	No	The number of non-professional seller offers for the product
ProfessionalSellers	0	1	Text	No	The number of professional seller offers for the product

Offer

Attribute	Min	Max	Data type	Required	Description
Id	0	1	Text	No	The offer ID. This ID is used for adding products to the shopping cart.
Condition	0	1	Offer state type	No	The state the offer is in, e.g. “new”
Price	1	1	Money	Yes	bol.com price, format 19.95
ListPrice	0	1	Money	No	List price, format 19.95
AvailabilityCode	0	1	Text	No	Availability code, e.g. 170
AvailabilityDescription	0	1	Text	No	Availability description, e.g. “Op werkdagen voor 21.30 uur besteld, morgen in huis”
Comment	0	1	Text	No	Comments from the seller of the product about the offer
Seller	1	1	Seller	Yes	The seller of the product
bestOffer	0	1	Boolean	No	True if the offer is the best available offer, otherwise not present

OriginalRequest

Attribute	Min	Max	Data type	Required	Description
Category	1	1	Category	Yes	Describes the category that was requested
Refinement Groups	0	-	RefinementGroup	No	Describes the refinement group and refinements that were requested
RetailId	0	1	Number	No	contains the retail id that was requested. The retail id's corresponding category/refinement ids are filtered and not shown in the Original Request.

EntityGroup

Attribute	Min	Max	Data type	Required	Description
Id	1	1	Number (0 – 512 positions long)	Yes	Id of the person
Entities	1	1	Text	Yes	Name of the person

Product

Attribute	Min	Max	Data type	Description
Id	1	1	Number (9 – 16 positions long)	Product Id
Title	1	1	Text	Product title
SpecsTag	0	1	Text	Contains one of the following: a product's Author, Artist, Brand, Manufacturer or Publisher.
Subtitle	0	1	Text	Product subtitle
ShortDescription	1	1	Text	Short description of the product
LongDescription	1	1	Text	Long description of the product
OfferData	0	1	OfferData	The offers of this product
Urls	0	-	Entry	The Urls of this product
Media	0	-	Media Entry	The cover image of the product in several formats, and additional media that are available for the product. May contain alternative images, patient information leaflet, trailers
Attributes	0	-	Attribute Group	Further details of the product. These are grouped
Promotions	0	-	Promotion	Promotions that are applicable for this product
Entities	0	-	Entity
Rating	0	1	Number	Average product rating, scale of 00 –50, respresenting 0 to 5 stars
EAN	0	1	Number	The EAN of the products
GPC	0	1	Number	The GPC classification for the product
Summary	0	1	Text	A small summary of product data
Tracklists	0	1	Tracklist	Tracklist of a cd
AttributeGroups	0	-	AttributeGroup	Groups of related attributes
EntityGroups	0	-	EntityGroup
Images	0	-	Media Entry	The cover image of the product in several sizes
ParentCategoryPaths	0	-	ParentCategoryPath	The parentcategory of the product

Seller

Attribute	Min	Max	Data type	Required	Description
Id	1	1	Number	Yes	Id of the seller
DisplayName	1	1	Text	Yes	Name of the seller, e.g. “2ehands verkoper Piet”
NumberOfReviews	0	1	Number	No	The number of times the seller is reviewed
OverallRating	0	1	Number	No	The average overall rating
Url	0	1	Text	No	An url describing the terms of a 3rd party seller
Logo	0	1	Text	No	An url to an image of the logo of the seller
EmailAddress	0	1	Text	No	The email address of the seller
PhoneNumber	0	1	Text	No	The telephone number of the seller
AddressLine1	0	1	Text	No	Contains streetname, housenumber and housenumberextension of the return address of the seller. Note that this field can only be returned when a corresponding item has been opted for returns.
AddressLine2	0	1	Text	No	Contains zipcode and city name of the return address of the seller. Note that this field can only be returned when a corresponding item has been opted for returns.
SellerType	0	1	Text	No	The type of seller, i.e., bol.com, non professional seller, professional seller
TopSeller	0	1	Boolean	No	Indicates whether the seller is a topseller
SellerRating	0	1	SellerRating	No	The rating of the seller
RecentReviewCounts	0	1	SellerReviewCounts	No	Counts of reviews that the seller received in the last three months
allReviewCounts	0	1	SellerReviewCounts	No	Counts of all reviews the seller received
returnConditions	0	1	Text	No	Specific return condition terms that the seller applies
useWarrantyRepairConditions	0	1	Boolean	No	Signals whether the warrantyConditions and repairConditions apply to this seller
warrantyConditions	0	1	Text	No	Specific return warranty terms that the seller applies
repairConditions	0	1	Text	No	Specific repair condition terms that the seller applies
approvalPercentage	0	1	Text	No	Percentage of reviewers that recommended the seller
sellerInformation	0	1	Text	No	A description of the seller

SellerReviewCounts

Attribute	Max	Data type	Required	Description
positiveReviewCount	1	Number	No	The number of positive reviews
neutralReviewCount	1	Number	No	The number of neutral reviews
negativeReviewCount	1	Number	No	The number of negative reviews
totalReviewCount	1	Number	No	The total number of reviews

SellerRating

Attribute	Max	Data type	Required	Description
ratingMethod	1	Text	No	Indicates whether the rating is based on all available reviews (ALL_REVIEWS) or on the last three months (THREE_MONTHS)
sellerRating	1	Number	No	The rating of the seller
productInformationRating	1	Number	No	The rating of the seller based on his productinformation
deliveryTimeRating	1	Number	No	The rating of the seller based on his delivery time
shippingRating	1	Number	No	The rating of the seller based on his shipping performance
serviceRating	1	Number	No	The rating of the seller based on his service

RefinementGroup

Attribute	Min	Max	Data type	Required	Description
id	1	1	Number	Yes	The ID of the refinement group. Note that this id cannot be used to refine. Use the IDs of the underlying refinements instead.
name	1	1	Text	Yes	The name of the refinement group, for example “taal” (language).
refinements	1	-	Refinement	Yes	the refinements in the refinement group
productCount	1	1	Number	Yes	The number of products in this refinement

ProductRefinement

Attribute	Min	Max	Data type	Required	Description
id	1	1	Number	Yes	The ID of the refinement. Note that this id cannot be used to refine. Use the IDs of the underlying refinements instead.
name	1	1	Text	Yes	The name of the refinement, for example “Engelse Boeken” (English books).
Productcount	1	1	Number	Yes	The number of products that remain when the search or list is refined with this refinement alone. Note that the productcount from two refinements do not add up due to double counting.

Promotion

Attribute	Min	Max	Data type	Description
Description	1	1	Text	The description of the applicable promotion
Title	1	1	Text	The title of the promotion
Url	1	1	Text	The url of a list or page associated with the promotion
UrlText	1	1	Text	The text label for the promotion

Productfamily

Attribute	Min	Max	Data type	Description
Key	1	1	Text	The key of the family
Label	1	1	Text	The pretty label for the family
ProductFamilyMembers	0	1	ProductFamilyMember	The products that belong to the family

Productfamilymember

Attribute	Min	Max	Data type	Description
Label	1	1	Text	The pretty label for the product
productId	1	1	Text	The id of the product

OfferData

Attribute	Min	Max	Data type	Description
Bol.com	1	1	Number	the number of bol.com offers
NonProfessionalSellers	1	1	Number	The number of nonprofessional seller data
ProfessionalSellers	1	1	Number	The number of 2nd hand offers
Offers	0	-	Offer	The offers for the product

Accessory

Attribute	Min	Max	Data type	Description
productId	1	1	Number	the number of bol.com offers

BundleItem

Attribute	Min	Max	Data type	Required	Description
title	1	1	Text	Yes	The title of the bundle that the item belongs to
type	1	1	Text	Yes	Describes the type of bundle the item belongs to

PricingAdjustment

Attribute	Min	Max	Data type	Required	Description
Description	1	1	Text	Yes	The title of the pricing adjustment
amount	1	1	Money	Yes	The amount of discount the promotion represents
Revocable	1	1	Boolean	Yes	Signifies whether the user can revoce the promotion

ListData

Attribute	Min	Max	Data type	Description
Products	0	100	Products	List of products found, max. 100 (with a search on EAN/ISBN this is limited to max 3 results)
TotalResultSize	1	1	Number	Total number of products found by search, before clipping to max 100 products (see element product).
Categories	0	-	Array	One or more categories in which the found products occur. Category consists of the following elements: - id: the number indicating the category id – name: the category name – productCount: the number of products found in this category
RefinementGroups	0	-	RefinementGroups	One or more groups of refinements that are available to narrow down (refine) the search response.
OriginalRequest	0	1	OriginalRequest	If the request was made within a category or with refinements, this node describes the names and id’s from the categories and refinements from the request

RelatedProducts

Attribute	Min	Max	Data type	Description
ProductFamilies	0	-	ProductFamilies	The productfamilies for the product. See definition of productfamily for details
Accessories	0	-	Accessories	The accessories that are available for the product