docs / etsy

Etsy

Handmade and vintage product listings and shops.

base /etsy/v16 endpoints

post/etsy/v1/listings/search1 credit

Search Etsy listings by keyword — returns listing cards with id, title, price, and favorites count (coming soon)

Parameter		Allowed / range	Description
query	required	—	What to search for (listing keywords).
max_pages = 3	optional	1–10	How many result pages to fetch in one call (1–10).

Try in playground →

post/etsy/v1/listings/detail1 credit

Full Etsy listing detail by listing ID or URL — title, price, discount, variations, gallery images, description, category, favorites count, and stock (demand signal) (coming soon)

Parameter		Allowed / range	Description
listing_id	optional	—	Etsy listing ID — the digits in the listing URL (etsy.com/listing/<id>/…). Provide listing_id OR listing_url.
listing_url	optional	—	Full listing URL — alternative to listing_id.

Try in playground →

post/etsy/v1/shops/detail1 credit

Etsy shop profile by shop slug or URL — name, total sales, location, star rating, and featured listings (coming soon)

Parameter		Allowed / range	Description
shop_slug	optional	—	Shop name as it appears in the shop URL (etsy.com/shop/<slug>). Provide shop_slug OR shop_url.
shop_url	optional	—	Full shop URL — alternative to shop_slug.

Try in playground →

post/etsy/v1/reviews/shop1 credit

shop reviews (bare, cookie-less)

Parameter		Allowed / range	Description
shop_id	required	—	Numeric Etsy shop ID (find it via a shop page's source or a listing's shop data — NOT the shop name).
limit = 100	optional	1–	How many reviews to return.
exclude_listing_id	optional	—	Skip reviews belonging to this listing (advanced).

Try in playground →

post/etsy/v1/reviews/listing1 credit

reviews for one listing

Parameter		Allowed / range	Description
listing_id	optional	—	Etsy listing ID — the digits in the listing URL (etsy.com/listing/<id>/…). Provide listing_id OR listing_url.
listing_url	optional	—	Full listing URL — alternative to listing_id.
max_pages = 20	optional	1–	How many review pages to walk (more pages = more reviews, slower).

Try in playground →

post/etsy/v1/search/suggest1 credit

Etsy search autocomplete — returns keyword suggestions for a partial query (no account required)

Parameter		Allowed / range	Description
query	required	—	Partial search text to complete.
limit = 20	optional	1–	How many suggestions to return.

Try in playground →

Example request · listings/search

curl -X POST https://api.reefapi.com/etsy/v1/listings/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}