# Carrefour Italy — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/carrefour-italy/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/carrefour-italy/get-category-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/carrefour-italy/get-online-grocery-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/carrefour-italy/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/carrefour-italy/get-promotions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/carrefour-italy/get-store-locations \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/carrefour-italy/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.