Shop List API
Use the Etsy shop list API to filter shops by category, price, sales, favorites, reviews, country and period. Review request parameters, cURL examples, JSON responses and Credits usage below.
/v1/shop1 Credit per returned record. If your balance is insufficient, only as many records as your remaining Credits cover are returned (partial deduction); with a zero balance, 403001 is returned. Empty results are free.·api.etshop.ai/open-apiCredits usage rules
Billing: shop/product lists and top sellers cost 1 Credit per returned record; shop details cost 2 Credits per call. Details, trends, daily data and reviews are free (the record must have been returned by a list or details call within 3 days). Keyword search costs 1 Keyword Credit per keyword, and the same keyword is free for 30 days. Shop monitoring costs 1 Monitor Credit per shop for 30 days and is not refunded when stopped. Empty results are free and server errors are refunded automatically.
Request headers
Authorization: {API Key}application/jsonapplication/jsonRequest example
curl --location --request GET 'https://api.etshop.ai/open-api/v1/shop?times=2¤t_page=1&page_size=2&order_by=sale_growth&direction=desc' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}' Request parameters
Pass each parameter in its specified location.
| Parameter | Type | Description |
|---|---|---|
| times
query · required
| integer | Statistics period for the *_growth fields and growth-based sorting: 1 yesterday, 2 last 7 days, 3 last 30 days, 4 last 90 days. |
| name
query · optional
| string | Keywords matched against shop name or headline (fuzzy). Multiple values should be comma-separated; all must match. |
| exclude_name
query · optional
| string | Exclude shops whose name or headline contains any of these keywords. Multiple values should be comma-separated. |
| star_seller
query · optional
| integer | Star Seller: 1 yes, 0 no. |
| avg_price_start
query · optional
| number | Minimum average product price (USD). |
| avg_price_end
query · optional
| number | Maximum average product price (USD). |
| total_product_num_start
query · optional
| integer | Minimum number of products. |
| total_product_num_end
query · optional
| integer | Maximum number of products. |
| created_time_start
query · optional
| string | Shop opening date (from). Format: Y-m-d, e.g. 2024-01-01. |
| created_time_end
query · optional
| string | Shop opening date (to). Format: Y-m-d, e.g. 2024-12-31. |
| average_rating_start
query · optional
| number | Minimum shop rating (0–5). |
| average_rating_end
query · optional
| number | Maximum shop rating (0–5). |
| country_code
query · optional
| string | Shop country/region code(s). Multiple values should be comma-separated. |
| sold_count_start
query · optional
| integer | Minimum total sales. |
| sold_count_end
query · optional
| integer | Maximum total sales. |
| total_rating_count_start
query · optional
| integer | Minimum total reviews. |
| total_rating_count_end
query · optional
| integer | Maximum total reviews. |
| favorites_count_start
query · optional
| integer | Minimum total favorites. |
| favorites_count_end
query · optional
| integer | Maximum total favorites. |
| views_start
query · optional
| integer | Minimum total views. |
| views_end
query · optional
| integer | Maximum total views. |
| product_type
query · optional
| string | Product type(s). Multiple values should be comma-separated. Valid options: Handmade, Digital, Vintage, Customizable, Others. |
| is_real_sale
query · optional
| integer | Whether the shop has real sales data: 1 yes, 0 no. |
| current_page
query · optional
| integer | Page number (min: 1, default: 1). |
| page_size
query · optional
| integer | Items per page (range: 1-100, default: 20). |
| order_by
query · optional
| string | Sort field. Valid options: sale_growth (sales growth in the period), view_growth (view growth in the period), collection_growth (favorite growth in the period), review_growth (review growth in the period), total_sale (total sales), total_view (total views), total_collection (total favorites), total_review (total reviews). Defaults to sale_growth. |
| direction
query · optional
| string | Sort direction. Valid options: desc (descending, default), asc (ascending). |
Response example
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": 21475836,
"image": "https://i.etsystatic.com/isla/7a1c3e/58213467/isla_fullxfull.58213467_k2m9x0qa.jpg",
"name": "LunaLinenStudio",
"url": "https://www.etsy.com/shop/LunaLinenStudio",
"star_seller": 1,
"headline": "Handmade linen bedding & table linens from Lithuania",
"total_product_num": 412,
"create_date": 1462147200,
"currency_code": "EUR",
"sold_count": 86214,
"sold_count_growth": 1342,
"total_rating_count": 15830,
"total_rating_count_growth": 187,
"favorites_count": 48270,
"favorites_count_growth": 615,
"views": 2903417,
"views_growth": 40512,
"product_type": ["Handmade", "Customizable"],
"avg_price": 68.4,
"country_code": "LT",
"best_selling_product": [
{
"id": 1284567890,
"images": ["https://i.etsystatic.com/21475836/r/il/8c1d2e/5123456789/il_fullxfull.5123456789_ab12.jpg"]
},
{
"id": 1197834562,
"images": ["https://i.etsystatic.com/21475836/r/il/42f0a9/4987654321/il_fullxfull.4987654321_cd34.jpg"]
}
]
},
{
"id": 30981254,
"image": "https://i.etsystatic.com/isla/b4d2f1/71234598/isla_fullxfull.71234598_9xq2lm3n.jpg",
"name": "PrintablePlannerCo",
"url": "https://www.etsy.com/shop/PrintablePlannerCo",
"star_seller": 0,
"headline": "Digital planners and printable templates",
"total_product_num": 1286,
"create_date": 1609459200,
"currency_code": "USD",
"sold_count": 154302,
"sold_count_growth": 1105,
"total_rating_count": 21455,
"total_rating_count_growth": 96,
"favorites_count": 30218,
"favorites_count_growth": 402,
"views": 4120584,
"views_growth": 61873,
"product_type": ["Digital"],
"avg_price": 6.25,
"country_code": "US",
"best_selling_product": [
{
"id": 1456789012,
"images": ["https://i.etsystatic.com/30981254/r/il/0e7b11/5234567890/il_fullxfull.5234567890_ef56.jpg"]
}
]
}
],
"page": {
"page_count": 238411,
"current_page": 1,
"total_count": 476822,
"page_size": 2
}
},
"credits": {
"type": "default",
"remaining_credits": 196538,
"consumed_credits": 2,
"total_credits": 196540
}
} Response structure
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
| » code | integer | true | none | Status Code |
| » message | string | true | none | Response message |
| » data | object | true | none | Response data |
| »» data | [object] | true | none | Shop list |
| »»» id | integer | true | none | Shop ID |
| »»» image | string | true | none | Shop icon |
| »»» name | string | true | none | Shop name |
| »»» url | string | true | none | Shop URL |
| »»» star_seller | integer | true | none | Star Seller: 1 yes, 0 no |
| »»» headline | string | true | none | Shop headline |
| »»» total_product_num | integer | true | none | Number of products |
| »»» create_date | integer | true | none | Shop opening time (Unix timestamp, seconds) |
| »»» currency_code | string | true | none | Shop currency |
| »»» sold_count | integer | true | none | Total sales |
| »»» sold_count_growth | integer | true | none | Sales growth in the period set by times |
| »»» total_rating_count | integer | true | none | Total reviews |
| »»» total_rating_count_growth | integer | true | none | Review growth in the period |
| »»» favorites_count | integer | true | none | Total favorites |
| »»» favorites_count_growth | integer | true | none | Favorite growth in the period |
| »»» views | integer | true | none | Total views |
| »»» views_growth | integer | true | none | View growth in the period |
| »»» product_type | [string] | true | none | Product types: Handmade, Digital, Vintage, Customizable, Others |
| »»» avg_price | number | true | none | Average product price (USD) |
| »»» country_code | string | true | none | Shop country/region code |
| »»» best_selling_product | [object] | true | none | Best-selling products (up to 3) |
| »»»» id | integer | true | none | Product ID |
| »»»» images | [string] | true | none | Main product image |
| »» page | object | true | none | Pagination |
| »»» page_count | integer | true | none | Total pages |
| »»» current_page | integer | true | none | Current page number |
| »»» total_count | integer | true | none | Total records |
| »»» page_size | integer | true | none | Items per page |
| » credits | object | true | none | Credits information of this request. See Billing Rules. |
| »» type | string | true | none | Credits type. default for this endpoint. |
| »» remaining_credits | integer | true | none | Remaining Credits after this request |
| »» consumed_credits | integer | true | none | Credits consumed by this request, equal to the number of records returned |
| »» total_credits | integer | true | none | Credits balance before this request (remaining_credits + consumed_credits) |
