Skip to content

Prices and shops

GET /v1/Products/{id}/Prices returns the current offers for a product in your market, in the order Kieskeurig shows them.

[
{
"shop": { "id": 1234, "name": "Voorbeeldshop", "logo": "https://…", "website": "https://www.voorbeeldshop.nl/", "marketplace": false, "officialDealer": true, "billingCode": null },
"amount": 104.99,
"amountBare": 99.99,
"deliveryCost": 5.00,
"deliveryCode": "ONE_DAY",
"deliveryText": "Voor 23:59 besteld, morgen in huis",
"textAd": "Gratis retourneren | 30 dagen bedenktijd",
"link": "https://…",
"secondaryCtaLink": null
}
]
Field Meaning
amount What the customer pays: price including delivery
amountBare Price excluding delivery
deliveryCost Delivery cost
deliveryCode Normalized delivery time (ONE_DAY … MORE_DAYS, PRE_ORDER); null when unknown
deliveryText, textAd Free text from the shop, in Dutch
link Clickout URL; see Affiliate ids and clickouts
secondaryCtaLink Optional second clickout to a specific page at the shop, for example a form to request a discount; null when the shop supplies none. See Second button

All amounts are in euros. Refurbished offers are included by default; pass Refurbished=false to leave them out.

Some shops supply a second destination for an offer, for example HelloTV’s “ask for a discount” form. The offer then has secondaryCtaLink: a clickout like link, carrying your affiliate id, that lands directly on that page. Clicks on it are registered and paid like normal clickouts.

  • Show the second button only when secondaryCtaLink is not null.
  • Use the URL unchanged. Don’t append your own parameters: the shop’s page may then not open.
  • It is only returned by GET /v1/Products/{id}/Prices, not by GET /v1/Shops/{shopId}/Offers.

When a product has no current offers in your market, GET /v1/Products/{id}/Prices returns 404 with error code 4040. That is a normal state, not a failure: products go out of stock, shops pause their feeds, and products come back. Show the product as unavailable and check again later. Don’t delete the product on a single 404.

Prices come from the shops’ product feeds and are updated whenever a feed is processed. The API caches each product’s offer list for up to 5 minutes, so polling the same product more often than that returns the same data.

The price in a feed can occasionally differ from the shop’s website, for example during a flash sale or when the shop changes prices between two feed updates. If you see a structural difference for a shop, tell us which product and shop, and when you saw it.

Shop details appear in every offer (shop), and GET /v1/Shops lists all shops with review scores and quality marks (thuiswinkel, beCommerce, kieskeurigQualityMark).

Shop ids belong to a market. The same retailer can have a different id for a key in another market. Use the ids your own key returns, and don’t hard-code ids from someone else’s integration.

Identify shops by id, not billingCode. billingCode is a legacy internal code and is empty for most shops.

website holds the shop’s website as an absolute URL, or null when we don’t know it. Use it to show where the shop is, not as a link for users to click: clicks should go through the clickout link so they are attributed to you.

Your key can exclude certain shops. They never appear in GET /v1/Products/{id}/Prices, and GET /v1/Shops/{shopId}/Offers returns 404 for them.

GET /v1/Shops/{shopId}/Offers returns every current offer of a shop, ordered by EAN, with title, image, price and clickout URL. It pages with Skip and Limit (max 1000) and reports the total in X-Total-Count. kieskeurigId is null for offers we haven’t matched to a catalog product.

With the MerchantFeed role, GET /v1/Shops/{shopId}/merchant returns the same data as a Google Merchant Center compatible XML feed.

GET /v1/Products/{id}/History (role History) returns price points (ean, amount, date) for a product in your market, newest first by default. Pass SortDirection=ASCENDING for oldest first.