EtshopAPI Platform
EN / 中文
API REFERENCE

Product List API

GET/v1/product
1 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-api
Credits 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

AUTHORIZATIONAuthorization: {API Key}
CONTENT-TYPEapplication/json
ACCEPTapplication/json

Request example

cURL
curl --location --request GET 'https://api.etshop.ai/open-api/v1/product?times=2&name=linen%20duvet&order_by=sale_growth&direction=desc&current_page=1&page_size=2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {API Key}'

Request parameters 28 fields

Pass each parameter in its specified location.

Parameter Type Description
times
query · required
integer Statistics period for the *_growth fields and growth-based sorting: 5 last 3 days, 2 last 7 days, 3 last 30 days, 4 last 90 days.
categories
query · optional
integer Category ID from Category List. Any level is accepted; all subcategories are included.
name
query · optional
string Product keywords, matched against listing tags or title. Multiple values should be comma-separated; all must match.
exclude_name
query · optional
string Exclude products whose title contains any of these keywords. Multiple values should be comma-separated.
shop_id
query · optional
integer Shop ID. Only products from this shop are returned (closed shops included).
price_start
query · optional
number Minimum price (USD).
price_end
query · optional
number Maximum price (USD).
created_time_start
query · optional
string Listing date (from). Format: Y-m-d, e.g. 2026-01-01.
created_time_end
query · optional
string Listing date (to). Format: Y-m-d, e.g. 2026-10-31.
bestseller
query · optional
integer Pass 1 to return Bestseller products only.
etsy_pick
query · optional
integer Pass 1 to return Etsy's Pick products only.
with_video
query · optional
integer Pass 1 to return products with a video only.
sale_start
query · optional
integer Minimum total sales.
sale_end
query · optional
integer Maximum total sales.
review_start
query · optional
integer Minimum total reviews.
review_end
query · optional
integer Maximum total reviews.
collection_start
query · optional
integer Minimum total favorites.
collection_end
query · optional
integer Maximum total favorites.
view_start
query · optional
integer Minimum total views.
view_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 Pass 1 to return products with real sales only.
real_sale_start
query · optional
integer Minimum real sales.
real_sale_end
query · optional
integer Maximum real sales.
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), real_sale_growth (real sales growth in the period), total_sale (total sales), total_view (total views), total_collection (total favorites), total_review (total reviews), real_sale (real sales), create_date (listing date). Defaults to review_growth.
direction
query · optional
string Sort direction. Valid options: desc (descending, default), asc (ascending).

Response example

Response · JSON
{
    "code": 200,
    "message": "success",
    "data": {
        "data": [
            {
                "id": 1284567890,
                "image": "https://i.etsystatic.com/21475836/r/il/8c1d2e/5123456789/il_fullxfull.5123456789_ab12.jpg",
                "name": "Linen Duvet Cover in Natural Flax, Stonewashed Linen Bedding, Queen King Size",
                "create_date": 1663200000,
                "currency_code": "EUR",
                "country_code": "LT",
                "sale": 9842,
                "sale_growth": 214,
                "review": 2137,
                "review_growth": 31,
                "collect": 18450,
                "collect_growth": 402,
                "view": 389214,
                "view_growth": 6120,
                "bestseller": 1,
                "etsy_pick": 0,
                "product_type": ["Handmade", "Customizable"],
                "is_video": 1,
                "price": 129,
                "url": "https://www.etsy.com/listing/1284567890/linen-duvet-cover-in-natural-flax",
                "store_name": "LunaLinenStudio",
                "shop_id": 21475836,
                "real_sale": 6215,
                "real_sale_growth": 158
            },
            {
                "id": 1532907846,
                "image": "https://i.etsystatic.com/38201745/r/il/a17c4d/6012345678/il_fullxfull.6012345678_xy90.jpg",
                "name": "Washed Linen Duvet Cover Set, Sage Green Bedding with Pillowcases",
                "create_date": 1694563200,
                "currency_code": "USD",
                "country_code": "US",
                "sale": 3120,
                "sale_growth": 167,
                "review": 604,
                "review_growth": 22,
                "collect": 7731,
                "collect_growth": 288,
                "view": 145032,
                "view_growth": 4870,
                "bestseller": 0,
                "etsy_pick": 1,
                "product_type": ["Handmade"],
                "is_video": 0,
                "price": 98.5,
                "url": "https://www.etsy.com/listing/1532907846/washed-linen-duvet-cover-set-sage-green",
                "store_name": "HearthAndLoomHome",
                "shop_id": 38201745,
                "real_sale": 0,
                "real_sale_growth": 0
            }
        ],
        "page": {
            "page_count": 1846,
            "current_page": 1,
            "total_count": 3692,
            "page_size": 2
        }
    },
    "credits": {
        "type": "default",
        "remaining_credits": 196531,
        "consumed_credits": 2,
        "total_credits": 196533
    }
}
Example data from the existing documentation

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 Product list
»»» id integer true none Product ID
»»» image string true none Main product image
»»» name string true none Product title
»»» create_date integer true none Listing time (Unix timestamp, seconds)
»»» currency_code string true none Price currency
»»» country_code string true none Shop country/region code
»»» sale integer true none Total sales
»»» sale_growth integer true none Sales growth in the period set by times
»»» review integer true none Total reviews
»»» review_growth integer true none Review growth in the period
»»» collect integer true none Total favorites
»»» collect_growth integer true none Favorite growth in the period
»»» view integer true none Total views
»»» view_growth integer true none View growth in the period
»»» bestseller integer true none Bestseller: 1 yes, 0 no
»»» etsy_pick integer true none Etsy's Pick: 1 yes, 0 no
»»» product_type [string] true none Product types: Handmade, Digital, Vintage, Customizable, Others
»»» is_video integer true none Has a video: 1 yes, 0 no
»»» price number true none Price (in currency_code)
»»» url string true none Product URL
»»» store_name string true none Shop name
»»» shop_id integer true none Shop ID
»»» real_sale integer true none Real sales
»»» real_sale_growth integer true none Real sales growth in the period
»» 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)
Search the existing endpoint names and paths