# Zappos API — search zappos.com for shoes, boots, sandals, clothing, bags, accessories, eyewear and watches, and pull a full product with every colourway, every size and width, per-variant price, per-variant units in stock, ASIN, UPC, brand, description, measurements, ratings and images — no API key or account required

> Search the Zappos catalog. Give a `query` ('running shoes', 'hiking boots', 'nike air max', 'womens dresses') and get back 100 products per page, each with Zappos' own product id, style id and colour id, price and list price, discount, units in stock, star rating, review count, badges, the full image set, and the product's OTHER colourways inline. Narrow with brand, colour, gender, size, width, department, category, material, style, feature, occasion, pattern, theme, price bucket and an on-sale switch; sort by price, rating, newest or best sellers. Every filter value your query actually supports — with the number of products behind it — is returned in `filters_available`, so you never have to guess.
> ReefAPI engine `zappos` · 2 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/zappos/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /zappos/v1/search — 1 credit
Search the Zappos catalog. Give a `query` ('running shoes', 'hiking boots', 'nike air max', 'womens dresses') and get back 100 products per page, each with Zappos' own product id, style id and colour id, price and list price, discount, units in stock, star rating, review count, badges, the full image set, and the product's OTHER colourways inline. Narrow with brand, colour, gender, size, width, department, category, material, style, feature, occasion, pattern, theme, price bucket and an on-sale switch; sort by price, rating, newest or best sellers. Every filter value your query actually supports — with the number of products behind it — is returned in `filters_available`, so you never have to guess.

**Parameters:**
- `query` (string, required) — What to search for on zappos.com — a category ('running shoes', 'hiking boots', 'womens dresses'), a brand + category ('nike air max', 'ugg slippers'), or a product name. Zappos auto-narrows obvious queries to a department (searching 'running shoes' selects Shoes for you); whatever it decided is reported back in `applied_filters`.
- `max_results` (integer, optional, default 100) — How many products to return (1-400). Zappos paginates 100 per page; asking for more than 100 fetches the following pages automatically, up to four.
- `page` (integer, optional, default 1) — Which result page to start from (1-based, 100 products per page). Page until `meta.pagination.has_more` is false.
- `sort` (enum, optional) — Result ordering, using Zappos' own six options. Omit for Zappos' relevance ranking. NOTE (measured, not a bug): every ordering other than relevance also DROPS the products that have no value for the sort key — sorting 'hiking boots' by rating takes the result count from 462 to 343, because 119 products have no rating yet. `meta.pagination.total_results` always reports the count for the request you actually made. [one of: relevance, newest, rating, best_sellers, price_low, price_high]
- `brand` (string, optional) — Only this brand, written the way Zappos writes it (Nike, adidas, Merrell, UGG, Dr. Martens). The full brand list for your query, with result counts, comes back in `filters_available.realBrandNameFacet`.
- `color` (string, optional) — Only this colour family — Zappos groups colours into about fourteen families (Black, Brown, Gray, White, Blue, Green, Red, Pink, Purple, Tan, Multi, Metallic, Yellow, Orange). Live values in `filters_available.colorFacet`.
- `gender` (string, optional) — Men, Women, Boys or Girls — Zappos' own audience facet. Live values in `filters_available.txAttrFacet_Gender`.
- `size` (string, optional) — Only products available in this size. Zappos uses a different size facet per audience (Men's Shoe Size, Women's Shoe Size, Kids' Shoe Sizes, clothing sizes), so pass the size the way it is printed — '10', '10.5', 'Large', '8 Toddler' — and the engine picks the size facet your query actually offers. Live values are the `filters_available` entries whose label contains 'Size'.
- `width` (string, optional) — Only products available in this width — Narrow, Medium, Wide, Extra Wide, Extra-Extra Wide (footwear only). Live values are the `filters_available` entries whose label contains 'Width'.
- `category` (string, optional) — Zappos' second-level category (Boots, Sneakers & Athletic Shoes, Sandals, Hiking, Dresses, Backpacks…). Live values in `filters_available.zc2`.
- `department` (string, optional) — Zappos' top-level department (Shoes, Clothing, Bags, Accessories, Eyewear, Watches). Live values in `filters_available.zc1`.
- `material` (string, optional) — Leather, Suede, Canvas, Mesh, Nylon, Rubber, Synthetic, Textile. Live values in `filters_available.txAttrFacet_Materials`.
- `style` (string, optional) — Zappos' style facet (Athletic, Bootie, Chukka, Comfort, Duck Boot, Western…). Live values in `filters_available.txAttrFacet_Styles`.
- `feature` (string, optional) — A product feature Zappos tags (Waterproof, Arch Support, Insulated, Lightweight, Slip Resistant, Moisture Wicking…). Live values in `filters_available.txAttrFacet_Features`.
- `occasion` (string, optional) — Athletic, Casual, Dress, Outdoor, Work & Duty. Live values in `filters_available.txAttrFacet_Occasion`.
- `pattern` (string, optional) — Camo, Distressed, Logo, Quilted, Solid, Woven… Live values in `filters_available.txAttrFacet_Pattern`.
- `theme` (string, optional) — Action Sports, Summer, Western, Winter. Live values in `filters_available.txAttrFacet_Theme`.
- `price_range` (string, optional) — One of Zappos' price buckets — '$50 and Under', '$100 and Under', '$200 and Under', '$200 and Over'. Zappos publishes buckets, not a free min/max range; live values in `filters_available.priceFacet`.
- `on_sale` (boolean, optional, default false) — Only products Zappos currently marks as on sale.

**Returns:** products[]{product_id, style_id, color_id, name, brand, product_type, color, color_detail, genders[], url, price, original_price, currency, on_sale, percent_off, discount_amount, in_stock, units_available, low_stock, is_new, rating, style_rating, review_count, image, images[]{view, url}, swatch_image, has_fabric_swatch, is_couture, badges[], promo_badges[], other_colors[]{style_id, color_id, color, color_detail, price, original_price, percent_off, units_available, rating, review_count, image, url}} + filters_available{<zappos facet field>: {label, multi_select, values[]{value, label, count, selected, apply_url}}} + search{term, original_term, corrected_from, heading, applied_filters}. meta.pagination{page, per_page, total_results, page_count, returned, has_more, next_page}; meta.filters{applied, ignored}. Honest caveats: `units_available` is Zappos' live stock count for that colourway summed over its sizes — search does NOT break it down per size, which is what `product_detail` is for; `rating` is the product-level star average and `style_rating` the colourway's, and both are 0 (not null) on products with no reviews yet, exactly as Zappos publishes them; `other_colors` is present only when Zappos ships the sibling colourways on the card; `swatch_image` exists only for products with a fabric swatch; a filter whose value your query does not offer is reported in `meta.filters.ignored` and is never silently dropped.

**Example request body:**
```json
{
  "query": "running shoes",
  "max_results": 40
}
```

### POST /zappos/v1/product_detail — 2 credits
Get one Zappos product in full, by its product id (or its zappos.com URL) — brand, category, gender, the marketing description and every specification bullet, the parsed physical measurements (weight, heel height, shaft, circumference, platform height, bag depth and strap drop where Zappos lists them), size charts, the customer rating with its star histogram and the runs-small / runs-wide / arch-support breakdowns, and the two customer reviews Zappos embeds. Every colourway is returned with its own style id, colour id, price, list price, image set and stock, and the selected colourway is broken down to the SIZE x WIDTH level: one row per purchasable variant with Zappos' stock id, the Amazon ASIN, the manufacturer UPC, that variant's own price and list price, and how many units are in stock right now.

**Parameters:**
- `product_id` (string, required) — Zappos' own PRODUCT id — the number in a zappos.com/product/<id> URL, the `sku` in their schema.org data, and the `product_id` on every `search` result. Always a string of digits; never hashed, composed or re-derived. A style id is NOT accepted here (Zappos does not serve /product/<styleId>) — pass it as `style_id` instead. You may pass the full product URL in `url` rather than this.
- `color_id` (string, optional) — Which colourway to put in `selected_color`. Zappos' own colour id, exactly as `search` returns it. Omit to get the colourway Zappos shows by default. If the id does not belong to this product the call fails with NOT_FOUND and lists the ids that do — it never quietly returns a different colour.
- `style_id` (string, optional) — Alternative colour selector: Zappos' STYLE id (their SKU for one colourway of one product), as returned by `search`. Resolved to its colour inside the product payload, so it costs no extra request. Use `color_id` OR `style_id`.
- `url` (string, optional) — A full zappos.com product URL — an alternative to `product_id` (+ `color_id`). Both the short /product/<id>/color/<id> form and the long /p/<slug>/product/<id>/color/<id> form are accepted.
- `include_all_color_variants` (boolean, optional, default false) — By default the per-size variant list (stock id, ASIN, UPC, price, units in stock) is returned for the SELECTED colour, and the other colourways come back summarised (price, price range, in-stock flag, variant count). Set true to get the full size grid for EVERY colourway in one response — no extra request, just a much larger payload (a 22-colour sneaker is ~370 variants).

**Returns:** product{product_id, name, full_name, brand, brand_id, brand_url, product_type, category, gender, url, product_url, description, bullets[], measurements{}, size_charts[]{label, url}, breadcrumbs[]{name, url}, video{title, url, embed_url, thumbnail}, rating{average, review_count, histogram_pct, fit_size, fit_width, fit_arch}, fit{size, width, arch}, sample_reviews[]{review_id, rating, text, author, author_byline, date, up_votes, verified_purchase, incentivised, has_media, comfort_rating, look_rating, fit_size, fit_width, fit_arch, also_owns}, color_count, price_min, price_max, currency} + selected_color{color_id, style_id, color, url, price, original_price, percent_off, on_sale, final_sale, badge, image, images[]{view, url}, variant_count, in_stock_variant_count, in_stock, units_available, price_min, price_max, size_axis, widths[], size_ranges[], variants[]{stock_id, asin, upc, size, size_label, size_group, size_system, size_range, size_id, width, width_id, dimensions{}, price, original_price, currency, on_sale, in_stock, units_available, is_placeholder}} + colors[] (the same shape for every colourway; `variants` only on the selected one unless include_all_color_variants=true). Honest caveats: per-variant price IS published and is returned verbatim — it is NOT copied down from the colourway, and where a size genuinely carries no price of its own the field is null rather than filled in; sold-out sizes are still listed, but Zappos replaces their stock id with a synthetic `out_of_stock_…` token and blanks the ASIN/UPC, so those rows come back with `stock_id: null`, `asin: null`, `upc: null` and `is_placeholder: true`; `fit` is null when no customer has rated the fit (Zappos renders its default text at 0%, which we do not pass off as data); `measurements` exists only for the categories Zappos measures (footwear and bags — not clothing, watches or eyewear); `video` and `size_charts` are per-product and usually absent; `sample_reviews` is at most TWO — the most- and least-upvoted — because that is all Zappos embeds in the product page.

## More
- Try it live, no code: https://reefapi.com/playground?engine=zappos
- Human docs page: https://reefapi.com/docs/zappos
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt