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.

get

/catalog/v4/products/{productId}

The products operation gets detailed information for products.

parameters

NameLocationData typeRequiredDescription
"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

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
"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

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
"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

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
"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

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
"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

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"-""Entry""Yes""A list of attributes that are logically grouped together, e.g, System Requirements"
Title11"Text""Yes""The name of the group, e.g., System Requirements"

Entity

AttributeMinMaxData typeDescription
Id11"Text""The ID of the entity."
Value11"Text""The value of the entity"
Label11"Text""The text label for the entity"

ParentCategoryPaths

AttributeMinMaxData type
ParentCategories1"-""ParentCategory"

ParentCategoryPath

AttributeMinMaxData typeDescription
id11"Text""The id of the parent category"
name11"Text""The name of the parent category"

TrackList

AttributeMinMaxData typeDescription
DiscNumber1"-""Text"
Track1"-""Track""The individual tracks"

Track

AttributeMinMaxData typeDescription
Title1"-""Text""The title of the track"
TrackNumber1"-""Track""The tracknumber of the track"

Entry

AttributeMinMaxData typeDescription
Key11"Text""The key of the entry."
Value11"Text""The value of the entry"
Label11"Text""The text label for the key"

Category

AttributeMinMaxData typeRequiredDescription
id11"Number (0 – 512 positions long)""Yes""Id of the category"
name11"Text""Yes""Name of the category"
ProductCount01"Number""No""The number of products found in the category"
Refinements1"-""Refinement""No""Category Refinements"

CategoryRefinement

AttributeMinMaxData typeRequiredDescription
id11"Number (0 – 512 positions long)""Yes""Id of the category"
name11"Text""Yes""Name of the category"
productCount11"Number""Yes""The number of categories in the refinement"

MediaEntry

AttributeMinMaxData typeRequiredDescription
type01"Text""No""Url of the ExtraSmall Image"
key01"Text""No""Url of the Small Image"
url01"Text""No""Url to the specified medium"

Offers

AttributeMinMaxData typeRequiredDescription
Offer1"-""Offer""Yes""See definition of Offer"
bol.com01"Number""No""The number of bol.com offers for the product"
NonProfessionalSellers01"Number""No""The number of non-professional seller offers for the product"
ProfessionalSellers01"Text""No""The number of professional seller offers for the product"

Offer

AttributeMinMaxData typeRequiredDescription
Id01"Text""No""The offer ID. This ID is used for adding products to the shopping cart."
Condition01"Offer state type""No""The state the offer is in, e.g. “new”"
Price11"Money""Yes""bol.com price, format 19.95"
ListPrice01"Money""No""List price, format 19.95"
AvailabilityCode01"Text""No""Availability code, e.g. 170"
AvailabilityDescription01"Text""No""Availability description, e.g. “Op werkdagen voor 21.30 uur besteld, morgen in huis”"
Comment01"Text""No""Comments from the seller of the product about the offer"
Seller11"Seller""Yes""The seller of the product"
bestOffer01"Boolean""No""True if the offer is the best available offer, otherwise not present"

OriginalRequest

AttributeMinMaxData typeRequiredDescription
Category11"Category""Yes""Describes the category that was requested"
Refinement Groups0"-""RefinementGroup""No""Describes the refinement group and refinements that were requested"
RetailId01"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

AttributeMinMaxData typeRequiredDescription
Id11"Number (0 – 512 positions long)""Yes""Id of the person"
Entities11"Text""Yes""Name of the person"

Product

AttributeMinMaxData typeDescription
Id11"Number (9 – 16 positions long)""Product Id"
Title11"Text""Product title"
SpecsTag01"Text""Contains one of the following: a product's Author, Artist, Brand, Manufacturer or Publisher."
Subtitle01"Text""Product subtitle"
ShortDescription11"Text""Short description of the product"
LongDescription11"Text""Long description of the product"
OfferData01"OfferData""The offers of this product"
Urls0"-""Entry""The Urls of this product"
Media0"-""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"
Attributes0"-""Attribute Group""Further details of the product. These are grouped"
Promotions0"-""Promotion""Promotions that are applicable for this product"
Entities0"-""Entity"
Rating01"Number""Average product rating, scale of 00 –50, respresenting 0 to 5 stars"
EAN01"Number""The EAN of the products"
GPC01"Number""The GPC classification for the product"
Summary01"Text""A small summary of product data"
Tracklists01"Tracklist""Tracklist of a cd"
AttributeGroups0"-""AttributeGroup""Groups of related attributes"
EntityGroups0"-""EntityGroup"
Images0"-""Media Entry""The cover image of the product in several sizes"
ParentCategoryPaths0"-""ParentCategoryPath""The parentcategory of the product"

Seller

AttributeMinMaxData typeRequiredDescription
Id11"Number""Yes""Id of the seller"
DisplayName11"Text""Yes""Name of the seller, e.g. “2ehands verkoper Piet”"
NumberOfReviews01"Number""No""The number of times the seller is reviewed"
OverallRating01"Number""No""The average overall rating"
Url01"Text""No""An url describing the terms of a 3rd party seller"
Logo01"Text""No""An url to an image of the logo of the seller"
EmailAddress01"Text""No""The email address of the seller"
PhoneNumber01"Text""No""The telephone number of the seller"
AddressLine101"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."
AddressLine201"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."
SellerType01"Text""No""The type of seller, i.e., bol.com, non professional seller, professional seller"
TopSeller01"Boolean""No""Indicates whether the seller is a topseller"
SellerRating01"SellerRating""No""The rating of the seller"
RecentReviewCounts01"SellerReviewCounts""No""Counts of reviews that the seller received in the last three months"
allReviewCounts01"SellerReviewCounts""No""Counts of all reviews the seller received"
returnConditions01"Text""No""Specific return condition terms that the seller applies"
useWarrantyRepairConditions01"Boolean""No""Signals whether the warrantyConditions and repairConditions apply to this seller"
warrantyConditions01"Text""No""Specific return warranty terms that the seller applies"
repairConditions01"Text""No""Specific repair condition terms that the seller applies"
approvalPercentage01"Text""No""Percentage of reviewers that recommended the seller"
sellerInformation01"Text""No""A description of the seller"

SellerReviewCounts

AttributeMinMaxData typeRequiredDescription
positiveReviewCount01"Number""No""The number of positive reviews"
neutralReviewCount01"Number""No""The number of neutral reviews"
negativeReviewCount01"Number""No""The number of negative reviews"
totalReviewCount01"Number""No""The total number of reviews"

SellerRating

AttributeMinMaxData typeRequiredDescription
ratingMethod01"Text""No""Indicates whether the rating is based on all available reviews (ALL_REVIEWS) or on the last three months (THREE_MONTHS)"
sellerRating01"Number""No""The rating of the seller"
productInformationRating01"Number""No""The rating of the seller based on his productinformation"
deliveryTimeRating01"Number""No""The rating of the seller based on his delivery time"
shippingRating01"Number""No""The rating of the seller based on his shipping performance"
serviceRating01"Number""No""The rating of the seller based on his service"

RefinementGroup

AttributeMinMaxData typeRequiredDescription
id11"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."
name11"Text""Yes""The name of the refinement group, for example “taal” (language)."
refinements1"-""Refinement""Yes""the refinements in the refinement group"
productCount11"Number""Yes""The number of products in this refinement"

ProductRefinement

AttributeMinMaxData typeRequiredDescription
id11"Number""Yes""The ID of the refinement. Note that this id cannot be used to refine. Use the IDs of the underlying refinements instead."
name11"Text""Yes""The name of the refinement, for example “Engelse Boeken” (English books)."
Productcount11"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

AttributeMinMaxData typeDescription
Description11"Text""The description of the applicable promotion"
Title11"Text""The title of the promotion"
Url11"Text""The url of a list or page associated with the promotion"
UrlText11"Text""The text label for the promotion"

Productfamily

AttributeMinMaxData typeDescription
Key11"Text""The key of the family"
Label11"Text""The pretty label for the family"
ProductFamilyMembers01"ProductFamilyMember""The products that belong to the family"

Productfamilymember

AttributeMinMaxData typeDescription
Label11"Text""The pretty label for the product"
productId11"Text""The id of the product"

OfferData

AttributeMinMaxData typeDescription
Bol.com11"Number""the number of bol.com offers"
NonProfessionalSellers11"Number""The number of nonprofessional seller data"
ProfessionalSellers11"Number""The number of 2nd hand offers"
Offers0"-""Offer""The offers for the product"

Accessory

AttributeMinMaxData typeDescription
productId11"Number""the number of bol.com offers"

BundleItem

AttributeMinMaxData typeRequiredDescription
title11"Text""Yes""The title of the bundle that the item belongs to"
type11"Text""Yes""Describes the type of bundle the item belongs to"

PricingAdjustment

AttributeMinMaxData typeRequiredDescription
Description11"Text""Yes""The title of the pricing adjustment"
amount11"Money""Yes""The amount of discount the promotion represents"
Revocable11"Boolean""Yes""Signifies whether the user can revoce the promotion"

ListData

AttributeMinMaxData typeDescription
Products0100"Products""List of products found, max. 100 (with a search on EAN/ISBN this is limited to max 3 results)"
TotalResultSize11"Number""Total number of products found by search, before clipping to max 100 products (see element product)."
Categories0"-""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"
RefinementGroups0"-""RefinementGroups""One or more groups of refinements that are available to narrow down (refine) the search response."
OriginalRequest01"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

AttributeMinMaxData typeDescription
ProductFamilies0"-""ProductFamilies""The productfamilies for the product. See definition of productfamily for details"
Accessories0"-""Accessories""The accessories that are available for the product"