# Amazon (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 retrieve product data from Amazon Italy (amazon.it), including listings, detailed product info, category hierarchies, and bestseller rankings.

**Category:** E-commerce | **Website:** [amazon.it/](https://amazon.it/) | **Docs:** [parse.bot/marketplace/95878171-7d43-4c62-94e2-49571a580c58/amazon-it-api](https://parse.bot/marketplace/95878171-7d43-4c62-94e2-49571a580c58/amazon-it-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/amazon-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 best sellers

Get best-selling products for a specific department on Amazon Italy. Returns up to 30 ranked products with title, ASIN, price, and rating. Use get_categories to discover valid department slugs. Omitting the department returns the overall best sellers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `department` | string | No | Department slug from get_categories (e.g. 'electronics', 'books', 'pc', 'toys'). Omitting returns the overall best sellers. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/amazon-italy/get-best-sellers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"department":"<string>"}'
```

### Get categories

Get the top-level product category hierarchy from Amazon Italy. Returns category names, URL slugs, and links to the bestseller page for each department. Use the slug values as input to get_best_sellers.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/amazon-italy/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get product details

Get comprehensive details for a specific product on Amazon Italy by ASIN. Returns title, brand, pricing, specifications, bullet points, images, and ratings. Some fields may be null if not available on the product page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `asin` | string | Yes | Amazon Standard Identification Number (10-character alphanumeric product ID, e.g. 'B0DSGDJLG4'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/amazon-italy/get-product-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"asin":"<string>"}'
```

### Get search results csv

Search products and return results sorted by price ascending. Returns the same product fields as search_products but pre-sorted by price. Useful for finding the cheapest options for a given keyword.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (e.g. 'smartphone', 'cuffie bluetooth'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/amazon-italy/get-search-results-csv \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Search products

Full-text search over Amazon Italy product listings. Returns products matching the keyword with title, price, rating, and ASIN. Optionally sort by price ascending. Results are from the first page of search (up to ~48 products). Sponsored listings are excluded.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (e.g. 'laptop', 'cuffie bluetooth'). |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/amazon-italy/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>","sort":"<string>"}'
```

## Next steps

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