# Yoox — 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 YOOX's fashion catalog to discover products by category, designer, new arrivals, and sale items. Get detailed product information to find exactly what you're looking for across the YOOX marketplace.

**Category:** E-commerce | **Website:** [yoox.com/](https://yoox.com/) | **Docs:** [parse.bot/marketplace/9a88c27f-1654-4db1-acdb-dfd45639dd23/yoox-com-api](https://parse.bot/marketplace/9a88c27f-1654-4db1-acdb-dfd45639dd23/yoox-com-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/yoox/`
**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 categories

Retrieve the navigation category tree for a department. Returns grouped categories (e.g. Clothing, Shoes, Accessories) with names and relative URLs. Useful for discovering browsable sections within a department.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `department` | string | No | Department to get categories for. |

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

### Get designers list

List all designers (brands) available in a department. Each designer has a display name and an ID suitable for use as the brand filter in search_products. Sorted alphabetically by name.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `department` | string | No | Department to get designers for. |

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

### Get new arrivals

Get recently added products for a gender. Paginates via zero-based page number. Returns the same product shape as search_products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `gender` | string | No | Gender for new arrivals. |
| `limit` | integer | No | Number of results per page. |
| `page` | integer | No | Zero-based page number. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yoox/get-new-arrivals \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"gender":"<string>","limit":"<integer>","page":"<integer>"}'
```

### Get product detail

Fetch full details for a single product by its item code. Returns pricing, sizing, composition, images, and other attributes. The item_code is obtained from search_products or get_product_listing_by_category results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_code` | string | Yes | The unique YOOX item code (e.g. '32047896TE'). Obtain from search_products or get_product_listing_by_category results[*].product_id. |

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

### Get product listing by category

Browse products within a department with optional category keyword filter. Paginates via zero-based page number. Returns the same product shape as search_products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Optional category keyword to filter within the department (e.g. 'shoes', 'dresses', 'jackets'). |
| `department` | string | Yes | Department to browse. |
| `limit` | integer | No | Number of results per page. |
| `page` | integer | No | Zero-based page number. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yoox/get-product-listing-by-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","department":"<string>","limit":"<integer>","page":"<integer>"}'
```

### Get sale items

Get discounted products for a gender. Paginates via zero-based page number. Returns the same product shape as search_products. All returned items have a non-null discount_percentage.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `gender` | string | No | Gender for sale items. |
| `limit` | integer | No | Number of results per page. |
| `page` | integer | No | Zero-based page number. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/yoox/get-sale-items \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"gender":"<string>","limit":"<integer>","page":"<integer>"}'
```

### Search products

Full-text search across the YOOX catalog. Supports price range filters, brand filtering, and sort order. Paginates via zero-based page number. Each product includes pricing (current, original, retail), available sizes, images, composition, and color.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand` | string | No | Brand ID to filter by (e.g. 'FERRAGAMO-753'). Obtain from get_designers_list results. |
| `limit` | integer | No | Number of results per page. |
| `max_price` | number | No | Maximum price filter in USD. |
| `min_price` | number | No | Minimum price filter in USD. |
| `page` | integer | No | Zero-based page number. |
| `query` | string | Yes | Search keyword (e.g. 'shoes', 'dresses', 'jacket'). |
| `sort_by` | string | No | Sort order for results. |

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