# Carrefour Italy — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse Carrefour Italy's product catalog across categories, view detailed product information, find nearby store locations, and discover current promotions all in one place. Explore online grocery selections and compare products by price, brand, and availability.

**Category:** Food & Dining | **Website:** [carrefour.it/](https://carrefour.it/) | **Docs:** [parse.bot/marketplace/59e86df2-3fcd-4364-a2df-1d135d4275ef/carrefour-it-api](https://parse.bot/marketplace/59e86df2-3fcd-4364-a2df-1d135d4275ef/carrefour-it-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-carrefour-it-api-59e86df2/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_category_products

Browse products listed under a specific grocery category. The category_slug corresponds to the URL path segment under /spesa-online/. Returns all products on the first page of that category with the same product fields as search_products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_slug` | string | Yes | Category slug identifier from get_online_grocery_categories (e.g. 'frutta-e-verdura', 'carne', 'pesce', 'pasta-riso-e-farina') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-carrefour-it-api-59e86df2/get_category_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_slug":"<string>"}'
```

### get_online_grocery_categories

List all top-level online grocery categories available on Carrefour Italy. Returns category name, URL slug (for use with get_category_products), and full URL. Categories include produce, meat, fish, dairy, beverages, household, and personal care.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-carrefour-it-api-59e86df2/get_online_grocery_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_details

Retrieve full product details including nutritional information and ingredients for a specific product identified by its URL slug and EAN barcode. Returns structured nutrition table, ingredient list, and basic product data. The product_slug and ean can be obtained from search_products or get_category_products results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ean` | string | Yes | Product EAN barcode number (e.g. '8012666051267') |
| `product_slug` | string | Yes | Product URL slug (e.g. 'carrefour-classic-latte-uht-parzialmente-scremato-1000-ml') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-carrefour-it-api-59e86df2/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ean":"<string>","product_slug":"<string>"}'
```

### get_promotions

Retrieve currently discounted and promoted products on Carrefour Italy. Products where price differs from metric19 (original price) indicate an active discount. Returns the same product fields as search_products.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-carrefour-it-api-59e86df2/get_promotions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_store_locations

Find Carrefour store locations in Italy. Optionally filter by city name (case-insensitive). Returns store details including address, opening hours, store type (express/iper/market), geographic coordinates, and available services/departments.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name to filter stores, case-insensitive (e.g. 'MILANO', 'ROMA', 'Torino'). Omitting returns all stores. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-carrefour-it-api-59e86df2/get_store_locations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>"}'
```

### search_products

Full-text search over Carrefour Italy's online grocery catalog. query matches product names; results are paginated with configurable page size. Each product includes name, EAN id, price, original price (metric19), brand, category slug, pack size (dimension52), and food/nonfood classification (dimension53).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results per page |
| `page` | integer | No | Page number (1-based) |
| `query` | string | Yes | Search keyword (e.g. 'latte', 'pasta', 'birra') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-carrefour-it-api-59e86df2/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<string>"}'
```