Etsy API
The Etsy API returns handmade and vintage listings, shop and review data as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary listings/search endpoint returns items with listing id, title, price, list price, shop, image and URL (ad-flagged), and you can pull a listings/detail, a shop's detail and listings, a category, and shop or listing reviews. It is built for marketplace research, price monitoring and catalog tools that need Etsy data without a scraper. One ReefAPI key, one shared credit pool, the standard envelope.
Real request and response JSON
Captured from the indexed primary action, listings/search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/etsy/v1/listings/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "silver ring"
}
}{
"ok": true,
"meta": {
"api": "etsy",
"endpoint": "listings/search",
"mode": "live",
"latency_ms": 3305.9,
"record_count": 12,
"bytes": 0,
"cache_hit": false
},
"data": {
"query": "silver ring",
"items": [
{
"listing_id": "[redacted-phone]",
"title": "Solid 925 Sterling Silver Stacking Rings - Pick your favorite! Minimalist Midi Custom",
"url": "https://www.etsy.com/listing/[redacted-phone]/solid-925-sterling-silver-stacking-rings",
"image_url": "https://i.etsystatic.com/5780988/r/il/c03e23/[redacted-phone]/il_fullxfull.[redacted-phone]_3vwg.jpg",
"shop_slug": "JewelryBySally",
"shop_id": "5780988",
"price": "12.00",
"currency": "USD",
"list_price": null,
"is_ad": null
},
{
"listing_id": "[redacted-phone]",
"title": "2118-Handmade Sterling Silver Pattern Ring, Daily Wearing Band(2.8mm)",
"url": "https://www.etsy.com/listing/[redacted-phone]/2118-handmade-sterling-silver-pattern",
"image_url": "https://i.etsystatic.com/11956698/r/il/434a1a/[redacted-phone]/il_fullxfull.[redacted-phone]_f4a7.jpg",
"shop_slug": "MasteRetsaM",
"shop_id": "11956698",
"price": "23.10",
"currency": "USD",
"list_price": "42.00",
"is_ad": null
},
{
"listing_id": "[redacted-phone]",
"title": "Bundle of Vintage Silver Stainless Steel Spoon Rings | 2 rings for 25",
"url": "https://www.etsy.com/listing/[redacted-phone]/bundle-of-vintage-silver-stainless-steel",
"image_url": "https://i.etsystatic.com/30341384/r/il/9afaff/[redacted-phone]/il_fullxfull.[redacted-phone]_bekf.jpg",
"shop_slug": "SilverWearSilas",
"shop_id": "30341384",
"price": "25.00",
"currency": "USD",
"list_price": null,
"is_ad": null
}
],
"count": 12,
"pages_fetched": 1
}
}What the Etsy API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| listings/search | 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. | Pricing teams call listings/search to search Etsy handmade/vintage listings by keyword. | query, max_pages, sort, min_price, max_price, ... |
| listings/detail | 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. | Marketplace operators call listings/detail to get full Etsy listing detail by listing ID or URL. | listing_url, listing_id, url |
| shops/detail | 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). | Catalog enrichment teams call shops/detail to get etsy shop profile by shop slug or URL. | shop_url, shop_slug, url |
| shops/listings | 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. | Retail analysts call shops/listings to get browse a shop's full active catalog, paginated. | shop_url, shop_slug, url, max_pages, sort |
| listings/category | 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. | Pricing teams call listings/category to get browse Etsy by category (the /c/<category> grid). | category, max_pages, sort, min_price, max_price, ... |
| reviews/shop | All reviews for an Etsy shop by numeric shop ID (bare, cookie-less). | Marketplace operators call reviews/shop to get all reviews for an Etsy shop by numeric shop ID (bare, cookie-less).. | shop_id, limit, exclude_listing_id |
| reviews/listing | Reviews for a single Etsy listing by listing ID or URL. | Catalog enrichment teams call reviews/listing to get reviews for a single Etsy listing by listing ID or URL.. | listing_url, listing_id, url, max_pages |
| search/suggest | Etsy search autocomplete — keyword suggestions for a partial query (no account required). | Retail analysts call search/suggest to get etsy search autocomplete. | query, limit |
Call listings/search from your stack
curl -X POST https://api.reefapi.com/etsy/v1/listings/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"silver ring"}'import requests
r = requests.post(
"https://api.reefapi.com/etsy/v1/listings/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "silver ring"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/etsy/v1/listings/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "silver ring"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.etsy.listings/search with {"query":"silver ring"}.Who uses this API and why
- Marketplace researchers call listings/search to track prices and trends in a handmade category.
- Seller-intelligence tools use shops/listings to audit a competitor shop's full catalog.
- Product tools pull reviews/listing to gauge demand and sentiment for a listing.
Questions developers ask before integrating
What is the Etsy API?
Etsy API is a ReefAPI endpoint group for handmade and vintage product listings and shops. It returns live JSON through POST requests under /etsy/v1.
Is the Etsy API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Etsy calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Etsy login or account?
No login to Etsy is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Etsy data?
The page example is captured from a live listings/search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Etsy API use?
Etsy actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Etsy from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call etsy actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the Etsy API a Etsy scraper?
It is the managed alternative to a DIY Etsy scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same handmade and vintage product listings and shops back as clean JSON.
Why does my Etsy scraper keep getting blocked?
Most Etsy scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked or failed calls are free.