GET /catalog/v4/lists

Request URL structure:{categoryid}

Request HTTP method:


Request requires session:




Location Data type Required


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 refinementscategories, 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:{apikey}&format=json



Element Min Max Description




Total number of products found, before clipping to max 100 products.




Total size of the returned results



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



One or more groups of refinements that are available to narrow down (refine) the search response.




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

Request / Response example:


Example response: JSONXML