Skip to main content

​
VIP Items Query 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

POST /api/v1/items

​
Authentication

Include your API Key in the request header: 
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)

{
  "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

ParameterTypeRequiredDescription
search_keystringNoSearch keyword or Etsy product URL
statusintNoProduct status: 1=Active, 0=Inactive
categorystringNoProduct category
pricestringNoPrice range, e.g. 20~100
sales_weeklystringNoWeekly sales range
salesstringNoTotal sales range
favoritesstringNoFavorites count range
favorites_weeklystringNoWeekly new favorites range
reviewsstringNoReviews count range
reviews_weeklystringNoWeekly new reviews range
product_typestringNoProduct type, multiple separated by comma
is_ravingintNoIs Raving product: 1=Yes
is_pickintNoIs Pick product: 1=Yes
is_bestsellintNoIs bestseller: 1=Yes
listed_timestringNoListing date (YYYY-MM-DD)
countrystringNoShipping country
currency_codestringNoCurrency code, default USD
sort_byintNoSort field (1~6)
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/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
  }'

​
Response

​
Response Example

Response
{
  "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

FieldTypeDescription
product_numintTotal number of products matching criteria
page_sizeintItems per page
final_countintNumber of items returned in current page
listarrayProduct data list
used_todayintCredits used today
remaining_todayintRemaining 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

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

{
  "search_key": "",
  "status": 1,
  "sales": "100~",
  "is_bestsell": 1,
  "sort_by": 4,
  "desc": 1,
  "page_size": 20
}

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

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

​
3. Query Products Listed in Specific Time Period

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

​
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