# Amazon (Spain) — 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 retrieve product data from Amazon.es. Supports keyword search with filters (price, brand, rating, delivery), product detail lookup by ASIN, autocomplete suggestions, and best-seller browsing.

**Category:** E-commerce | **Website:** [amazon.es/](https://amazon.es/) | **Docs:** [parse.bot/marketplace/a23f30eb-a31e-48b4-97ea-7a7b2b80e871/amazon-es-api](https://parse.bot/marketplace/a23f30eb-a31e-48b4-97ea-7a7b2b80e871/amazon-es-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/amazon-spain/`
**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

Retrieve the current best-selling products on Amazon.es. Returns a ranked list of up to 50 product ASINs. Optionally filter by category node path segment.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_node` | string | No | Category path segment to filter best sellers (e.g. 'electronics', 'toys') |

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

### Get product details

Fetch comprehensive product information by ASIN, including title, price, brand, star rating, image gallery, bullet-point features, technical specification table, and product description. Some fields (description, ingredients, upc) may be null depending on product type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `asin` | string | Yes | Amazon Standard Identification Number (10-character alphanumeric product ID) |

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

### Get search suggestions

Retrieve autocomplete search suggestions for a query prefix from Amazon.es. Returns up to 10 keyword suggestions ordered by relevance. Useful for building type-ahead search interfaces.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search prefix (partial or full word) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/amazon-spain/get-search-suggestions \
  -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.es product listings. Returns paginated results with product title, price, rating, and ASIN. Supports filtering by price range, brand, minimum star rating, category, and delivery speed. Paginates via integer page number; each page contains up to ~50 results. An empty items array on a valid query means no products matched the filters.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand` | string | No | Filter results to a specific brand name |
| `category` | string | No | Department or category alias to narrow search scope (e.g. 'electronics', 'computers') |
| `fast_delivery` | boolean | No | When true, filters for Prime-eligible / 1-day delivery products |
| `max_price` | number | No | Maximum price in EUR |
| `min_price` | number | No | Minimum price in EUR |
| `min_rating` | integer | No | Minimum average star rating (1-5) |
| `page` | integer | No | Page number (1-based) |
| `query` | string | Yes | Search keyword or phrase |
| `sort` | string | No | Sort order for results |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/amazon-spain/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"brand":"<string>","category":"<string>","fast_delivery":"<boolean>","max_price":"<number>","min_price":"<number>","min_rating":"<integer>","page":"<integer>","query":"<string>","sort":"<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.