# Kaufland marketplace API scraper — search kaufland.de, .cz, .sk, .pl and .at and read full product records: buy-box price with UVP and struck price kept apart, every seller's new and used offer with shipping, EAN, specifications, variants, ratings and reviews. No account, no browser.

> Search a Kaufland storefront by keyword or browse a category, 40 rows per page: product id, title, brand, EAN, image, price with the site's struck price and the manufacturer's UVP as separate fields, unit price, coupon, condition (new / refurbished / used), seller and whether Kaufland itself sells it, shipping cost, delivery window, rating and review count, lowest used and refurbished offer price, and whether the row is a sponsored ad. Filter by price range, manufacturer, minimum rating, deals only or any storefront facet; sort the way the site does.
> ReefAPI engine `kaufland` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/kaufland/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /kaufland/v1/search — 2 credits
Search a Kaufland storefront by keyword or browse a category, 40 rows per page: product id, title, brand, EAN, image, price with the site's struck price and the manufacturer's UVP as separate fields, unit price, coupon, condition (new / refurbished / used), seller and whether Kaufland itself sells it, shipping cost, delivery window, rating and review count, lowest used and refurbished offer price, and whether the row is a sponsored ad. Filter by price range, manufacturer, minimum rating, deals only or any storefront facet; sort the way the site does.

**Parameters:**
- `query` (string, optional) — What to search for on the storefront, in its language ('staubsauger', 'kava', 'kawa'). Optional when `category` is given.
- `category` (string, optional) — Browse (or narrow a search to) a category: its numeric id (5921) or a Kaufland category URL (…/c/kaffeepulver/~5921/). Ids come from `filters.categories`, `category` on rows and `breadcrumb` on product/detail.
- `country` (enum, optional, default "de") — Which Kaufland storefront to read. Currency follows the country: EUR for de, sk and at, CZK for cz, PLN for pl. A kaufland.* URL in product_id/category sets it automatically. Unknown values are rejected. [one of: de, cz, sk, pl, at]
- `page` (integer, optional, default 1) — Result page, 1-based. 40 rows per page; the site stops at 10 000 results (page 250).
- `sort` (enum, optional, default "relevance") — Result order — the orderings the storefront itself offers. [one of: relevance, price_asc, price_desc, rating, newest, bestsellers]
- `min_price` (number, optional) — Lowest price in the storefront currency (inclusive).
- `max_price` (number, optional) — Highest price in the storefront currency (inclusive).
- `brand_id` (string, optional) — Only this manufacturer: the numeric `id` from `filters.brands` (51451 = Jacobs on kaufland.de), or `brand_id` from product/detail.
- `min_rating` (integer, optional) — Only products rated at least this many stars (1-4).
- `deals_only` (boolean, optional, default false) — Only products currently on a deal (the storefront's 'Angebote' filter).
- `filters` (object, optional) — Advanced: extra storefront facets as {key: value}, using `filters.attributes[].key` and a `values[].value` from a previous search with include_filters=true (e.g. {"3284": "1394137"}).
- `include_filters` (boolean, optional, default false) — Also return the facet panel (categories, manufacturers, price bands, attribute filters) for this search. One extra upstream call.
- `include_sponsored` (boolean, optional, default false) — Kaufland mixes paid (sponsored) products into the default order. Default false: they are left out and counted in sponsored_dropped. true: they are returned in place with sponsored: true.
- `include_fallback_results` (boolean, optional, default false) — When no product on page 1 contains a query word, Kaufland's rows are loose matches. Default false: results is empty and fallback_results_dropped counts them. true: they are returned apart, in fallback_results.
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** results[]{position, product_id, offer_id, title, brand, ean (GTIN-validated), url, image, images[], sponsored, price, currency, was_price (the storefront's struck price, null when none), discount_percent, rrp (UVP manufacturer's recommended price — NOT a was-price), rrp_discount_percent, unit_price{price, unit}, voucher{code_title, discount, discount_type, discount_amount, vouchers_total, vouchers_redeemed} (a coupon to redeem — NOT applied to price), price_with_voucher (the coupon price the product page headlines; null without a coupon), top_price, condition{key, code, is_new}, seller{id, name, company_name, is_kaufland}, shipping_cost, delivery{min_workdays, max_workdays, earliest_date, latest_date}, available, sold_out, rating (1-5, null when unrated), review_count, rating_scale, refurbished_offers_from_price (cheapest used/refurbished offer), category{id, name}, badges[]}, count (organic rows), sponsored_dropped, sponsored_included, unavailable_dropped, page, page_size (40), total_results (the site's count), total_results_capped (true when the site's 10 000 cap is hit), total_pages, has_more, page_notice, query, category_id, sort, country, currency, applied_filters, keyword_matches_on_page, fallback_results_dropped, fallback_total, fallback_results[] (opt-in), filters{categories[]{id, name}, brands[]{id, name}, price_bands[]{min, max}, min_rating[], attributes[]{key, name, type, unit, values[]{value, label}}} (with include_filters=true)

**Example request body:**
```json
{
  "query": "kaffee"
}
```

### POST /kaufland/v1/product/detail — 2 credits
The full Kaufland product record by id or URL: title, brand, EAN, MPN, category and breadcrumb, buy-box price with shipping cost and total, UVP and the site's struck price kept apart, unit price, coupon, condition of the buy-box offer, seller with return period and whether it is Kaufland itself, delivery window and ships-from country, every other seller's new and used/refurbished offer with shipping and total price, the cheapest offer vs the buy box, rating with per-star breakdown, all images, description, the full specifications table and colour/size variants.

**Parameters:**
- `product_id` (string, required) — Kaufland product id as returned in `product_id` by `search` (434682098), or a full kaufland.* product URL (…/product/434682098/). Ids are shared across storefronts, prices are not.
- `country` (enum, optional, default "de") — Which Kaufland storefront to read. Currency follows the country: EUR for de, sk and at, CZK for cz, PLN for pl. A kaufland.* URL in product_id/category sets it automatically. Unknown values are rejected. [one of: de, cz, sk, pl, at]
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** product{product_id, url, title, brand, brand_id, brand_url, ean, eans[] (every GTIN the product carries), mpn, category{id, name}, breadcrumb[]{id, name, url}, price, currency, was_price, discount_percent, rrp, rrp_discount_percent, unit_price, voucher, price_with_voucher, top_price, in_stock, buy_box{offer_id, price, currency, shipping_cost, total_price, condition{key, code, is_new, seller_note}, seller{id, name, is_kaufland, return_period_days, shop_url}, delivery{text, max_workdays, earliest_date, latest_date, ships_from_country, fulfillment_type, next_day_available}, stock_quantity, other_new_offers, other_used_offers}, sold_by_kaufland, offers_summary{offers_count, new_offers_count, used_or_refurbished_offers_count, cheapest_offer, cheapest_new_offer, buy_box_is_cheapest_new}, offers[]{offer_id, is_buy_box, price, shipping_cost, total_price, currency, condition, seller, delivery, fulfillment_type}, refurbished_alternatives[], rating, review_count, rating_scale, rating_breakdown{'1'..'5'}, images[], description, specifications[]{id, name, value}, variants[]{dimension, dimension_name, options[]{title, product_id, selected, url}}, is_bestseller, adult_only, listed_in_countries[], country}

**Example request body:**
```json
{
  "product_id": "434682098"
}
```

### POST /kaufland/v1/product/offers — 1 credit
Every offer on one Kaufland product: each seller's new and used/refurbished offer with price, shipping cost, total price, condition and seller note, delivery window and return period, which offer holds the buy box, the cheapest offer and cheapest new offer by total price, and refurbished alternatives. Cheaper than product/detail when only prices and sellers are needed.

**Parameters:**
- `product_id` (string, required) — Kaufland product id as returned in `product_id` by `search` (434682098), or a full kaufland.* product URL (…/product/434682098/). Ids are shared across storefronts, prices are not.
- `country` (enum, optional, default "de") — Which Kaufland storefront to read. Currency follows the country: EUR for de, sk and at, CZK for cz, PLN for pl. A kaufland.* URL in product_id/category sets it automatically. Unknown values are rejected. [one of: de, cz, sk, pl, at]
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** product_id, url, country, currency, buy_box{…as in product/detail}, offers[]{offer_id, is_buy_box, price, shipping_cost, total_price, currency, condition{key, code, is_new, seller_note}, seller{id, name, is_kaufland, return_period_days, shop_url}, delivery{text, earliest_date, latest_date}, fulfillment_type}, offers_count, new_offers_count, used_or_refurbished_offers_count, cheapest_offer, cheapest_new_offer, buy_box_is_cheapest_new, refurbished_alternatives[]

**Example request body:**
```json
{
  "product_id": "434682098"
}
```

### POST /kaufland/v1/product/reviews — 2 credits
Customer reviews of one Kaufland product: star rating, title, text, date, verified purchase, product-test flag, which storefront it was written on with any translation, plus the product's average rating, total review count, per-star breakdown and Kaufland's AI summary of the reviews. Sort newest, oldest or by stars; page through all of them.

**Parameters:**
- `product_id` (string, required) — Kaufland product id as returned in `product_id` by `search` (434682098), or a full kaufland.* product URL (…/product/434682098/). Ids are shared across storefronts, prices are not.
- `country` (enum, optional, default "de") — Which Kaufland storefront to read. Currency follows the country: EUR for de, sk and at, CZK for cz, PLN for pl. A kaufland.* URL in product_id/category sets it automatically. Unknown values are rejected. [one of: de, cz, sk, pl, at]
- `page` (integer, optional, default 1) — Review page, 1-based.
- `page_size` (integer, optional, default 20) — Reviews per page (1-100, default 20).
- `sort` (enum, optional, default "newest") — Review order. [one of: newest, oldest, rating_desc, rating_asc, site_default]
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** reviews[]{review_id, rating, title, text, date (YYYY-MM-DD), verified_purchase, product_test, external_source, storefront, language, translated_title, translated_text, media_count, variant}, count, page, page_size, total_reviews, total_pages, has_more, sort, average_rating, rating_scale, rating_breakdown{'1'..'5'}, ai_summary, product_id, country

**Example request body:**
```json
{
  "product_id": "434682098"
}
```

### POST /kaufland/v1/search/suggest — 1 credit
Kaufland's own search-box suggestions for a partial keyword on the chosen storefront.

**Parameters:**
- `query` (string, required) — What the shopper has typed so far (at least 2 characters).
- `country` (enum, optional, default "de") — Which Kaufland storefront to read. Currency follows the country: EUR for de, sk and at, CZK for cz, PLN for pl. A kaufland.* URL in product_id/category sets it automatically. Unknown values are rejected. [one of: de, cz, sk, pl, at]
- `max_rotations` (integer, optional, default 4) — Advanced: how many times to retry a difficult request (1-8, default 4 — leave unchanged for typical use).

**Returns:** suggestions[], count, query, country

**Example request body:**
```json
{
  "query": "kaffee"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=kaufland
- Human docs page: https://reefapi.com/docs/kaufland
- Overview page: https://reefapi.com/kaufland-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt