# Coop (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 Coop Italy's product catalog across categories and subcategories to find detailed information about items, prices, and current offers. Discover product recommendations and get comprehensive details including availability and promotional deals to help you shop more efficiently.

**Category:** Food & Dining | **Website:** [coop.it/](https://coop.it/) | **Docs:** [parse.bot/marketplace/c98360f1-ccca-4483-b2a2-80bb6bd35b64/coop-it-api](https://parse.bot/marketplace/c98360f1-ccca-4483-b2a2-80bb6bd35b64/coop-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-coop-it-api-c98360f1/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_categories

Returns the full hierarchy of product categories from the CoopShop catalog, including up to 3 levels of nesting. Each category includes its ID, name, slug, URL, and nested subcategories.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `warehouse_id` | string | No | Warehouse ID to scope categories. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-coop-it-api-c98360f1/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"warehouse_id":"<string>"}'
```

### get_offers

Returns products currently on offer. Checks for promotional products first; if none available, returns newly added products. The offer_type field indicates which type was found ('promo' or 'new_product').

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Optional category ID to scope offers. |
| `page` | integer | No | Page number. |
| `page_size` | integer | No | Products per page. |
| `warehouse_id` | string | No | Warehouse ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-coop-it-api-c98360f1/get_offers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","page":"<integer>","page_size":"<integer>","warehouse_id":"<string>"}'
```

### get_product_details

Returns full details for a specific product by slug, including ingredients, nutritional information, allergens, media images, conservation instructions, and recycling info. The slug is obtained from search or category listing results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_slug` | string | Yes | Product slug from search or category results (e.g. 'cavatelli-secchi-coop-ff500g'). |
| `warehouse_id` | string | No | Warehouse ID. |

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

### get_products_by_category

Returns a paginated list of products for a given category ID, with optional sorting and promotional filtering. Results include product details, vendor info, media URLs, and facet filters for further refinement.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category ID to retrieve products for (e.g. '33997'). |
| `page` | integer | No | Page number. |
| `page_size` | integer | No | Products per page. |
| `promo` | boolean | No | Filter promotional products only. |
| `sort` | string | No | Sort order. |
| `warehouse_id` | string | No | Warehouse ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-coop-it-api-c98360f1/get_products_by_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","page":"<integer>","page_size":"<integer>","promo":"<boolean>","sort":"<string>","warehouse_id":"<string>"}'
```

### get_subcategories

Returns the full category object and its children (subcategories) for a given category slug. Includes breadcrumbs, metadata, SEO info, and direct child categories.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_slug` | string | Yes | Slug of the parent category (e.g. 'condimenti-conserve-e-scatolame'). |
| `warehouse_id` | string | No | Warehouse ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-coop-it-api-c98360f1/get_subcategories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_slug":"<string>","warehouse_id":"<string>"}'
```

### get_suggested_products

Returns suggested/recommended products for a given product ID. Useful for building 'you might also like' sections. The product_id is obtained from search or category listing results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max number of suggestions. |
| `product_id` | string | Yes | Product ID to get suggestions for (e.g. '603715' from search_products results). |
| `warehouse_id` | string | No | Warehouse ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-coop-it-api-c98360f1/get_suggested_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","product_id":"<string>","warehouse_id":"<string>"}'
```

### search_products

Full-text search for products by keyword query. Returns paginated results with facets for filtering by category, promotions, and brand lines. Pagination via page number.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number. |
| `page_size` | integer | No | Products per page. |
| `query` | string | Yes | Search keyword (e.g. 'pasta'). |
| `warehouse_id` | string | No | Warehouse ID. |

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