YOOX APIyoox.com ↗
Search YOOX's luxury fashion catalog, browse categories, get designer lists, and fetch detailed product data including pricing, sizing, and images.
What is the YOOX API?
The YOOX API exposes 7 endpoints covering product search, category navigation, designer listings, new arrivals, and sale items from the YOOX catalog. Each product record includes current price, original price, retail price, discount percentage, available sizes, material composition, and image URLs. The get_product_detail endpoint returns the full attribute set for a single item, while search_products supports brand, price range, and sort filters across the entire catalog.
curl -X GET 'https://api.parse.bot/scraper/b0e5fca3-bf37-47ff-b329-d13dd7b3aead/search_products?page=0&limit=5&query=shoes&sort_by=price_asc&max_price=500&min_price=50' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace yoox-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: YOOX fashion API — search, browse, and drill into product details."""
from parse_apis.yoox_api import Yoox, Sort, ProductNotFound
client = Yoox()
# Search for affordable shoes sorted by price
for product in client.products.search(query="shoes", sort_by=Sort.PRICE_ASC, max_price=300, limit=5):
print(product.brand, product.name, f"${product.current_price}", product.color)
# Drill into the first result for full details
shoe = client.products.search(query="sneakers", limit=1).first()
if shoe:
detail = client.products.get(product_id=shoe.product_id)
print(detail.name, detail.composition, detail.available_sizes)
# Browse a department's designers and categories
women = client.department("women")
for designer in women.list_designers(limit=5):
print(designer.name, designer.id)
for group in women.list_categories(limit=3):
print(group.group_name, [item.name for item in group.items])
# Get sale items for women
for item in women.sale_items(limit=3):
print(item.brand, item.name, f"${item.current_price}", f"{item.discount_percentage}% off")
# Typed error handling for a missing product
try:
client.products.get(product_id="NONEXISTENT99")
except ProductNotFound as exc:
print(f"Product not found: {exc.item_code}")
print("exercised: products.search / products.get / department.list_designers / department.list_categories / department.sale_items")
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.
| Param | Type | Description |
|---|---|---|
| page | integer | Zero-based page number. |
| brand | string | Brand ID to filter by (e.g. 'FERRAGAMO-753'). Obtain from get_designers_list results. |
| limit | integer | Number of results per page. |
| queryrequired | string | Search keyword (e.g. 'shoes', 'dresses', 'jacket'). |
| sort_by | string | Sort order for results. |
| max_price | number | Maximum price filter in USD. |
| min_price | number | Minimum price filter in USD. |
{
"type": "object",
"fields": {
"page": "integer current page number",
"pages": "integer total number of pages",
"total": "integer total number of matching products",
"products": "array of product objects with product_id, name, brand, category, current_price, original_price, retail_price, currency, discount_percentage, available_sizes, images, product_url, composition, color"
},
"sample": {
"data": {
"page": 0,
"pages": 4000,
"total": 55345,
"products": [
{
"name": "GUCCI Mules & Clogs",
"brand": "GUCCI",
"color": "Black",
"images": [
"https://www.yoox.com/images/items/32/32047896te_11_d.jpg"
],
"category": "Mules & Clogs",
"currency": "USD",
"product_id": "32047896TE",
"composition": "Leather",
"product_url": "https://www.yoox.com/us/32047896TE/item",
"retail_price": 1981,
"current_price": 948,
"original_price": 1505,
"available_sizes": [
"6.5",
"7",
"7.5"
],
"discount_percentage": 37.01
}
]
},
"status": "success"
}
}About the YOOX API
Search and Browse the YOOX Catalog
The search_products endpoint accepts a required query string and optional filters for brand, min_price, max_price, and sort_by. Brand IDs follow the format BRANDNAME-NNNN (e.g. FERRAGAMO-753) and must be obtained from get_designers_list before use. Results paginate via a zero-based page parameter and return a total count alongside pages, so you can build multi-page retrieval loops. Each product object carries product_id, name, brand, category, current_price, original_price, retail_price, currency, and discount_percentage.
Department and Category Navigation
get_product_listing_by_category browses products within a department using the same product shape as search. An optional category keyword narrows results further (e.g. 'shoes' or 'jackets' within a department). To discover valid category paths, call get_categories first — it returns a grouped navigation tree with group_name and an items array of name and url pairs. To enumerate brands available in a department, get_designers_list returns an alphabetically sorted array of name and id fields.
Product Detail, New Arrivals, and Sale Items
get_product_detail takes the item_code from any listing response and returns the full record: composition, color, images (array of URLs), product_url, and retail_price, in addition to the standard pricing fields. get_new_arrivals and get_sale_items both accept an optional gender parameter and paginate the same way as search. Items returned by get_sale_items always carry a non-null discount_percentage, making them suitable for discount-monitoring workflows without additional filtering.
The YOOX API is a managed, monitored endpoint for yoox.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when yoox.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official yoox.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track price drops on designer items by comparing current_price against original_price across paginated search results
- Build a brand-specific product feed by passing a brand ID from get_designers_list into search_products
- Monitor new inventory additions by polling get_new_arrivals filtered by gender
- Aggregate sale items across departments using get_sale_items with discount_percentage for deal discovery
- Construct a category-aware product browser using the navigation tree from get_categories and listings from get_product_listing_by_category
- Enrich product records with full composition, color, and image data by chaining get_product_detail after a search
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.