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.
API requests
Catalog
Utilities
Complex data types
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
/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 |
Category
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 | 0 | 1 | Number | No | The number of products found in the category |
Refinements | 1 | - | Refinement | No | Category Refinements |
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 | Min | Max | Data type | Required | Description |
---|---|---|---|---|---|
type | 0 | 1 | Text | No | Url of the ExtraSmall Image |
key | 0 | 1 | Text | No | Url of the Small Image |
url | 0 | 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 | Min | Max | Data type | Required | Description |
---|---|---|---|---|---|
positiveReviewCount | 0 | 1 | Number | No | The number of positive reviews |
neutralReviewCount | 0 | 1 | Number | No | The number of neutral reviews |
negativeReviewCount | 0 | 1 | Number | No | The number of negative reviews |
totalReviewCount | 0 | 1 | Number | No | The total number of reviews |
SellerRating
Attribute | Min | Max | Data type | Required | Description |
---|---|---|---|---|---|
ratingMethod | 0 | 1 | Text | No | Indicates whether the rating is based on all available reviews (ALL_REVIEWS) or on the last three months (THREE_MONTHS) |
sellerRating | 0 | 1 | Number | No | The rating of the seller |
productInformationRating | 0 | 1 | Number | No | The rating of the seller based on his productinformation |
deliveryTimeRating | 0 | 1 | Number | No | The rating of the seller based on his delivery time |
shippingRating | 0 | 1 | Number | No | The rating of the seller based on his shipping performance |
serviceRating | 0 | 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 |