Etsy API endpoint
Lists the listings in an Etsy shop, identified by the required `id` (a numeric shop id or a shop name). Narrow with `q` to filter within the shop's own catalogue, and page with `offset` (default 0) and `limit` (default 24). Each listing has its id, title, URL, image, price, currency, quantity, shop rating and sold-out flag.
/etsy/shop/{id}/listingsReturns a shop's listing catalog, optionally filtered by keyword.
Path parameters:
id (required) — numeric Etsy shop id or shop name.Query parameters:
q (optional) — keyword filter within the shop's own catalog.offset (optional, default 0) — 0-based listing offset.limit (optional, default 24) — page size.Response includes a listings array of {listing_id, title, url, image, price, price_int, currency, shop_id, shop_name, shop_rating, is_sold_out, quantity}.
| Field | Filled in, of 24 checked | Values in the sample |
|---|---|---|
| listing_id | 24 | |
| title | 24 | median 138 characters |
| url | 24 | etsy.com |
| image | 24 | i.etsystatic.com |
| price | 24 | 51.25 to 462.76, median 105.05 |
| price_int | 24 | 5,125 to 46,276, median 10,505 |
| currency | 24 | USD in all 24 |
| shop_id | 24 | |
| shop_name | 24 | gaguatelier in all 24 |
| shop_rating | 24 | 4.94 |
| quantity | 24 | 1 to 14, median 1 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| id (path) | string | Yes | Numeric Etsy shop id or shop name | gaguatelier | |
| q | string | No | Keyword filter within the shop's own catalog | mug | |
| offset | integer | No | 0-based listing offset | 0 | |
| limit | integer | No | Page size (default 24) | 24 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/etsy/shop/gaguatelier/listings?q=coffee&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"shop_id": "87654321",
"shop_name": "gaguatelier",
"query": "mug",
"offset": 0,
"listings": [
{
"listing_id": "1044347578",
"title": "Handmade Ceramic Mug",
"price": "$29.99",
"price_int": 2999,
"currency": "USD"
}
]
}
}Request schema
No body schema
Response schema
#/definitions/etsy.shopListingsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | etsy.MobileShopListings | No | ||||
| data.listings | array | No | MobileListingCard record, 12 fields: currency, image, is_sold_out, listing_id, price, price_int, quantity, shop_id, shop_name, shop_rating, title, url. Described under Etsy Product Search API. | |||
| data.offset | integer | No | 0 | |||
| data.query | string | No | ||||
| data.shop_id | string | No | 12345678 | |||
| data.shop_name | string | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/etsy/shop/gaguatelier/listings?q=coffee&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"