Etsy

List Etsy shop listings

List an Etsy shop's active listings, 36 a page in the order you choose, with the shop's rating, sales, location and owners.

GET/v1/etsy/shop/listings
x-api-keystringheader

API key (`sfk_...`)

Parameters
3
shopstringrequiredquery

Etsy shop name, e.g. `PlanetJune`: the last part of the shop's address. A shop URL such as https://www.etsy.com/shop/PlanetJune is also accepted. Not case-sensitive.

sortstringoptionalquery

Order: `custom` (the shop's own order), `newest`, `price_asc` or `price_desc`. Omit for the shop's default order.

one of: custom, newest, price_asc, price_desc

cursorstringoptionalquery

Pass `page.nextCursor` from the previous response to get the next page. Omit it for the first page.

min 1 chars · max 256 chars · pattern: ^[A-Za-z0-9_-]+$

Response fields
40

Endpoint-specific response payload.

datalookupStatus
string

Whether the item was found. `not_found` covers an id or name that doesn't exist and a listing or shop that was removed or closed (Etsy doesn't tell those apart).

one of: found, not_found

datashopName
string

The shop asked for.

The shop when found; otherwise null.

datashopshopId
stringnullable

Numeric shop id, e.g. `5158258`.

datashopname
string

Shop name, e.g. `PlanetJune`.

datashopurl
string

The shop's Etsy address.

datashopheadline
stringnullable

The shop's one-line headline, as its page shows it.

datashoplocation
stringnullable

Where the shop is, e.g. `Waterloo, Canada`.

datashoplogoUrl
stringnullable

The shop's icon.

datashopbannerUrl
stringnullable

The shop's banner picture.

Names of the people the shop lists as running it.

datashopowners[]
stringoptional
datashoprating
numbernullable

Average review rating across the shop, 0 to 5.

≥ 0 · ≤ 5

datashopreviewCount
integernullable

How many reviews the shop has.

≥ 0

datashopsalesCount
integernullable

How many sales the shop page shows, when it shows them.

≥ 0

The shop's active listings on this page, in the order asked for; empty past the last page or for a shop with none.

datalistings[]listingId
string

Listing id: pass it to the listing endpoints.

datalistings[]title
string

Listing title.

datalistings[]url
string

The listing's Etsy address, without tracking parameters, e.g. `https://www.etsy.com/listing/1136507412/opal-inlay-huggie-earrings-set-by`.

datalistings[]imageUrl
stringnullable

Main picture, full size.

datalistings[]price
numbernullable

Price as shown, in `currency`, e.g. `26.25`: the sale price when the listing is on sale.

≥ 0

datalistings[]originalPrice
numbernullable

Price before the sale, when the listing is on sale; otherwise null.

≥ 0

datalistings[]currency
stringnullable

ISO 4217 currency code of the prices, e.g. `USD`.

datalistings[]shopId
stringnullable

Numeric id of the shop selling it, e.g. `10204022`.

datalistings[]shopName
stringnullable

Name of the shop selling it, e.g. `CaitlynMinimalist`; null where the list doesn't show it (similar listings).

datalistings[]isAd
boolean

Whether Etsy shows the listing as an ad (a seller paid for the spot). Always false in a shop's own listings.

datalistings[]freeShipping
boolean

Whether the list shows free shipping to the US for it.

Pagination state for the current page.

datapagepage
integer

This page's number, from 1.

≥ 0

datapagehasMore
boolean

Whether another page is available.

datapagenextCursor
stringnullable

Pass as `cursor` to get the next page; null on the last page.

datapagetotalListings
integernullable

How many listings the whole list has, as Etsy counts them.

≥ 0

datatruncated
boolean

Whether the list stops before the shop's last listing: true on page 100 of a longer catalogue (`page.totalListings` has the full count).

Metadata describing the request and billing outcome.

metarequestId
string

Unique request identifier for tracing this API call.

min 1 chars

metacreditsCharged
integer

Credits charged for this request.

≥ 0

metaversion
string

Public API version that served the response.

one of: v1

metastale
booleanoptional

Present, and `true`, only when the source couldn't be reached and this is the last good answer for the same request instead, up to 24 hours old. Absent on every live answer.

one of: true

metafetchedAt
stringoptional

When a stale answer (`stale: true`) was originally fetched (ISO 8601, UTC). Absent on every live answer.

Code example

curl "https://api.socialfetch.dev/v1/etsy/shop/listings?shop=PlanetJune" \
  -H "x-api-key: YOUR_API_KEY"

Responses

The shop and one page of its listings, or `not_found`.