List the products in a category
One AliExpress category, with the same product fields, filters and sort orders as a keyword search. Pass a category id — every product carries its categoryId — or a category page URL. Sorting by orders is the quickest read of what sells in a category right now. Results are read in the market you pass and echoed as market. An unknown category is a 404.
/category-products Products https://api.fetchlayer.dev/aliexpress/category-products Headers
Authorization string required Bearer token — your FetchLayer API key.
Parameters
category string required Category id (for example 70802) or category page URL.
sort string optional best_match, orders (most sold first), price_asc or price_desc. (default: best_match)
minPrice number optional Lowest price, in the requested currency.
maxPrice number optional Highest price, in the requested currency.
freeShipping boolean optional Only listings with free shipping. (default: false)
fourStarsAndUp boolean optional Only listings rated four stars and up. (default: false)
choiceOnly boolean optional Only AliExpress Choice listings. (default: false)
shipFrom string optional Two-letter country code the item ships from, for example CN, US or ES.
limit number optional Maximum products returned (max 1200), or -1 for the maximum allowed. (default: 60)
pages number optional Pages of 60 to collect in one request (max 20), or -1 for the maximum allowed. Each page counts as one request. (default: 1)
cursor string optional Resume from a previous response's nextCursor.
delayMs number optional Milliseconds to wait between pages (max 30000).
shipTo string optional Two-letter country code the shopper ships to, for example US or DE. Changes prices, shipping and availability. (default: US)
currency string optional Currency prices are returned in: USD, EUR, GBP, CAD, AUD, NZD, BRL, MXN, CLP, COP, PEN, ARS, JPY or KRW. Any other value is a 400. (default: USD)
language string optional Language for titles and labels: en_US, de_DE or pt_BR. Any other value is a 400. (default: en_US)
format string optional json, or markdown to get the result rendered as text. (default: json)
timeoutMs number optional Per-request time limit in milliseconds (max 600000).
Response Fields
category-products
List the products in a category
products object[] The matching products, de-duplicated within this response.
products[].productId string Global product id — the handle /product-details, /product-prices and /product-reviews take. US storefront ids are folded into it.
products[].title string Listing title, in the requested language.
products[].url string Public product page URL.
products[].imageUrl string | null Main image. Pass it to /media to download it.
products[].imageUrls string[] Every image shown on the card.
products[].price object | null Current price after the listing discount, the lowest across variants: amount, currency and the price as displayed. Null on new-shopper gift cards, which AliExpress lists without a price.
products[].originalPrice object | null Price before the discount, when one is shown.
products[].discountPercent number | null Discount shown on the card.
products[].rating number | null Average rating out of 5.
products[].soldText string | null Sales label as displayed, for example "10,000+ sold".
products[].soldCount number | null Exact sales where published, otherwise the lower bound of the label.
products[].shipFrom string | null Two-letter country the item ships from.
products[].categoryId string | null Category id — pass it to /category-products or as categoryId on a search.
products[].sponsored boolean A paid placement rather than an organic result.
products[].choice boolean Part of the AliExpress Choice programme.
products[].badges string[] Labels on the card: "Top selling", "Lowest price in 90 days", a delivery window, or the text shown in place of a price on a gift card.
filters object The filters and sort this listing ran with, after defaults were applied.
productCount number Products in this response.
totalResults number | null Matches AliExpress reports for the whole query, before paging.
pagesScraped number Pages actually collected. Each page counts as one request against your plan.
pagesRequested number Pages the request asked for.
nextCursor string | null Pass back as cursor to continue, or null when there is no next page.
hasNextPage boolean Whether more results are available beyond this response.
market object The market this result was read in — shipTo, currency and language — after defaults were applied. Compare prices only between results with the same market.
notes string[] Caveats about this specific result — a walk refused part-way, a padded search, a page repeated by the cursor. Read it before treating a result as complete.
requestedUrl string The AliExpress page this result corresponds to.
scrapedAt string ISO 8601 timestamp of when the data was collected.
resultType string Which shape this response is, e.g. product-search or product-reviews.
transport string The upstream source the data came from: aliexpress.
blocked boolean Always false on a successful response.
Request
curl -X POST "https://api.fetchlayer.dev/aliexpress/category-products" \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{"category":"70802","sort":"orders","shipTo":"US","currency":"USD","language":"en_US"}'Response
{
"resultType": "category-products",
"market": {
"shipTo": "US",
"currency": "USD",
"language": "en_US"
},
"notes": [],
"filters": {
"sort": "orders",
"categoryId": "70802",
"freeShipping": false,
"fourStarsAndUp": false,
"choiceOnly": false
},
"productCount": 60,
"totalResults": 8814,
"pagesScraped": 1,
"nextCursor": "eyJwIjoyfQ",
"hasNextPage": true,
"products": [
{
"productId": "1005007168889184",
"title": "AK820 Red-Switch Mechanical Gaming Keyboard, 75% Layout, Hot-Swappable Switches, Featuring a USB-C Port, White Backlighting",
"url": "https://www.aliexpress.com/item/1005007168889184.html",
"price": {
"amount": 33.24,
"currency": "USD",
"formatted": "US $33.24"
},
"categoryId": "70802",
"choice": true
}
]
}