Skip to main content

​
VIP Stores Query API

​
Overview

This API is designed for VIP users to query Etsy store data, supporting multi-condition filtering by sales, favorites, reviews, country, category, etc., with sorting and pagination capabilities. Each returned store will consume corresponding API credits.
  • API Type: REST API
  • Request Method: POST
  • Data Format: JSON
  • Authentication: API Key
  • Available To: VIP / Subscription Users

​
Endpoint

POST /api/v1/stores

​
Authentication

Include a valid API Key in the request header: 
X-VIP-TOKEN: your_api_key_here
If the API Key is invalid, unsubscribed, or has insufficient credits, a corresponding error will be returned.

​
Request Parameters

​
Request Body (JSON)

{
  "search_key": "jewelry",
  "status": 1,
  "country": "US",
  "category": "Jewelry",
  "sales_weekly": "10,100",
  "sales": "100,5000",
  "favorites": "50,2000",
  "favorites_weekly": "5,200",
  "reviews": "20,1000",
  "reviews_weekly": "2,100",
  "start_at": "2020-01-01~2023-01-01",
  "is_star": 0,
  "is_raving": 0,
  "sort_by": 8,
  "desc": 1,
  "page_num": 1,
  "page_size": 20
}

​
Parameter Description

ParameterTypeRequiredDescription
search_keystringNoSearch keyword or store name、url
statusintNoStore status: 1=Active, 0=Inactive
countrystringNoStore country
categorystringNoStore main category
sales_weeklystringNoStore weekly sales range
salesstringNoStore total sales range
favoritesstringNoStore favorites count range
favorites_weeklystringNoStore weekly new favorites
reviewsstringNoStore reviews count range
reviews_weeklystringNoStore weekly new reviews
start_atstringNoStore opening date range
is_starintNoIs star store: 1=Yes
is_ravingintNoIs Raving store: 1=Yes
sort_byintNoSort field: 8=Total sales, 9=Weekly sales, 10=Reviews, 11=Favorites
descintNoSort direction: 1=Descending, 0=Ascending
page_numintNoPage number, starts from 1
page_sizeintNoItems per page, max 100

​
Request Examples

curl -X POST https://api.example.com/api/v1/stores \
  -H "Content-Type: application/json" \
  -H "X-VIP-TOKEN: your_api_key_here" \
  -d '{
    "search_key": "jewelry",
    "country": "US",
    "page_num": 1,
    "page_size": 20
  }'

​
Response

​
Response Example

Response
{
  "code": 0,
  "message": "success",
  "data": {
    "store_num": 1520,
    "page_size": 20,
    "final_count": 20,
    "list": [
      {
        "store_id": "123456",
        "store_name": "BestJewelryShop",
        "logo_url": "https://image.xxx/logo.png",
        "store_url": "https://www.etsy.com/shop/BestJewelryShop",
        "status": 1,
        "products": 320,
        "start_at": "2019-06-01",
        "sales_weekly": 120,
        "sales_total": 5600,
        "reviews": 980,
        "reviews_weekly": 12,
        "favorites": 3400,
        "favorites_weekly": 45,
        "is_star": 1,
        "is_raving": 0,
        "category": ["Jewelry"],
        "rating": 4.8,
        "country": ["US"],
        "social_info": [],
        "shop_badges": [],
        "shop_website": "https://www.etsy.com/shop/BestJewelryShop"
      }
    ]
  },
  "used_today": 80,
  "remaining_today": 920
}

​
Response Fields

FieldTypeDescription
store_numintTotal number of stores matching criteria
page_sizeintItems per page
final_countintNumber of items returned in current page
listarrayStore data list
used_todayintCredits used today
remaining_todayintRemaining credits today

​
Credit Consumption Rules

  • Each returned store consumes 1 credit
  • Actual credit consumption = final_count
  • Returns 429 error when daily credits are insufficient

​
Error Codes

CodeDescription
400Invalid parameters
401Invalid or missing API Key
403No subscription permission
429Daily quota exhausted
500Internal server error

​
Use Cases

  • Etsy store screening and research
  • High-sales / high-rating store discovery
  • Competitor store monitoring
  • Market size and trend analysis

​
Query Scenarios

​
1. Query Star Premium Stores

{
  "search_key": "",
  "status": 1,
  "is_star": 1,
  "sales": "10000~",
  "sort_by": 8,
  "desc": 1,
  "page_size": 20
}

​
2. Query Emerging Stores in Specific Country

{
  "search_key": "",
  "status": 1,
  "country": "US",
  "sales_weekly": "100~",
  "sort_by": 9,
  "desc": 1,
  "page_size": 20
}

​
3. Query Raving Stores (High Rating)

{
  "search_key": "",
  "status": 1,
  "is_raving": 1,
  "reviews": "1000~",
  "sort_by": 10,
  "desc": 1,
  "page_size": 20
}

​
Important Notes

  • Recommended to control page_size reasonably to avoid unnecessary credit consumption
  • Multi-condition filtering may increase query time
  • Response data is sourced from Etsy public information and is for analysis use only
Last Updated: 2026-01-14
Maintained By: EHunt API Team