> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.ehunt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Etsy Stores 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

```text theme={null}
POST /api/v1/stores
```

***

## Authentication

Include a valid API Key in the request header:

```text theme={null}
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)

```json theme={null}
{
  "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

| Parameter         | Type   | Required | Description                                                         |
| ----------------- | ------ | -------- | ------------------------------------------------------------------- |
| search\_key       | string | No       | Search keyword or store name、url                                    |
| status            | int    | No       | Store status: 1=Active, 0=Inactive                                  |
| country           | string | No       | Store country                                                       |
| category          | string | No       | Store main category                                                 |
| sales\_weekly     | string | No       | Store weekly sales range                                            |
| sales             | string | No       | Store total sales range                                             |
| favorites         | string | No       | Store favorites count range                                         |
| favorites\_weekly | string | No       | Store weekly new favorites                                          |
| reviews           | string | No       | Store reviews count range                                           |
| reviews\_weekly   | string | No       | Store weekly new reviews                                            |
| start\_at         | string | No       | Store opening date range                                            |
| is\_star          | int    | No       | Is star store: 1=Yes                                                |
| is\_raving        | int    | No       | Is Raving store: 1=Yes                                              |
| sort\_by          | int    | No       | Sort field: 8=Total sales, 9=Weekly sales, 10=Reviews, 11=Favorites |
| desc              | int    | No       | Sort direction: 1=Descending, 0=Ascending                           |
| page\_num         | int    | No       | Page number, starts from 1                                          |
| page\_size        | int    | No       | Items per page, max 100                                             |

***

## Request Examples

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.example.com/api/v1/stores"

  headers = {
      "Content-Type": "application/json",
      "X-VIP-TOKEN": "your_api_key_here"
  }

  payload = {
      "search_key": "jewelry",
      "country": "US",
      "page_num": 1,
      "page_size": 20
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()

  print(json.dumps(data, indent=2))
  ```

  ```javascript JavaScript (Node.js) theme={null}
  const axios = require('axios');

  const url = 'https://api.example.com/api/v1/stores';

  const headers = {
    'Content-Type': 'application/json',
    'X-VIP-TOKEN': 'your_api_key_here'
  };

  const payload = {
    search_key: 'jewelry',
    country: 'US',
    page_num: 1,
    page_size: 20
  };

  axios.post(url, payload, { headers })
    .then(response => {
      console.log(JSON.stringify(response.data, null, 2));
    })
    .catch(error => {
      console.error('Error:', error.response?.data || error.message);
    });
  ```

  ```php PHP theme={null}
  <?php
  $url = "https://api.example.com/api/v1/stores";

  $headers = [
      "Content-Type: application/json",
      "X-VIP-TOKEN: your_api_key_here"
  ];

  $payload = [
      "search_key" => "jewelry",
      "country" => "US",
      "page_num" => 1,
      "page_size" => 20
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  $data = json_decode($response, true);

  curl_close($ch);

  echo json_encode($data, JSON_PRETTY_PRINT);
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      url := "https://api.example.com/api/v1/stores"
      
      payload := map[string]interface{}{
          "search_key": "jewelry",
          "country":    "US",
          "page_num":   1,
          "page_size":  20,
      }
      
      jsonData, _ := json.Marshal(payload)
      
      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("X-VIP-TOKEN", "your_api_key_here")
      
      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()
      
      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  url = URI.parse("https://api.example.com/api/v1/stores")

  headers = {
    'Content-Type' => 'application/json',
    'X-VIP-TOKEN' => 'your_api_key_here'
  }

  payload = {
    search_key: 'jewelry',
    country: 'US',
    page_num: 1,
    page_size: 20
  }

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url.path, headers)
  request.body = payload.to_json

  response = http.request(request)
  data = JSON.parse(response.body)

  puts JSON.pretty_generate(data)
  ```

  ```java Java theme={null}
  import java.io.*;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import org.json.JSONObject;

  public class StoresQuery {
      public static void main(String[] args) throws Exception {
          String url = "https://api.example.com/api/v1/stores";
          
          URL obj = new URL(url);
          HttpURLConnection con = (HttpURLConnection) obj.openConnection();
          con.setRequestMethod("POST");
          con.setRequestProperty("Content-Type", "application/json");
          con.setRequestProperty("X-VIP-TOKEN", "your_api_key_here");
          con.setDoOutput(true);
          
          JSONObject payload = new JSONObject();
          payload.put("search_key", "jewelry");
          payload.put("country", "US");
          payload.put("page_num", 1);
          payload.put("page_size", 20);
          
          OutputStream os = con.getOutputStream();
          os.write(payload.toString().getBytes());
          os.flush();
          os.close();
          
          BufferedReader in = new BufferedReader(
              new InputStreamReader(con.getInputStream())
          );
          String inputLine;
          StringBuilder response = new StringBuilder();
          
          while ((inputLine = in.readLine()) != null) {
              response.append(inputLine);
          }
          in.close();
          
          System.out.println(response.toString());
      }
  }
  ```
</CodeGroup>

***

## Response

### Response Example

```json Response theme={null}
{
  "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

| Field            | Type  | Description                              |
| ---------------- | ----- | ---------------------------------------- |
| store\_num       | int   | Total number of stores matching criteria |
| page\_size       | int   | Items per page                           |
| final\_count     | int   | Number of items returned in current page |
| list             | array | Store data list                          |
| used\_today      | int   | Credits used today                       |
| remaining\_today | int   | Remaining 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

| Code | Description                |
| ---- | -------------------------- |
| 400  | Invalid parameters         |
| 401  | Invalid or missing API Key |
| 403  | No subscription permission |
| 429  | Daily quota exhausted      |
| 500  | Internal 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

<CodeGroup>
  ```json Request theme={null}
  {
    "search_key": "",
    "status": 1,
    "is_star": 1,
    "sales": "10000~",
    "sort_by": 8,
    "desc": 1,
    "page_size": 20
  }
  ```

  ```bash cURL theme={null}
  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": "",
      "status": 1,
      "is_star": 1,
      "sales": "10000~",
      "sort_by": 8,
      "desc": 1,
      "page_size": 20
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.example.com/api/v1/stores"
  headers = {
      "Content-Type": "application/json",
      "X-VIP-TOKEN": "your_api_key_here"
  }

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

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  const response = await axios.post(
    'https://api.example.com/api/v1/stores',
    {
      search_key: '',
      status: 1,
      is_star: 1,
      sales: '10000~',
      sort_by: 8,
      desc: 1,
      page_size: 20
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-VIP-TOKEN': 'your_api_key_here'
      }
    }
  );

  console.log(response.data);
  ```
</CodeGroup>

### 2. Query Emerging Stores in Specific Country

<CodeGroup>
  ```json Request theme={null}
  {
    "search_key": "",
    "status": 1,
    "country": "US",
    "sales_weekly": "100~",
    "sort_by": 9,
    "desc": 1,
    "page_size": 20
  }
  ```

  ```bash cURL theme={null}
  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": "",
      "status": 1,
      "country": "US",
      "sales_weekly": "100~",
      "sort_by": 9,
      "desc": 1,
      "page_size": 20
    }'
  ```

  ```python Python theme={null}
  import requests

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

  response = requests.post(
      "https://api.example.com/api/v1/stores",
      headers={
          "Content-Type": "application/json",
          "X-VIP-TOKEN": "your_api_key_here"
      },
      json=payload
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await axios.post(
    'https://api.example.com/api/v1/stores',
    {
      search_key: '',
      status: 1,
      country: 'US',
      sales_weekly: '100~',
      sort_by: 9,
      desc: 1,
      page_size: 20
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-VIP-TOKEN': 'your_api_key_here'
      }
    }
  );
  ```
</CodeGroup>

### 3. Query Raving Stores (High Rating)

<CodeGroup>
  ```json Request theme={null}
  {
    "search_key": "",
    "status": 1,
    "is_raving": 1,
    "reviews": "1000~",
    "sort_by": 10,
    "desc": 1,
    "page_size": 20
  }
  ```

  ```bash cURL theme={null}
  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": "",
      "status": 1,
      "is_raving": 1,
      "reviews": "1000~",
      "sort_by": 10,
      "desc": 1,
      "page_size": 20
    }'
  ```

  ```python Python theme={null}
  import requests

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

  response = requests.post(
      "https://api.example.com/api/v1/stores",
      headers={
          "Content-Type": "application/json",
          "X-VIP-TOKEN": "your_api_key_here"
      },
      json=payload
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await axios.post(
    'https://api.example.com/api/v1/stores',
    {
      search_key: '',
      status: 1,
      is_raving: 1,
      reviews: '1000~',
      sort_by: 10,
      desc: 1,
      page_size: 20
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-VIP-TOKEN': 'your_api_key_here'
      }
    }
  );
  ```
</CodeGroup>

***

## 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