# Etsy API scraper — search handmade & vintage listings, full product detail (price, variations, materials, photos), shop profiles, a shop's full paginated catalog, category browse and all customer reviews from etsy.com

> Search Etsy handmade/vintage listings by keyword — returns listing cards with id, title, price, sale price, shop, image and listing URL. Supports category, price range, sort and pagination filters.
> ReefAPI engine `etsy` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/etsy/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 /etsy/v1/listings/search — 2 credits
Search Etsy handmade/vintage listings by keyword — returns listing cards with id, title, price, sale price, shop, image and listing URL. Supports category, price range, sort and pagination filters.

**Parameters:**
- `query` (string, required) — What to search for (listing keywords).
- `max_pages` (integer, optional, default 1) — How many result pages to fetch in one call (1–10). Each page ≈ 48 listings.
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, price_asc, price_desc, recent, top_reviews]
- `min_price` (number, optional) — Minimum price filter (in the site currency, USD).
- `max_price` (number, optional) — Maximum price filter (in the site currency, USD).
- `category` (string, optional) — Restrict to an Etsy category slug (jewelry, home_and_living, clothing, art_and_collectibles, weddings, toys_and_games …).
- `free_shipping` (boolean, optional) — Only listings that ship free.

**Returns:** items[]{listing_id, title, price, currency, list_price, shop_slug, shop_id, image_url, url, is_ad}

**Example request body:**
```json
{
  "query": "silver ring"
}
```

### POST /etsy/v1/listings/detail — 2 credits
Full Etsy listing detail by listing ID or URL — title, price, sale price, currency, rating, review count, favorites (demand signal), stock-left, variations, gallery images, description, tags, materials, category and shipping estimate.

**Parameters:**
- `listing_id` (string, optional) — Etsy listing ID — the digits in the listing URL (etsy.com/listing/<id>/…). Provide listing_id OR listing_url.
- `listing_url` (string, optional) — Full listing URL — alternative to listing_id.

**Returns:** listing{listing_id, title, price, price_max, currency, original_price, on_sale, rating, review_count_display, favorites_count, stock_left, variations[], images[], image_count, description, tags[], materials[], categories[], shipping_estimate, shop_id, shop_slug, schema_product}

### POST /etsy/v1/shops/detail — 2 credits
Etsy shop profile by shop slug or URL — name, total lifetime sales, location, star rating, review count, admirers (followers), active-listings count, year opened and the shop's featured listings (deduped, with title/price/image).

**Parameters:**
- `shop_slug` (string, optional) — Shop name as it appears in the shop URL (etsy.com/shop/<slug>). Provide shop_slug OR shop_url.
- `shop_url` (string, optional) — Full shop URL — alternative to shop_slug.

**Returns:** shop{shop_slug, shop_name, sales_count, location, rating, review_count, followers_count, active_listings_count, opened_year, shop_id, featured_listings[]{listing_id, title, price, currency, image_url, url}}

### POST /etsy/v1/shops/listings — 1 credit
Browse a shop's full active catalog, paginated — every product the shop sells (not just the featured handful), with id, title, price, sale price, image and listing URL. Page through with max_pages to pull the whole inventory.

**Parameters:**
- `shop_slug` (string, optional) — Shop name from the shop URL (etsy.com/shop/<slug>). Provide shop_slug OR shop_url.
- `shop_url` (string, optional) — Full shop URL — alternative to shop_slug.
- `max_pages` (integer, optional, default 1) — How many catalog pages to fetch (1–20). Each page ≈ 36 listings.
- `sort` (enum, optional, default "custom") — Order within the shop. [one of: custom, price_asc, price_desc, recent]

**Returns:** items[]{listing_id, title, price, currency, list_price, image_url, url} + total_listings, pages_fetched

### POST /etsy/v1/listings/category — 1 credit
Browse Etsy by category (the /c/<category> grid) — discover trending/popular listings in a category without a keyword. Supports sub-categories, price range, sort and pagination.

**Parameters:**
- `category` (string, required) — Etsy category to browse. Use a top-level slug below, or a sub-path like 'jewelry/rings' / 'home_and_living/candles'. [one of: jewelry, clothing, home_and_living, wedding_and_party, toys_and_entertainment, art_and_collectibles, craft_supplies_and_tools, bags_and_purses, accessories, bath_and_beauty, books_movies_and_music, electronics_and_accessories, pet_supplies, shoes, paper_and_party_supplies]
- `max_pages` (integer, optional, default 1) — How many category pages to fetch (1–10). Each page ≈ 48 listings.
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, price_asc, price_desc, recent, top_reviews]
- `min_price` (number, optional) — Minimum price filter (USD).
- `max_price` (number, optional) — Maximum price filter (USD).
- `free_shipping` (boolean, optional) — Only listings that ship free.

**Returns:** items[]{listing_id, title, price, currency, list_price, shop_slug, image_url, url} + category, pages_fetched

**Example request body:**
```json
{
  "category": "jewelry/rings"
}
```

### POST /etsy/v1/reviews/shop — 1 credit
All reviews for an Etsy shop by numeric shop ID (bare, cookie-less).

**Parameters:**
- `shop_id` (string, required) — Numeric Etsy shop ID (from a listing's or shop's data — NOT the shop name; shops/detail returns it as shop_id).
- `limit` (integer, optional, default 100) — How many reviews to return.
- `exclude_listing_id` (string, optional) — Skip reviews belonging to this listing (advanced).

**Returns:** reviews[]{rating, text, language, created_at, photo_url, listing_id, transaction_id, reviewer}

**Example request body:**
```json
{
  "shop_id": "7357402",
  "limit": 20
}
```

### POST /etsy/v1/reviews/listing — 1 credit
Reviews for a single Etsy listing by listing ID or URL.

**Parameters:**
- `listing_id` (string, optional) — Etsy listing ID — the digits in the listing URL (etsy.com/listing/<id>/…). Provide listing_id OR listing_url.
- `listing_url` (string, optional) — Full listing URL — alternative to listing_id.
- `max_pages` (integer, optional, default 20) — How many review pages to walk (more pages = more reviews, slower).

**Returns:** reviews[]{rating, text, language, created_at, photo_url, listing_id, reviewer}

### POST /etsy/v1/search/suggest — 1 credit
Etsy search autocomplete — keyword suggestions for a partial query (no account required).

**Parameters:**
- `query` (string, required) — Partial search text to complete.
- `limit` (integer, optional, default 20) — How many suggestions to return.

**Returns:** suggestions[]{query, categories[]}

**Example request body:**
```json
{
  "query": "silver ring"
}
```

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