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

## Overview

This API is designed for **VIP users to query product data** on Etsy, supporting multi-dimensional filtering (sales, price, favorites, reviews, etc.), sorting, and pagination. Each returned product 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/items
```

***

## Authentication

Include your API Key in the request header:

```text theme={null}
X-VIP-TOKEN: your_api_key_here
```

If the API Key is invalid, expired, or lacks subscription permissions, an error response will be returned.

***

## Request Parameters

### Request Body (JSON)

```json theme={null}
{
  "search_key": "string",
  "status": 1,
  "category": "string",
  "price": "20~100",
  "sales_weekly": "10~100",
  "sales": "100~1000",
  "favorites": "50~500",
  "favorites_weekly": "5~50",
  "reviews": "10~200",
  "reviews_weekly": "1~20",
  "product_type": "digital,physical",
  "is_raving": 0,
  "is_pick": 0,
  "is_bestsell": 0,
  "listed_time": "2024-01-01",
  "country": "US",
  "currency_code": "USD",
  "sort_by": 1,
  "desc": 1,
  "page_num": 1,
  "page_size": 20
}
```

***

### Parameter Description

| Parameter         | Type   | Required | Description                                                                                                                                       |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| search\_key       | string | No       | Search keyword or Etsy product URL                                                                                                                |
| status            | int    | No       | Product status: 1=Active, 0=Inactive                                                                                                              |
| category          | string | No       | Product category                                                                                                                                  |
| price             | string | No       | Price range, e.g. 20\~100                                                                                                                         |
| sales\_weekly     | string | No       | Weekly sales range，1\~100                                                                                                                         |
| sales             | string | No       | Total sales range，1\~100                                                                                                                          |
| favorites         | string | No       | Favorites count range，1\~100                                                                                                                      |
| favorites\_weekly | string | No       | Weekly new favorites range，1\~100                                                                                                                 |
| reviews           | string | No       | Reviews count range，1\~100                                                                                                                        |
| reviews\_weekly   | string | No       | Weekly new reviews range，1\~100                                                                                                                   |
| product\_type     | string | No       | Product type, multiple separated by comma                                                                                                         |
| is\_raving        | int    | No       | Is Raving product: 1=Yes                                                                                                                          |
| is\_pick          | int    | No       | Is Pick product: 1=Yes                                                                                                                            |
| is\_bestsell      | int    | No       | Is bestseller: 1=Yes                                                                                                                              |
| listed\_time      | string | No       | Listing date (YYYY-MM-DD)                                                                                                                         |
| country           | string | No       | Shipping country                                                                                                                                  |
| currency\_code    | string | No       | Currency code, default USD                                                                                                                        |
| sort\_by          | int    | No       | Sort field<br />1 = Weekly sales (default) 2 = Total sales 3 = Reviews 4 = Favorites 11 = Weekly reviews 12 = Weekly favorites 13 = Monthly sales |
| desc              | int    | No       | Sort direction: 1=Descending, 2=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/items \
    -H "Content-Type: application/json" \
    -H "X-VIP-TOKEN: your_api_key_here" \
    -d '{
      "search_key": "wedding ring",
      "page_num": 1,
      "page_size": 20
    }'
  ```

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

  url = "https://api.example.com/api/vi/items"

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

  payload = {
      "search_key": "wedding ring",
      "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/vi/items';

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

  const payload = {
    search_key: 'wedding ring',
    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/vi/items";

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

  $payload = [
      "search_key" => "wedding ring",
      "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/vi/items"
      
      payload := map[string]interface{}{
          "search_key": "wedding ring",
          "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/vi/items")

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

  payload = {
    search_key: 'wedding ring',
    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 ItemsQuery {
      public static void main(String[] args) throws Exception {
          String url = "https://api.example.com/api/vi/items";
          
          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", "wedding ring");
          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": {
    "product_num": 2345,
    "page_size": 20,
    "final_count": 20,
    "list": [
      {
        "title": "Gold Wedding Ring",
        "category": "Jewelry",
        "price": 89.99,
        "status": 1,
        "sales_weekly": 32,
        "sales_total": 1200,
        "reviews": 320,
        "favorites": 540,
        "is_bestsell": 1,
        "is_pick": 0,
        "is_raving": 1,
        "tags": "ring, wedding, gold",
        "ships_from": "US",
        "release_time": "2024-01-01",
        "store_name": "BestJewelryShop",
        "product_url": "https://www.etsy.com/listing/xxx",
        "logo_url": "https://image.xxx/logo.png",
        "reviews_weekly": 5,
        "favorites_weekly": 12
      }
    ]
  },
  "used_today": 120,
  "remaining_today": 880
}
```

***

## Response Fields

| Field            | Type  | Description                                |
| ---------------- | ----- | ------------------------------------------ |
| product\_num     | int   | Total number of products matching criteria |
| page\_size       | int   | Items per page                             |
| final\_count     | int   | Number of items returned in current page   |
| list             | array | Product data list                          |
| used\_today      | int   | Credits used today                         |
| remaining\_today | int   | Remaining credits today                    |

***

## Credit Consumption Rules

* Each returned product consumes 1 credit
* Actual 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 product selection analysis
* High-sales / high-favorite product discovery
* Competitor product monitoring
* Market trend research and data analysis

***

## Query Scenarios

### 1. Query Active Bestselling Products

<CodeGroup>
  ```json Request theme={null}
  {
    "search_key": "",
    "status": 1,
    "sales": "100~",
    "is_bestsell": 1,
    "sort_by": 4,
    "desc": 1,
    "page_size": 20
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.example.com/api/vi/items \
    -H "Content-Type: application/json" \
    -H "X-VIP-TOKEN: your_api_key_here" \
    -d '{
      "search_key": "",
      "status": 1,
      "sales": "100~",
      "is_bestsell": 1,
      "sort_by": 4,
      "desc": 1,
      "page_size": 20
    }'
  ```

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

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

  payload = {
      "search_key": "",
      "status": 1,
      "sales": "100~",
      "is_bestsell": 1,
      "sort_by": 4,
      "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/vi/items',
    {
      search_key: '',
      status: 1,
      sales: '100~',
      is_bestsell: 1,
      sort_by: 4,
      desc: 1,
      page_size: 20
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-VIP-TOKEN': 'your_api_key_here'
      }
    }
  );

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

### 2. Query Inactive High-Sales Products (Competitor Analysis)

<CodeGroup>
  ```json Request theme={null}
  {
    "search_key": "",
    "status": 0,
    "sales": "1000~",
    "sort_by": 4,
    "desc": 1,
    "page_size": 20
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.example.com/api/vi/items \
    -H "Content-Type: application/json" \
    -H "X-VIP-TOKEN: your_api_key_here" \
    -d '{
      "search_key": "",
      "status": 0,
      "sales": "1000~",
      "sort_by": 4,
      "desc": 1,
      "page_size": 20
    }'
  ```

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

  payload = {
      "search_key": "",
      "status": 0,
      "sales": "1000~",
      "sort_by": 4,
      "desc": 1,
      "page_size": 20
  }

  response = requests.post(
      "https://api.example.com/api/vi/items",
      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/vi/items',
    {
      search_key: '',
      status: 0,
      sales: '1000~',
      sort_by: 4,
      desc: 1,
      page_size: 20
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-VIP-TOKEN': 'your_api_key_here'
      }
    }
  );
  ```
</CodeGroup>

### 3. Query Products Listed in Specific Time Period

<CodeGroup>
  ```json Request theme={null}
  {
    "search_key": "handmade",
    "status": 1,
    "listed_time": "2024-03-01",
    "sort_by": 2,
    "desc": 1,
    "page_size": 20
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.example.com/api/vi/items \
    -H "Content-Type: application/json" \
    -H "X-VIP-TOKEN: your_api_key_here" \
    -d '{
      "search_key": "handmade",
      "status": 1,
      "listed_time": "2024-03-01",
      "sort_by": 2,
      "desc": 1,
      "page_size": 20
    }'
  ```

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

  payload = {
      "search_key": "handmade",
      "status": 1,
      "listed_time": "2024-03-01",
      "sort_by": 2,
      "desc": 1,
      "page_size": 20
  }

  response = requests.post(
      "https://api.example.com/api/vi/items",
      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/vi/items',
    {
      search_key: 'handmade',
      status: 1,
      listed_time: '2024-03-01',
      sort_by: 2,
      desc: 1,
      page_size: 20
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-VIP-TOKEN': 'your_api_key_here'
      }
    }
  );
  ```
</CodeGroup>

***

## Important Notes

* Recommended page\_size should not exceed 50 to avoid unnecessary credit consumption
* Complex filtering conditions may affect API response time
* API response data is for analysis reference only and does not constitute business guarantee

***

**Last Updated**: 2026-01-14\
**Maintained By**: EHunt API Team