Carrefour France API & Scraper
The Carrefour France API turns carrefour.fr, the French supermarket's online store and its marketplace, into clean JSON in eleven actions.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
search takes a French keyword with the site's own sorts (relevance, price, price per kg or litre, rating) and filters (brand, price range, promotions, Carrefour's own brand, organic, Nutri-Score and any other facet the site lists) and returns 30 products a page: EAN, title, brand, URL, packaging, the price with the struck price and discount, loyalty-card credits and multi-buy offers kept apart, the unit price, the seller (Carrefour or a marketplace seller with rating and shipping), availability, rating, Nutri-Score and how many other offers exist with their lowest price. product/detail adds the breadcrumb, description, key features, characteristics, ingredients and nutrition per 100 g, storage information, energy class, dimensions, images, the per-star rating breakdown, variants with their own EAN and price, and every offer. product/offers lists those offers (Carrefour store, Carrefour home delivery and each marketplace seller) with shipping and total, cheapest first. product/reviews and seller/reviews return verified reviews; seller/profile and seller/products open a marketplace seller; category and deals browse a category or the promotions hub; search/suggest completes a keyword; stores finds the nearest stores. Grocery prices and the assortment depend on the store, so every priced action takes a store_id or a postal_code and echoes the store it used; without one, prices are carrefour.fr's national online catalogue. In a live check on 2026-09-16, 8 products matched their own product pages on title, price, struck price, availability, rating and GTIN with no mismatch. No Carrefour account, no browser, one ReefAPI key and the standard { ok, data, meta, error } envelope. France only.
Price, struck price, card credit and multi-buy are four different numbers
A Carrefour page can show a sale price with a crossed-out price, a loyalty-card credit, and a 'second one at -50%' offer on the same product. The API keeps each in its own field, and a search row's price is its buy-box offer, not always the cheapest one.
| Product (2026-09-16) | price | was_price | loyalty / multi-buy | other offers |
|---|---|---|---|---|
| Hisense 55" QLED TV 55E7S | 449.99 EUR | 499.99 (-10%) | none | 8 offers, cheapest 404.70 from a marketplace seller with free delivery |
| Rowenta X-Pert 7.60 stick vacuum | 119.99 EUR | 179.99 (-33%) | loyalty_price 99.99 (20 EUR credited to the card) | 3 other offers |
| Kärcher WD 1 wet and dry vacuum | 54.99 EUR | null | loyalty_price 43.99 (20% credited to the card) | none |
| GrandLait semi-skimmed milk, 10 x 1 L | 11.60 EUR (1.16 EUR / L) | null | multi-buy: 2 for 17.40 | none |
| Nutella 400 g | 3.65 EUR (default catalogue) | null | 4.25 EUR at a Lyon drive store | prices follow store_id / postal_code |
price is what the page sells one unit at. was_price is the crossed-out price. A loyalty offer is money credited to the Carrefour card after purchase, so price does not change; loyalty_price shows the price after that credit. A multi-buy prices several units together and never replaces price. The unit price is the one the site publishes, which is based on the regular price while a promotion runs (unit_price_basis says so).
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/carrefour-fr/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "lait"
}
}{
"ok": true,
"meta": {
"api": "carrefour-fr",
"endpoint": "search",
"mode": "live",
"latency_ms": 2425.2,
"record_count": 30,
"bytes": 191579,
"cache_hit": false,
"pagination": {
"page": 1,
"page_size": 30,
"total": 576,
"has_more": true
},
"upstream_requests": 2
},
"data": {
"results": [
{
"position": 1,
"product_id": "3533630088362",
"ean": "3533630088362",
"title": "Lait Demi-Ecrémé GrandLait GRANDLAIT",
"brand": "GRANDLAIT",
"url": "https://www.carrefour.fr/p/lait-demi-ecreme-grandlait-grandlait-3533630088362",
"product_type": "product",
"business_type": "food",
"category": "Crèmerie et Produits laitiers",
"category_path": [
"Crèmerie et Produits laitiers",
"Laits et Boissons végétales",
"Lait demi-écrémé"
],
"packaging": "le pack de 10 bouteilles de 1L",
"format": "1l",
"price": 11.6,
"currency": "EUR",
"was_price": null,
"discount_amount": null,
"discount_percent": null,
"promotion_label": null,
"promotion_ends": null,
"loyalty_price": null,
"loyalty_offers": [],
"multibuy_offers": [
{
"type": "[trimmed-depth]",
"label": "[trimmed-depth]",
"quantity": "[trimmed-depth]",
"total_price": "[trimmed-depth]",
"regular_total": "[trimmed-depth]",
"valid_until": "[trimmed-depth]"
}
],
"promotion_badges": [],
"unit_price": 1.16,
"unit_of_measure": "L",
"unit_price_label": "1.16 € / L",
"unit_price_basis": "price",
"tax_message": null,
"offer_id": "0261-150-6",
"seller": {
"id": null,
"name": "Carrefour",
"is_carrefour": true,
"rating": null,
"rating_count": null,
"rating_scale": null,
"url": null
},
"shipping_cost": null,
"free_shipping": null,
"free_shipping_minimum": null,
"delivery_days_min": null,
"delivery_days_max": null,
"availability": "in_stock",
"in_stock": true,
"low_stock": false,
"other_offers_count": 0,
"other_offers_lowest_price": null,
"lowest_offer_price": 11.6,
"rating": 4.8,
"review_count": 5,
"rating_scale": 5,
"nutriscore": null,
"labels": [],
"highlight": "Partenaire Monopoly",
"is_best_seller": false,
"is_new": false,
"is_sponsored": false,
"image": "https://media.carrefour.fr/medias/00b4c9d658e33bf3867c48d23ae956f0/p_1500x1500/3533630088362-photosite-20161220-162326-0.jpg"
},
{
"position": 2,
"product_id": "3276554163158",
"ean": "3276554163158",
"title": "Lait Demi-Écrémé CARREFOUR CLASSIC'",
"brand": "CARREFOUR CLASSIC'",
"url": "https://www.carrefour.fr/p/lait-demi-ecreme-carrefour-classic-3276554163158",
"product_type": "product",
"business_type": "food",
"category": "Crèmerie et Produits laitiers",
"category_path": [
"Crèmerie et Produits laitiers",
"Laits et Boissons végétales",
"Lait demi-écrémé"
],
"packaging": "la bouteille 1L",
"format": "1L",
"price": 1.05,
"currency": "EUR",
"was_price": null,
"discount_amount": null,
"discount_percent": null,
"promotion_label": null,
"promotion_ends": null,
"loyalty_price": 0.89,
"loyalty_offers": [
{
"type": "[trimmed-depth]",
"label": "[trimmed-depth]",
"min_quantity": "[trimmed-depth]",
"discount_percent": "[trimmed-depth]",
"card_credit": "[trimmed-depth]",
"card_credit_scope": "[trimmed-depth]",
"credit_basis": "[trimmed-depth]",
"price_after_credit": "[trimmed-depth]",
"lot_price": "[trimmed-depth]",
"lot_price_after_credit": "[trimmed-depth]",
"valid_from": "[trimmed-depth]",
"valid_until": "[trimmed-depth]"
}
],
"multibuy_offers": [],
"promotion_badges": [],
"unit_price": 1.05,
"unit_of_measure": "L",
"unit_price_label": "1.05 € / L",
"unit_price_basis": "price",
"tax_message": null,
"offer_id": "0261-150-6",
"seller": {
"id": null,
"name": "Carrefour",
"is_carrefour": true,
"rating": null,
"rating_count": null,
"rating_scale": null,
"url": null
},
"shipping_cost": null,
"free_shipping": null,
"free_shipping_minimum": null,
"delivery_days_min": null,
"delivery_days_max": null,
"availability": "in_stock",
"in_stock": true,
"low_stock": false,
"other_offers_count": 0,
"other_offers_lowest_price": null,
"lowest_offer_price": 1.05,
"rating": 4.72,
"review_count": 164,
"rating_scale": 5,
"nutriscore": "A",
"labels": [],
"highlight": null,
"is_best_seller": false,
"is_new": false,
"is_sponsored": false,
"image": "https://media.carrefour.fr/medias/6236a56cbc6c46c4a47aaeea5b9ffe0b/p_1500x1500/3276554163158-photosite-20241112-171948-0.jpg"
},
{
"position": 3,
"product_id": "3270190430049",
"ean": "3270190430049",
"title": "Lait Demi-Écrémé CARREFOUR EXTRA",
"brand": "CARREFOUR EXTRA",
"url": "https://www.carrefour.fr/p/lait-demi-ecreme-carrefour-extra-3270190430049",
"product_type": "product",
"business_type": "food",
"category": "Crèmerie et Produits laitiers",
"category_path": [
"Crèmerie et Produits laitiers",
"Laits et Boissons végétales",
"Lait demi-écrémé"
],
"packaging": "le pack de 6 bouteilles de 1L",
"format": "6x1L",
"price": 6.66,
"currency": "EUR",
"was_price": null,
"discount_amount": null,
"discount_percent": null,
"promotion_label": null,
"promotion_ends": null,
"loyalty_price": 5.66,
"loyalty_offers": [
{
"type": "[trimmed-depth]",
"label": "[trimmed-depth]",
"min_quantity": "[trimmed-depth]",
"discount_percent": "[trimmed-depth]",
"card_credit": "[trimmed-depth]",
"card_credit_scope": "[trimmed-depth]",
"credit_basis": "[trimmed-depth]",
"price_after_credit": "[trimmed-depth]",
"lot_price": "[trimmed-depth]",
"lot_price_after_credit": "[trimmed-depth]",
"valid_from": "[trimmed-depth]",
"valid_until": "[trimmed-depth]"
}
],
"multibuy_offers": [],
"promotion_badges": [],
"unit_price": 1.11,
"unit_of_measure": "L",
"unit_price_label": "1.11 € / L",
"unit_price_basis": "price",
"tax_message": null,
"offer_id": "0261-150-6",
"seller": {
"id": null,
"name": "Carrefour",
"is_carrefour": true,
"rating": null,
"rating_count": null,
"rating_scale": null,
"url": null
},
"shipping_cost": null,
"free_shipping": null,
"free_shipping_minimum": null,
"delivery_days_min": null,
"delivery_days_max": null,
"availability": "in_stock",
"in_stock": true,
"low_stock": false,
"other_offers_count": 0,
"other_offers_lowest_price": null,
"lowest_offer_price": 6.66,
"rating": 4.71,
"review_count": 1954,
"rating_scale": 5,
"nutriscore": null,
"labels": [],
"highlight": null,
"is_best_seller": false,
"is_new": false,
"is_sponsored": false,
"image": "https://media.carrefour.fr/medias/11bae5b7375a317593e606fdabd76474/p_1500x1500/3270190430049-photosite-20210504-175356-0.jpg"
}
],
"count": 30,
"total_results": 576,
"total_pages": 20,
"page": 1,
"page_size": 30,
"sort": "relevance",
"applied_filters": {},
"sponsored_dropped": 0,
"sponsored_count": 0,
"search_type": null,
"available_filters": [
{
"field": "EM_Operations_SEO",
"label": "Opération",
"type": "checkbox",
"selected": false,
"values": [
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]",
"count": "[trimmed-depth]",
"selected": "[trimmed-depth]"
}
]
},
{
"field": "ES_discount_quickaccess",
"label": "Promotions",
"type": "boolean",
"selected": false,
"values": [
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]",
"count": "[trimmed-depth]",
"selected": "[trimmed-depth]"
},
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]",
"count": "[trimmed-depth]",
"selected": "[trimmed-depth]"
}
]
},
{
"field": "facet_promotions",
"label": "Promotions",
"type": "checkbox",
"selected": false,
"values": [
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]",
"count": "[trimmed-depth]",
"selected": "[trimmed-depth]"
},
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]",
"count": "[trimmed-depth]",
"selected": "[trimmed-depth]"
},
{
"value": "[trimmed-depth]",
"label": "[trimmed-depth]",
"count": "[trimmed-depth]",
"selected": "[trimmed-depth]"
}
]
}
],
"has_next_page": true,
"query": "lait",
"did_you_mean": null,
"autocorrected": false,
"related_searches": [
"lait sans lactose",
"lait demi ecreme",
"lait entier"
],
"keyword_matches_on_page": 30,
"fallback_results_dropped": 0,
"fallback_total": null,
"redirected_to": null,
"redirect_type": null,
"store": {
"store_id": null,
"store_code": "0261",
"name": "Carrefour online catalogue (default store)",
"is_default": true
}
}
}What the Carrefour France API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search carrefour.fr by keyword with the site's sorts and filters (brand, price range, promotions, own brand, organic, Nutri-Score, any listed facet). Each row: EAN, title, brand, URL, the price with the struck price and discount, loyalty-card offers, multi-buy offers, the unit price, seller (Carrefour or marketplace), availability, rating, Nutri-Score and how many other offers exist. Prices follow the chosen store (store_id / postal_code). | Pricing teams call search to search carrefour.fr by keyword with the site's sorts and filters (brand, price range, promoti…. | query, page, sort, brand, price_min, ... |
| product/detail | The full carrefour.fr product record by EAN or URL: title, brand, category breadcrumb, the buy-box price with struck price, loyalty-card and multi-buy offers, unit price, availability, every offer (Carrefour store, Carrefour home delivery, marketplace sellers with rating and shipping), rating with the per-star breakdown, description, key features, characteristics, ingredients and nutrition, storage/usage information, Nutri-Score, energy class, dimensions, images and variants (colour/size with their own EAN and price). | Marketplace operators call product/detail to get the full carrefour.fr product record by EAN or URL. | product_id, url, store_id, postal_code, max_rotations |
| product/offers | Every offer on one carrefour.fr product (by EAN or URL): the Carrefour store offer, Carrefour home delivery and each marketplace seller, with price, struck price, loyalty offers, shipping cost and delivery time, seller rating, stock and warranty add-ons, plus the cheapest offer. | Catalog enrichment teams call product/offers to get every offer on one carrefour.fr product (by EAN or URL). | product_id, url, sort, store_id, postal_code, ... |
| product/reviews | Verified customer reviews of a carrefour.fr product (by EAN or URL), paged, sortable and filterable by star rating: rating, title, text, author display name, review and order dates and the review source. | Retail analysts call product/reviews to get verified customer reviews of a carrefour.fr product (by EAN or URL), paged, sortable and filt…. | product_id, url, page, per_page, sort, ... |
| seller/reviews | Buyer reviews of a carrefour.fr marketplace seller, newest or oldest first: rating, the tags the buyer picked, author display name and dates. | Pricing teams call seller/reviews to get buyer reviews of a carrefour.fr marketplace seller, newest or oldest first. | seller_id, page, per_page, sort, max_rotations |
| seller/profile | A carrefour.fr marketplace seller's public page: name, logo, description, return policy, shipping zone and delivery time, rating, and the legal notice the site publishes (company name, registration and VAT numbers, business address, legal representative, terms URL). | Marketplace operators call seller/profile to get a carrefour.fr marketplace seller's public page. | seller_id, max_rotations |
| seller/products | Everything a carrefour.fr marketplace seller lists, with the same sorts, filters and row fields as search. | Catalog enrichment teams call seller/products to get everything a carrefour.fr marketplace seller lists, with the same sorts, filters and row fiel…. | seller_id, page, sort, brand, price_min, ... |
| category | Browse a carrefour.fr category (e.g. 'cremerie/laits', 'image-son/televiseurs') with the same sorts, filters, store pricing and row fields as search. | Retail analysts call category to get browse a carrefour.fr category (e.g. | category, page, sort, brand, price_min, ... |
| deals | carrefour.fr's promotions hub: every product with a running promotion (struck prices, loyalty-card credits, multi-buy offers, catalogue offers), with the same sorts, filters, store pricing and row fields as search. | Pricing teams call deals to get carrefour.fr's promotions hub. | page, sort, brand, price_min, price_max, ... |
| search/suggest | carrefour.fr's autocomplete for a partial keyword: keyword suggestions and keyword-in-category suggestions, each with its search URL. | Marketplace operators call search/suggest to get carrefour.fr's autocomplete for a partial keyword. | query, max_rotations |
| stores | Find Carrefour stores near a French postal code or a latitude/longitude, nearest first: name, banner, format, address, distance, today's opening hours and the drive/pickup services whose `store_id` prices search, category, deals, product/detail and product/offers for that store. | Catalog enrichment teams call stores to find Carrefour stores near a French postal code or a latitude/longitude, nearest first. | postal_code, latitude, longitude, mode, page, ... |
Call search from your stack
curl -X POST https://api.reefapi.com/carrefour-fr/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"lait"}'import requests
r = requests.post(
"https://api.reefapi.com/carrefour-fr/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "lait"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/carrefour-fr/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "lait"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.carrefour-fr.search with {"query":"lait"}.Who uses this API and why
- Grocery price trackers follow a basket across French drive stores, with struck prices, loyalty-card credits and multi-buy offers each in its own field.
- Marketplace sellers see every competing offer on an EAN at Carrefour, with shipping, delivery time and seller rating, and the cheapest delivered total.
- Nutrition and catalog teams pull ingredients, nutrition per 100 g, Nutri-Score, characteristics and images for products matched by EAN.
- Promotion analysts read the promotions hub and the price per kg or litre, sorted the way carrefour.fr sorts them.
Questions developers ask before integrating
Why do prices differ from what I see on carrefour.fr?
Because carrefour.fr prices groceries per store. Without a store, the API returns the national online catalogue (store.is_default true). Pass store_id (from the stores action) or a French postal_code to get the prices and the assortment of that drive or pickup store; the response's store object says which store was used. On 2026-09-16 a 400 g Nutella was 3.65 EUR in the default catalogue and 4.25 EUR at a Lyon drive store, and only 18 of the 30 default search rows existed there.
Which price does a row carry?
price is the price of one unit as the page shows it, promotions that lower the shelf price included; was_price is the crossed-out price and discount_percent the difference. Loyalty-card offers ("20% d'économies", "-15% Mardi PASS", "-10% Club") are credited to the card after purchase, so they are returned in loyalty_offers, and price stays the page price. Each loyalty offer says how many units it needs (min_quantity). loyalty_price is the price of one unit after the card credit, and only single-unit offers feed it. An offer such as "2 acheté(s) = 20% d'économies" returns the two-unit total before and after the credit (lot_price, lot_price_after_credit). For "Dès 2 produits = 70% d'économies" carrefour.fr publishes no amount that matches its label, so the API returns the label, the quantity and the percentage with card_credit null rather than a guessed figure. Offers like "Le 2ème à -50%" are in multibuy_offers with the quantity and the total.
Is a search result the cheapest offer?
Not always. A row is the product's buy-box offer (Carrefour or a marketplace seller) and carries other_offers_count, other_offers_lowest_price and lowest_offer_price. carrefour.fr's price sorts order products by that lowest offer, so a row's own price can look out of order. product/offers returns every offer with shipping cost, delivery time and total price, cheapest first.
What does shipping look like for marketplace sellers?
Each marketplace offer returns shipping_cost, free_shipping, free_shipping_minimum and the delivery time in days, following the rule carrefour.fr applies on its product page (free when the seller offers it, when the order reaches the seller's minimum, or when the seller publishes no delivery charge). total_price is price plus shipping. Carrefour's own offers do not publish a per-offer shipping cost; product/detail returns the site's delivery information text instead.
What happens with a misspelt or unknown keyword?
Misspellings the site understands keep their results and return did_you_mean (chocolt → chocolat). For a keyword it cannot match, carrefour.fr fills the page with loosely related products; the API returns an empty list, counts those rows in fallback_results_dropped, and include_fallback_results returns them apart. Some keywords open a category instead (jouet → the toys category); the API follows it and says so in redirect_type. On 2026-09-16, 25 real and 7 misspelt French queries kept their results and 10 nonsense queries came back empty or honestly corrected.
Does it include nutrition and ingredients?
When the product page has them: composition returns the ingredients and the nutrition table per 100 g, information returns storage and usage text, and nutriscore the grade. carrefour.fr publishes a Nutri-Score on few products (21 of 315 search rows in our sample), so nutriscore is often null.
Can I look up marketplace sellers?
Yes. Every marketplace offer returns seller.id. seller/profile returns the seller's page: description, return policy, delivery zone and times, rating, and the legal notice carrefour.fr publishes (company name, registration and VAT numbers, address). seller/products lists everything the seller sells with the search filters, and seller/reviews returns buyer reviews newest or oldest first. carrefour.fr offers no star filter for seller reviews.
Which countries are covered?
France (carrefour.fr) only. Carrefour's shops in Spain, Italy, Belgium, Poland, Brazil and elsewhere are separate websites with their own catalogues. Carrefour Turkey (CarrefourSA) is a different company with its own API on ReefAPI.
What is the Carrefour France API?
Carrefour France API is a ReefAPI endpoint group for carrefour.fr groceries and marketplace: store prices, struck and loyalty prices, every seller's offer, nutrition and reviews. It returns live JSON through POST requests under /carrefour-fr/v1.
Is the Carrefour France API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Carrefour France calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Carrefour France login or account?
No login to Carrefour France is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Carrefour France data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Carrefour France API use?
Carrefour France actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Carrefour France from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call carrefour-fr actions with the same key, credit pool and JSON envelope used by normal REST requests.