AliExpress API & Scraper
The AliExpress API returns product search, full detail and store data as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary search endpoint returns products with id, title, URL, images, price, original price, discount, units sold and rating, and you can pull a product_detail with SKUs, reviews, similar products, description, shipping options, a store's info, items and categories, and current deals. It is built for price research, dropshipping and catalog tools that need AliExpress data without scraping a heavily-defended marketplace. One ReefAPI key, one shared credit pool, the standard envelope.
AliExpress ids, SKU variants and what country plus currency change
The same AliExpress product is reachable under two different numeric ids, and the per-SKU block is where the prices and images that actually differ per variant live. Everything below was measured on 2026-08-27 with product_detail, search, reviews and shipping. Values shown as null were null in the response, not left blank in this table.
| Field | Measured example | What it means |
|---|---|---|
| product_id (long form) | 3256806194871771 | The number in /item/<id>.html. 16 digits, begins 3256. |
| product_id (short form) | 1005006381186523 | The same product, exactly 2,251,799,813,685,248 (2^51) lower. Accepted as input and echoed back unchanged. Confirmed on four products. |
| sku_id | 12000036967401257 | One buyable variant, color plus size. 17 digits. A shoe listing returned 50 of them. |
| store_id / seller_id | 1102530031 / 2671009820 | Two different numbers on the same store block. store_items and store_info take store_id. |
| review_id | 60095699688325802 | From the reviews action, unrelated to product_id. |
| price_min / price_max | 14.99 / 18.79 EUR | Cheapest and dearest SKU. price_current is the pre-selected SKU, not always the minimum. |
| sold_count | null | Always null on product_detail. The number lives in sold_text as free text ("5.000+ verkauft"). |
| weight | null | meta.weight_found came back false on every product tried. |
| country / currency | US, then DE | Changed the price (2.64 USD to 14.99 EUR), the delivery window (8-14 days to 5-11 days) and the store_url host (aliexpress.com to de.aliexpress.com). |
sku_variants[].props uses localized keys. With language=en the keys were "Color" and "Shoe Size"; with language=de the exact same product returned "Farbe" and "Schuhgroesse". Key your variant matching on sku_id, never on the property name.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/aliexpress/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "wireless earbuds",
"country": "US",
"currency": "USD"
}
}{
"ok": true,
"meta": {
"api": "aliexpress",
"endpoint": "search",
"mode": "live",
"latency_ms": 1561.2,
"record_count": 60,
"bytes": 736717,
"cache_hit": false,
"version": "0.1",
"page": 1,
"pagination": {
"page": 1,
"has_more": true
}
},
"data": {
"query": "wireless earbuds",
"country": "US",
"currency": "USD",
"results": [
{
"product_id": "[redacted-phone]",
"title": "Baseus Bass EP10 NC -43dB Noise Cancelling ANC True Wireless Earbuds Bluetooth 6.0 In-Ear Wireless Earphones 4-Mics ENC Ear buds",
"url": "https://www.aliexpress.com/item/[redacted-phone].html",
"image": "https://ae-pic-a1.aliexpress-media.com/kf/Sa802af2e290b4ffdb151cacc25733ef8x.jpg",
"images": [
"https://ae-pic-a1.aliexpress-media.com/kf/Sa802af2e290b4ffdb151cacc25733ef8x.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/Sa71cf8de22bb44808f92748d95d1413dt.png",
"https://ae-pic-a1.aliexpress-media.com/kf/Sa73b727b92734a5bb1ac082531d50829Z.png"
],
"price": 13.75,
"original_price": 44.43,
"currency": "USD",
"discount_pct": 69,
"price_formatted": "US $13.75",
"sold_count": 10000,
"sold_text": "10,000+ sold",
"rating": 4.9,
"store_name": null,
"store_url": null,
"product_type": "natural",
"promo_tags": [
"New shoppers save $30.68",
"Lowest price in 90 days"
],
"sku_id": "[redacted-phone]"
},
{
"product_id": "[redacted-phone]",
"title": "QCY T13 ANC Active Noise Cancelling Wireless Earbuds Bluetooth 5.3 Headphones 4 Mics ENC Clear Calls Earphones 30H Playtime IPX5",
"url": "https://www.aliexpress.com/item/[redacted-phone].html",
"image": "https://ae-pic-a1.aliexpress-media.com/kf/S5fdfcad8a1a24f919f7734a805f46c84l.jpg",
"images": [
"https://ae-pic-a1.aliexpress-media.com/kf/S5fdfcad8a1a24f919f7734a805f46c84l.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/S46d0988a85bc42a38eb4155c50f516c26.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/S66d59a917dd943caa4d014993d4215c6O.jpg"
],
"price": 26.39,
"original_price": 55.34,
"currency": "USD",
"discount_pct": 52,
"price_formatted": "US $26.39",
"sold_count": 5000,
"sold_text": "5,000+ sold",
"rating": 4.9,
"store_name": null,
"store_url": null,
"product_type": "natural",
"promo_tags": [
"Save $28.95",
"Delivery: Jul 24 - 29"
],
"sku_id": "[redacted-phone]"
},
{
"product_id": "[redacted-phone]",
"title": "Bluetooth headset TWS hands-free LED Dispay headset Bluetooth HiFi stereo music wireless earplug game headset",
"url": "https://www.aliexpress.com/item/[redacted-phone].html",
"image": "https://ae-pic-a1.aliexpress-media.com/kf/S2b686cc68e564b6e83fb2a593aaa0f4fT.jpg",
"images": [
"https://ae-pic-a1.aliexpress-media.com/kf/S2b686cc68e564b6e83fb2a593aaa0f4fT.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/Sa90e58eeca6c415885f6fab146615b63y.jpg",
"https://ae-pic-a1.aliexpress-media.com/kf/Sbc5bb29cba2c4a81b05a7a8bf5b8c993c.jpg"
],
"price": 0.33,
"original_price": 7.95,
"currency": "USD",
"discount_pct": 95,
"price_formatted": "US $0.33",
"sold_count": 5000,
"sold_text": "5,000+ sold",
"rating": 4.9,
"store_name": null,
"store_url": null,
"product_type": "natural",
"promo_tags": [
"Save $7.62",
"Delivery: Jul 24 - 29"
],
"sku_id": "[redacted-phone]"
}
],
"related_searches": [
"wireless earrings earbuds",
"aptx wireless earbuds",
"wireless earbuds ear hook"
],
"ranking_searches": [
"wireless headphones",
"white earbuds",
"ear buds"
]
}
}What the AliExpress API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Product search cards (price, sold_count, rating, store); filters sort/min_price/max_price/ship_from/free_shipping, paginated | Pricing teams call search to get product search cards (price, sold_count, rating, store); filters sort/min_price/max_price/shi…. | query, country, currency, page, max_pages, ... |
| product_detail | Full product + SKU-variant price/stock matrix + specs + images + video + store + shipping + rating + coupons + sale countdown + wishlist counts + item weight where the seller published one (empty when they did not — never guessed) | Marketplace operators call product_detail to get full product + SKU-variant price/stock matrix + specs + images + video + store + shipping + r…. | product_id, url, country, currency, language, ... |
| reviews | Buyer reviews (paginated — fetch many pages in one call) + rating distribution | Catalog enrichment teams call reviews to get buyer reviews (paginated. | product_id, url, page, max_pages, max_results, ... |
| similar | Products similar to a given item (search-backed 'more like this', seed product excluded), paginated | Retail analysts call similar to get products similar to a given item (search-backed 'more like this', seed product excluded), pag…. | product_id, url, query, page, max_pages, ... |
| description | Full product description text + images | Pricing teams call description to get full product description text + images. | product_id, url, description_url, country, currency |
| shipping | Shipping options per destination country | Marketplace operators call shipping to get shipping options per destination country. | product_id, url, country, currency, language, ... |
| store_info | Store profile (+ live seller metrics when a query is supplied) | Catalog enrichment teams call store_info to get store profile (+ live seller metrics when a query is supplied). | store_id, store_url, query, country, currency |
| deals | SuperDeals / discounted cards (search-derived, sorted by discount) | Retail analysts call deals to get superDeals / discounted cards (search-derived, sorted by discount). | query, min_discount, sort, page, max_pages, ... |
Call search from your stack
curl -X POST https://api.reefapi.com/aliexpress/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"wireless earbuds","country":"US","currency":"USD"}'import requests
r = requests.post(
"https://api.reefapi.com/aliexpress/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "wireless earbuds",
"country": "US",
"currency": "USD"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/aliexpress/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "wireless earbuds",
"country": "US",
"currency": "USD"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.aliexpress.search with {"query":"wireless earbuds","country":"US","currency":"USD"}.Who uses this API and why
- Dropshipping tools call search and product_detail to source products with prices, SKUs and shipping.
- Price-research products use deals and reviews to find trending, well-rated items.
- Catalog tools use store_items to mirror a supplier's full AliExpress inventory.
Questions developers ask before integrating
Why does the same AliExpress product have two different ids, 3256... and 1005...?
They are the same item written two ways, and the gap between them is a constant: 2,251,799,813,685,248, which is 2^51. Measured on four products on 2026-08-27, for example 3256806194871771 minus 2^51 gives 1005006381186523. Both forms are accepted as product_id and the API echoes back whichever form you sent, so pick one and stay consistent if you are joining against your own table.
Do SKU-level images come through, and why did 50 variants share only 5 images?
Every variant carries image and thumbnail, and on a 50-variant running shoe all 50 were populated. Only 5 were distinct because AliExpress attaches the photo to the color, not to the color and size pair, so all ten sizes of the blue shoe point at the same blue photo. If you want the color swatch set on its own, sku_properties[].value_details[] carries one image, thumbnail and color_hex per color value.
Does every size of an AliExpress listing cost the same?
No, and that is the usual reason a scraped price looks wrong. On one measured listing price_min was 14.99 EUR and price_max 18.79 EUR, with EU 43 at 16.19 and EU 44 at 16.69. price_current (14.99) is the pre-selected SKU, not an average and not the minimum in every case. Read sku_variants[].price.sale if you need the price for a specific size.
Why is sold_count null when the listing clearly shows thousands sold?
AliExpress publishes the figure as a rounded label rather than an exact number, so product_detail returns sold_count null and puts the label in sold_text, for example "50,000+ sold". The search action does parse that label into sold_count, where "1,000+ sold" became 1000 and "24 sold" became 24. Treat search's sold_count as a floor, not an exact count.
What actually changes when I set country and currency?
Quite a lot. The same product returned 2.64 USD shipping to the US with an 8 to 14 day estimate, and 14.99 EUR to Germany with 5 to 11 days. The store_url host switched from aliexpress.com to de.aliexpress.com, and sold_text came back in German. meta also reports province_sent, which is defaulted from the country (US gave California, DE gave Berlin), so set province yourself if you need a state-accurate delivery estimate.
Why do the sku_variants property names change between calls?
Because the language parameter localizes them. The same shoe returned props keyed "Color" and "Shoe Size" under language=en and "Farbe" and "Schuhgroesse" under language=de. sku_id is stable across languages, so match on sku_id and use props only for display.
Why does review_count in product_detail differ from total_reviews in reviews?
They are two different counters read at two different moments. On 2026-08-27 the same product returned review_count 1354 from product_detail and total_reviews 1352 from reviews. The reviews action also gives you summary.distribution with a count per star (5: 1103, 4: 132, 3: 55, 2: 15, 1: 49) plus positive_num, neutral_num and negative_num, which is the block to use when the numbers have to add up.
What does product_type "ad" mean in search results?
It marks a sponsored placement. Search rows come back with product_type either "natural" or "ad", and the ad rows are interleaved with organic ones in the same results array. If you are measuring rank or building a price index, filter on product_type equal to "natural" first, otherwise paid placements will move your numbers around.
What is the AliExpress API?
AliExpress API is a ReefAPI endpoint group for product search, prices, variants, reviews and shipping. It returns live JSON through POST requests under /aliexpress/v1.
Is the AliExpress API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. AliExpress calls use the same shared credit balance as every other ReefAPI engine.
Do I need an AliExpress login or account?
No login to AliExpress is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the AliExpress data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the AliExpress API use?
AliExpress actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call AliExpress from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call aliexpress actions with the same key, credit pool and JSON envelope used by normal REST requests.