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

NameLocationData typeRequiredDescription
productidPathNumberYesThe unique id for one or more products (comma separated).
includeattributesQueryTextNoReturn 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
offersQueryTextNoall, 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
formatQueryTextNojson (default): the response is returned in JSON. xml: the response is returned in XML
countryQueryTextNoSignifies 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

200400404500
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

NameLocationData typeRequiredDescription
productidPathNumberYesThe unique id for a product.
formatQueryTextNojson (default): the response is returned in JSON. xml: the response is returned in XML
offersQueryTextNoall, 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
countryQueryTextNoSignifies 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

200400404500
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/lists/?ids={categoryid}

parameters

NameLocationData typeRequiredDescription
idsQueryNumberYesThe 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.
dataoutputQueryTextNochoose to return refinements, categories, and or products. Mutiple values are allowed, use comma to separate. Default is products.
sortQuerySorting methodNoThe way the products are sorted, e.g., by price.
offersQueryTextNoall, 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
limitQueryNumberNoNumber of products that is returned by the operation. The default is 10 products
offsetQueryNumberNoThe 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.
includeattributesQueryTextNoReturn 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
listidQueryNumberNoThe ID of a specific list
formatQueryNumberNojson (default): the response is returned in JSON. xml: the response is returned in XML
countryQueryTextNoSignifies whether the shopping context is Dutch (NL; default) or Belgium (BE). This can influence search ranking, and whether some products and offers are returned
retailidQueryNumberNoA 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

200400404500
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

NameLocationData typeRequiredDescription
productidPathNumberYesThe product ID for which the recommendations are given
includeattributesQueryBooleanNoReturn 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.
offersQueryBooleanNoall, 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
limitQueryNumberNoRequest a number of recommendations that will be returned. Note that the max products is 20, but fewer recommendations may be available. Default is 10.
offsetQueryNumberNoSkip the first n recommendations.
formatQueryTextNojson (default): the response is returned in JSON. xml: the response is returned in XML
countryQueryTextNoSignifies 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

200400404500
An array of productsBad 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

NameLocationData typeRequiredDescription
datasetQueryTextNouse ‘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’
formatQueryTextNojson (default): the response is returned in JSON. xml: the response is returned in XML
countryQueryBooleanNoSignifies 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

200400404500
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

NameLocationData typeRequiredDescription
----No data is required

responses

200500
“Hello world!” messageInternal Server Error – The server could not understand the request

Definitions

AttributeGroup

AttributeMinMaxData typeRequiredDescription
Attributes1-EntryYesA list of attributes that are logically grouped together, e.g, System Requirements
Title11TextYesThe name of the group, e.g., System Requirements

Entity

AttributeMinMaxData typeDescription
Id11TextThe ID of the entity.
Value11TextThe value of the entity
Label11TextThe text label for the entity

ParentCategoryPaths

AttributeMinMaxData type
ParentCategories1-ParentCategory

ParentCategoryPath

AttributeMinMaxData typeDescription
id11TextThe id of the parent category
name11TextThe name of the parent category

TrackList

AttributeMinMaxData typeDescription
DiscNumber1-Text
Track1-TrackThe individual tracks

Track

AttributeMinMaxData typeDescription
Title1-TextThe title of the track
TrackNumber1-TrackThe tracknumber of the track

Entry

AttributeMinMaxData typeDescription
Key11TextThe key of the entry.
Value11TextThe value of the entry
Label11TextThe text label for the key

Category

AttributeMinMaxData typeRequiredDescription
id11Number (0 – 512 positions long)YesId of the category
name11TextYesName of the category
ProductCount01NumberNoThe number of products found in the category
Refinements1-RefinementNoCategory Refinements

CategoryRefinement

AttributeMinMaxData typeRequiredDescription
id11Number (0 – 512 positions long)YesId of the category
name11TextYesName of the category
productCount11NumberYesThe number of categories in the refinement

MediaEntry

AttributeMinMaxData typeRequiredDescription
type01TextNoUrl of the ExtraSmall Image
key01TextNoUrl of the Small Image
url01TextNoUrl to the specified medium

Offers

AttributeMinMaxData typeRequiredDescription
Offer1-OfferYesSee definition of Offer
bol.com01NumberNoThe number of bol.com offers for the product
NonProfessionalSellers01NumberNoThe number of non-professional seller offers for the product
ProfessionalSellers01TextNoThe number of professional seller offers for the product

Offer

AttributeMinMaxData typeRequiredDescription
Id01TextNoThe offer ID. This ID is used for adding products to the shopping cart.
Condition01Offer state typeNoThe state the offer is in, e.g. “new”
Price11MoneyYesbol.com price, format 19.95
ListPrice01MoneyNoList price, format 19.95
AvailabilityCode01TextNoAvailability code, e.g. 170
AvailabilityDescription01TextNoAvailability description, e.g. “Op werkdagen voor 21.30 uur besteld, morgen in huis”
Comment01TextNoComments from the seller of the product about the offer
Seller11SellerYesThe seller of the product
bestOffer01BooleanNoTrue if the offer is the best available offer, otherwise not present

OriginalRequest

AttributeMinMaxData typeRequiredDescription
Category11CategoryYesDescribes the category that was requested
Refinement Groups0-RefinementGroupNoDescribes the refinement group and refinements that were requested
RetailId01NumberNocontains the retail id that was requested. The retail id's corresponding category/refinement ids are filtered and not shown in the Original Request.

EntityGroup

AttributeMinMaxData typeRequiredDescription
Id11Number (0 – 512 positions long)YesId of the person
Entities11TextYesName of the person

Product

AttributeMinMaxData typeDescription
Id11Number (9 – 16 positions long)Product Id
Title11TextProduct title
SpecsTag01TextContains one of the following: a product's Author, Artist, Brand, Manufacturer or Publisher.
Subtitle01TextProduct subtitle
ShortDescription11TextShort description of the product
LongDescription11TextLong description of the product
OfferData01OfferDataThe offers of this product
Urls0-EntryThe Urls of this product
Media0-Media EntryThe 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
Attributes0-Attribute GroupFurther details of the product. These are grouped
Promotions0-PromotionPromotions that are applicable for this product
Entities0-Entity
Rating01NumberAverage product rating, scale of 00 –50, respresenting 0 to 5 stars
EAN01NumberThe EAN of the products
GPC01NumberThe GPC classification for the product
Summary01TextA small summary of product data
Tracklists01TracklistTracklist of a cd
AttributeGroups0-AttributeGroupGroups of related attributes
EntityGroups0-EntityGroup
Images0-Media EntryThe cover image of the product in several sizes
ParentCategoryPaths0-ParentCategoryPathThe parentcategory of the product

Seller

AttributeMinMaxData typeRequiredDescription
Id11NumberYesId of the seller
DisplayName11TextYesName of the seller, e.g. “2ehands verkoper Piet”
NumberOfReviews01NumberNoThe number of times the seller is reviewed
OverallRating01NumberNoThe average overall rating
Url01TextNoAn url describing the terms of a 3rd party seller
Logo01TextNoAn url to an image of the logo of the seller
EmailAddress01TextNoThe email address of the seller
PhoneNumber01TextNoThe telephone number of the seller
AddressLine101TextNoContains 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.
AddressLine201TextNoContains 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.
SellerType01TextNoThe type of seller, i.e., bol.com, non professional seller, professional seller
TopSeller01BooleanNoIndicates whether the seller is a topseller
SellerRating01SellerRatingNoThe rating of the seller
RecentReviewCounts01SellerReviewCountsNoCounts of reviews that the seller received in the last three months
allReviewCounts01SellerReviewCountsNoCounts of all reviews the seller received
returnConditions01TextNoSpecific return condition terms that the seller applies
useWarrantyRepairConditions01BooleanNoSignals whether the warrantyConditions and repairConditions apply to this seller
warrantyConditions01TextNoSpecific return warranty terms that the seller applies
repairConditions01TextNoSpecific repair condition terms that the seller applies
approvalPercentage01TextNoPercentage of reviewers that recommended the seller
sellerInformation01TextNoA description of the seller

SellerReviewCounts

AttributeMinMaxData typeRequiredDescription
positiveReviewCount01NumberNoThe number of positive reviews
neutralReviewCount01NumberNoThe number of neutral reviews
negativeReviewCount01NumberNoThe number of negative reviews
totalReviewCount01NumberNoThe total number of reviews

SellerRating

AttributeMinMaxData typeRequiredDescription
ratingMethod01TextNoIndicates whether the rating is based on all available reviews (ALL_REVIEWS) or on the last three months (THREE_MONTHS)
sellerRating01NumberNoThe rating of the seller
productInformationRating01NumberNoThe rating of the seller based on his productinformation
deliveryTimeRating01NumberNoThe rating of the seller based on his delivery time
shippingRating01NumberNoThe rating of the seller based on his shipping performance
serviceRating01NumberNoThe rating of the seller based on his service

RefinementGroup

AttributeMinMaxData typeRequiredDescription
id11NumberYesThe ID of the refinement group. Note that this id cannot be used to refine. Use the IDs of the underlying refinements instead.
name11TextYesThe name of the refinement group, for example “taal” (language).
refinements1-RefinementYesthe refinements in the refinement group
productCount11NumberYesThe number of products in this refinement

ProductRefinement

AttributeMinMaxData typeRequiredDescription
id11NumberYesThe ID of the refinement. Note that this id cannot be used to refine. Use the IDs of the underlying refinements instead.
name11TextYesThe name of the refinement, for example “Engelse Boeken” (English books).
Productcount11NumberYesThe 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

AttributeMinMaxData typeDescription
Description11TextThe description of the applicable promotion
Title11TextThe title of the promotion
Url11TextThe url of a list or page associated with the promotion
UrlText11TextThe text label for the promotion

Productfamily

AttributeMinMaxData typeDescription
Key11TextThe key of the family
Label11TextThe pretty label for the family
ProductFamilyMembers01ProductFamilyMemberThe products that belong to the family

Productfamilymember

AttributeMinMaxData typeDescription
Label11TextThe pretty label for the product
productId11TextThe id of the product

OfferData

AttributeMinMaxData typeDescription
Bol.com11Numberthe number of bol.com offers
NonProfessionalSellers11NumberThe number of nonprofessional seller data
ProfessionalSellers11NumberThe number of 2nd hand offers
Offers0-OfferThe offers for the product

Accessory

AttributeMinMaxData typeDescription
productId11Numberthe number of bol.com offers

BundleItem

AttributeMinMaxData typeRequiredDescription
title11TextYesThe title of the bundle that the item belongs to
type11TextYesDescribes the type of bundle the item belongs to

PricingAdjustment

AttributeMinMaxData typeRequiredDescription
Description11TextYesThe title of the pricing adjustment
amount11MoneyYesThe amount of discount the promotion represents
Revocable11BooleanYesSignifies whether the user can revoce the promotion

ListData

AttributeMinMaxData typeDescription
Products0100ProductsList of products found, max. 100 (with a search on EAN/ISBN this is limited to max 3 results)
TotalResultSize11NumberTotal number of products found by search, before clipping to max 100 products (see element product).
Categories0-ArrayOne 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
RefinementGroups0-RefinementGroupsOne or more groups of refinements that are available to narrow down (refine) the search response.
OriginalRequest01OriginalRequestIf 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

AttributeMinMaxData typeDescription
ProductFamilies0-ProductFamiliesThe productfamilies for the product. See definition of productfamily for details
Accessories0-AccessoriesThe accessories that are available for the product