> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/etsy>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/etsy.mdx>

---

# Etsy API. Listings, shops and prices as JSON.

A listing with its price, pictures, shop and newest reviews, every active listing in a shop, the listings Etsy recommends beside one, and search box suggestions. 4 routes under `/v1/etsy`, one credit per request.

- 4 routes
- Listings + shops
- 1 credit per request

Social Fetch exposes 4 routes under `/v1/etsy`. Every response uses the `{ data, meta }` envelope, and the listing and shop routes carry `data.lookupStatus`: `found` or `not_found`. HTTP 200 only means the request finished, so branch on `lookupStatus` before storing a row.

Etsy names every listing by a numeric id, the number in its address (`/listing/1136507412/...` is `1136507412`), and every shop by its name, the last part of its address (`/shop/PlanetJune`). Each route takes either the id or name, or the Etsy link itself. Prices are in US dollars, as a visitor to the US site sees them.

`GET /v1/etsy/listing` reads one listing with its title, description, price and sale price, the price range across its options, stock, pictures, video, category, materials, shop, rating, newest reviews, where it ships from and the shop's FAQs. `GET /v1/etsy/listing/similar` lists the listings Etsy recommends beside it, with ads kept and marked. `GET /v1/etsy/shop/listings` reads a shop (headline, location, owners, rating, review and sales counts) with one page of its active listings, 36 a page, in the shop's order, newest first or by price. `GET /v1/etsy/search/suggestions` answers the searches Etsy's search box suggests for a partial query.

## What you can get

- Any listing by id or Etsy link: title, description, price, sale price, price range across options, stock and quantity.
- Listing pictures and video, category path, materials, the shop selling it and where it ships from, with US shipping price.
- The listing's rating, review count and newest reviews, plus the shop's frequently asked questions.
- A shop by name or link: headline, location, owners, logo, banner, rating, review count and sales count.
- Every active listing in a shop, 36 a page, in the shop's own order, newest first or by price, with sale prices and free shipping.
- The listings Etsy recommends beside a listing, with ads marked.
- The searches Etsy's search box suggests for a partial query, best first.

## Etsy endpoints

| Endpoint | Request | Credits | Docs |
| --- | --- | --- | --- |
| Listing | GET /v1/etsy/listing | 1 credit Failed requests are free A not-found answer is still charged | [docs](https://www.socialfetch.dev/docs/api/v1/etsy/listing/get) |
| Similar listings | GET /v1/etsy/listing/similar | 1 credit Failed requests are free A not-found answer is still charged | [docs](https://www.socialfetch.dev/docs/api/v1/etsy/listing/similar/get) |
| Shop listings | GET /v1/etsy/shop/listings | 1 credit Failed requests are free A not-found answer is still charged | [docs](https://www.socialfetch.dev/docs/api/v1/etsy/shop/listings/get) |
| Search suggestions | GET /v1/etsy/search/suggestions | 1 credit Failed requests are free A not-found answer is still charged | [docs](https://www.socialfetch.dev/docs/api/v1/etsy/search/suggestions/get) |

## How to start

1. **Create an API key.** Sign up at Social Fetch and copy a key (`sfk_…`). New accounts get 100 free credits, enough to try every Etsy route on real listings and shops.
2. **Pass an id, a name or a link.** Call `GET /v1/etsy/listing?listing=1136507412` or `GET /v1/etsy/shop/listings?shop=PlanetJune`. A listing or shop link works too. Send `x-api-key` on every request.
3. **Branch, page and bill.** Check `data.lookupStatus` before writing a row. Follow `page.nextCursor` while `page.hasMore` is true. Bill from `meta.creditsCharged` and log `meta.requestId` for support.

## Pricing

Every Etsy route charges 1 credit per completed request, a not-found answer included. Each page of a shop's listings is its own request. Credits never expire on pay-as-you-go packs. `meta.creditsCharged` on every response is the billing source of truth.

## Compared with the official API

Etsy's own Open API is built for sellers and approved apps: it needs a registered app and key, and requests are rate limited per app. Social Fetch returns the public listings, shops and suggestions any visitor sees, with no app to register, under one JSON envelope with typed `lookupStatus` values and absolute links. Pictures are linked, never rehosted.

## FAQ

### Is there an Etsy API for listings and shops?

Yes. Social Fetch has 4 Etsy routes under /v1/etsy: a listing, similar listings, a shop's listings and search suggestions. Authenticate with your Social Fetch API key in x-api-key.

### What is a listing id, and where do I find one?

Etsy's number for a listing: the number in its address, so https://www.etsy.com/listing/1136507412/opal-inlay-huggie-earrings-set-by is 1136507412. Every row of a shop's listings and the similar listings carries it as listingId. You can also pass the link itself.

### How do I list every product in an Etsy shop?

Call GET /v1/etsy/shop/listings with the shop's name, such as PlanetJune, or its link. Follow page.nextCursor while page.hasMore is true; page.totalListings counts the whole catalogue. The list stops at page 100 and says so with truncated.

### Do I get sale prices?

Yes. price is the price as shown, the sale price when the listing is on sale, and originalPrice is the price before the sale. On a listing, minPrice and maxPrice give the range across its options. Prices are in US dollars.

### Which reviews are included?

A listing carries its rating, its review count and the newest reviews its page shows, up to 4, each with the stars, date, text and the buyer's name as Etsy shows it. A shop carries its own rating and review count.

### How much does the Etsy API cost?

Every Etsy route charges 1 credit per completed request. New accounts start with 100 free credits. Check meta.creditsCharged on each response for the amount actually billed.

### Does HTTP 200 mean the listing exists?

No. HTTP 200 means the request finished. Check data.lookupStatus: found means it was read, not_found means no listing or shop has the id or name, or it was removed or closed.

## Related

- [Etsy Listing API](https://www.socialfetch.dev/platforms/etsy/listing): One listing with its price, pictures, shop and reviews (`GET /v1/etsy/listing`).
- [Etsy Shop Listings API](https://www.socialfetch.dev/platforms/etsy/shop-listings): A shop and every active listing in it (`GET /v1/etsy/shop/listings`).
- [Etsy Similar Listings API](https://www.socialfetch.dev/platforms/etsy/listing-similar): Listings Etsy recommends beside a listing (`GET /v1/etsy/listing/similar`).
- [Etsy Search Suggestions API](https://www.socialfetch.dev/platforms/etsy/search-suggestions): What Etsy's search box suggests for a partial query (`GET /v1/etsy/search/suggestions`).
- [Ask in plain English](https://www.socialfetch.dev/ask): Route a natural-language listing, shop or price question to the matching Etsy operation.
- [Hosted MCP](https://www.socialfetch.dev/mcp): Call Etsy tools from Cursor or Claude with the same credit metering as REST.
