{ "openapi": "3.1.0", "info": { "title": "AliExpress API", "version": "1.0.0", "description": "AliExpress read as structured JSON: keyword search and category listings, full product details with every variant, a batch price check built for monitoring, buyer reviews with the star distribution, and product media — in a market you pin, through FetchLayer." }, "servers": [ { "url": "https://api.fetchlayer.dev/aliexpress" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search-products": { "post": { "operationId": "search-products", "tags": [ "Products" ], "summary": "Search products by keyword", "description": "Products matching a keyword, 60 per page, with AliExpress’s own filters: price range, free shipping, four stars and up, Choice only, ship-from country and category. Sort by best match, orders or price. Results are read in the market you pass and echoed as market — the same keyword ranks different products first for a US and a German shopper. AliExpress lists at most 60 pages for one query, so narrow with filters to reach further. Consecutive pages can repeat a product (11 of 60 on one keyword’s second page), so de-duplicate by productId across responses. A search with few matches is padded by AliExpress with loosely related products, and notes says so.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Keywords to search for (max 200 characters)." }, "categoryId": { "type": "string", "description": "Restrict the search to one category id, as returned on a product." }, "sort": { "type": "string", "description": "best_match, orders (most sold first), price_asc or price_desc.", "example": "best_match" }, "minPrice": { "type": "number", "description": "Lowest price, in the requested currency." }, "maxPrice": { "type": "number", "description": "Highest price, in the requested currency." }, "freeShipping": { "type": "boolean", "description": "Only listings with free shipping.", "example": "false" }, "fourStarsAndUp": { "type": "boolean", "description": "Only listings rated four stars and up.", "example": "false" }, "choiceOnly": { "type": "boolean", "description": "Only AliExpress Choice listings.", "example": "false" }, "shipFrom": { "type": "string", "description": "Two-letter country code the item ships from, for example CN, US or ES." }, "limit": { "type": "number", "description": "Maximum products returned (max 1200), or -1 for the maximum allowed.", "example": "60" }, "pages": { "type": "number", "description": "Pages of 60 to collect in one request (max 20), or -1 for the maximum allowed. Each page counts as one request.", "example": "1" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "shipTo": { "type": "string", "description": "Two-letter country code the shopper ships to, for example US or DE. Changes prices, shipping and availability.", "example": "US" }, "currency": { "type": "string", "description": "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.", "example": "USD" }, "language": { "type": "string", "description": "Language for titles and labels: en_US, de_DE or pt_BR. Any other value is a 400.", "example": "en_US" }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "mechanical keyboard", "shipTo": "US", "currency": "USD", "language": "en_US" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The keyword searched." }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "productId": { "type": "string", "description": "Global product id — the handle /product-details, /product-prices and /product-reviews take. US storefront ids are folded into it." }, "title": { "type": "string", "description": "Listing title, in the requested language." }, "url": { "type": "string", "description": "Public product page URL." }, "imageUrl": { "type": [ "string", "null" ], "description": "Main image. Pass it to /media to download it." }, "imageUrls": { "type": "array", "items": { "type": "string" }, "description": "Every image shown on the card." }, "price": { "type": [ "object", "null" ], "additionalProperties": true, "description": "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." }, "originalPrice": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Price before the discount, when one is shown." }, "discountPercent": { "type": [ "number", "null" ], "description": "Discount shown on the card." }, "rating": { "type": [ "number", "null" ], "description": "Average rating out of 5." }, "soldText": { "type": [ "string", "null" ], "description": "Sales label as displayed, for example \"10,000+ sold\"." }, "soldCount": { "type": [ "number", "null" ], "description": "Exact sales where published, otherwise the lower bound of the label." }, "shipFrom": { "type": [ "string", "null" ], "description": "Two-letter country the item ships from." }, "categoryId": { "type": [ "string", "null" ], "description": "Category id — pass it to /category-products or as categoryId on a search." }, "sponsored": { "type": "boolean", "description": "A paid placement rather than an organic result." }, "choice": { "type": "boolean", "description": "Part of the AliExpress Choice programme." }, "badges": { "type": "array", "items": { "type": "string" }, "description": "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." } } }, "description": "The matching products, de-duplicated within this response." }, "filters": { "type": "object", "additionalProperties": true, "description": "The filters and sort this listing ran with, after defaults were applied." }, "productCount": { "type": "number", "description": "Products in this response." }, "totalResults": { "type": [ "number", "null" ], "description": "Matches AliExpress reports for the whole query, before paging." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages the request asked for." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor to continue, or null when there is no next page." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "market": { "type": "object", "additionalProperties": true, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "string", "description": "The AliExpress page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. product-search or product-reviews." }, "transport": { "type": "string", "description": "The upstream source the data came from: aliexpress." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "product-search", "market": { "shipTo": "US", "currency": "USD", "language": "en_US" }, "notes": [], "query": "mechanical keyboard", "productCount": 58, "totalResults": 16791, "pagesScraped": 1, "nextCursor": "eyJwIjoyfQ", "hasNextPage": true, "products": [ { "productId": "1005009494458560", "title": "AJAZZ NK61 Wired Gaming Mechanical Keyboard 60% RGB Hot-Swappable 61 Keys Red Switch Mini Keyboard for Gamer PC", "url": "https://www.aliexpress.com/item/1005009494458560.html", "imageUrl": "https://ae-pic-a1.aliexpress-media.com/kf/S21fa9e98da3547c5a2e840c1917ce9cdI.png", "price": { "amount": 16.33, "currency": "USD", "formatted": "US $16.33" }, "originalPrice": { "amount": 41.14, "currency": "USD", "formatted": "US $41.14" }, "discountPercent": 60, "rating": 4.7, "soldText": "10,000+ sold", "soldCount": 15106, "shipFrom": "CN", "categoryId": "70802", "sponsored": false, "choice": true, "badges": [ "Top selling on AliExpress", "Delivery: Sep 18 - 24" ] } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/category-products": { "post": { "operationId": "category-products", "tags": [ "Products" ], "summary": "List the products in a category", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "description": "Category id (for example 70802) or category page URL." }, "sort": { "type": "string", "description": "best_match, orders (most sold first), price_asc or price_desc.", "example": "best_match" }, "minPrice": { "type": "number", "description": "Lowest price, in the requested currency." }, "maxPrice": { "type": "number", "description": "Highest price, in the requested currency." }, "freeShipping": { "type": "boolean", "description": "Only listings with free shipping.", "example": "false" }, "fourStarsAndUp": { "type": "boolean", "description": "Only listings rated four stars and up.", "example": "false" }, "choiceOnly": { "type": "boolean", "description": "Only AliExpress Choice listings.", "example": "false" }, "shipFrom": { "type": "string", "description": "Two-letter country code the item ships from, for example CN, US or ES." }, "limit": { "type": "number", "description": "Maximum products returned (max 1200), or -1 for the maximum allowed.", "example": "60" }, "pages": { "type": "number", "description": "Pages of 60 to collect in one request (max 20), or -1 for the maximum allowed. Each page counts as one request.", "example": "1" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "shipTo": { "type": "string", "description": "Two-letter country code the shopper ships to, for example US or DE. Changes prices, shipping and availability.", "example": "US" }, "currency": { "type": "string", "description": "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.", "example": "USD" }, "language": { "type": "string", "description": "Language for titles and labels: en_US, de_DE or pt_BR. Any other value is a 400.", "example": "en_US" }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "category" ] }, "examples": { "default": { "value": { "category": "70802", "sort": "orders", "shipTo": "US", "currency": "USD", "language": "en_US" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "productId": { "type": "string", "description": "Global product id — the handle /product-details, /product-prices and /product-reviews take. US storefront ids are folded into it." }, "title": { "type": "string", "description": "Listing title, in the requested language." }, "url": { "type": "string", "description": "Public product page URL." }, "imageUrl": { "type": [ "string", "null" ], "description": "Main image. Pass it to /media to download it." }, "imageUrls": { "type": "array", "items": { "type": "string" }, "description": "Every image shown on the card." }, "price": { "type": [ "object", "null" ], "additionalProperties": true, "description": "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." }, "originalPrice": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Price before the discount, when one is shown." }, "discountPercent": { "type": [ "number", "null" ], "description": "Discount shown on the card." }, "rating": { "type": [ "number", "null" ], "description": "Average rating out of 5." }, "soldText": { "type": [ "string", "null" ], "description": "Sales label as displayed, for example \"10,000+ sold\"." }, "soldCount": { "type": [ "number", "null" ], "description": "Exact sales where published, otherwise the lower bound of the label." }, "shipFrom": { "type": [ "string", "null" ], "description": "Two-letter country the item ships from." }, "categoryId": { "type": [ "string", "null" ], "description": "Category id — pass it to /category-products or as categoryId on a search." }, "sponsored": { "type": "boolean", "description": "A paid placement rather than an organic result." }, "choice": { "type": "boolean", "description": "Part of the AliExpress Choice programme." }, "badges": { "type": "array", "items": { "type": "string" }, "description": "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." } } }, "description": "The matching products, de-duplicated within this response." }, "filters": { "type": "object", "additionalProperties": true, "description": "The filters and sort this listing ran with, after defaults were applied." }, "productCount": { "type": "number", "description": "Products in this response." }, "totalResults": { "type": [ "number", "null" ], "description": "Matches AliExpress reports for the whole query, before paging." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages the request asked for." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor to continue, or null when there is no next page." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "market": { "type": "object", "additionalProperties": true, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "string", "description": "The AliExpress page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. product-search or product-reviews." }, "transport": { "type": "string", "description": "The upstream source the data came from: aliexpress." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "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 } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/product-details": { "post": { "operationId": "product-details", "tags": [ "Products" ], "summary": "Get one product in full", "description": "Everything AliExpress publishes for one product: title and category path, the lowest and highest current price across variants, the original price, discount and 30-day lowest price, every variant (SKU) with its options, price, availability and stock, total stock and purchase limit, the store with its country, opening date, positive-feedback share and top-rated status, rating, review count, sold and wishlist counts, specifications, images and video, and the shipping option AliExpress selects by default for the market — carrier, fee, ship-from country and delivery dates. Accepts a product id or any product page URL, including US storefront ids; the id returned is always the global one. AliExpress refuses product lookups in bursts, and this route depends on them: an occasional 503 is temporary, so wait a little and retry. Search, category listings and reviews are served another way and are not affected. A 404 means the product does not exist or is not public and is not worth retrying.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "description": "AliExpress product id or any product page URL." }, "shipTo": { "type": "string", "description": "Two-letter country code the shopper ships to, for example US or DE. Changes prices, shipping and availability.", "example": "US" }, "currency": { "type": "string", "description": "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.", "example": "USD" }, "language": { "type": "string", "description": "Language for titles and labels: en_US, de_DE or pt_BR. Any other value is a 400.", "example": "en_US" }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "product" ] }, "examples": { "default": { "value": { "product": "1005009494458560", "shipTo": "US", "currency": "USD", "language": "en_US" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "productId": { "type": "string", "description": "Global product id." }, "title": { "type": "string", "description": "Title, in the requested language." }, "url": { "type": "string", "description": "Public product page URL." }, "available": { "type": "boolean", "description": "Whether it can be bought in this market." }, "categoryId": { "type": [ "string", "null" ], "description": "Leaf category id." }, "categoryPath": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Category breadcrumb, top level first." }, "price": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Lowest current price across variants: amount, currency and as displayed." }, "priceMax": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Highest current price across variants." }, "originalPrice": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The default variant's price before its discount." }, "discountPercent": { "type": [ "number", "null" ], "description": "Discount on the default variant." }, "thirtyDayLowestPrice": { "type": [ "string", "null" ], "description": "The 30-day lowest price before the discount, as displayed, where AliExpress shows one." }, "variantProperties": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Option dimensions (Color, Size…) with each option’s name and image." }, "variants": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every SKU: skuId, selected options, price, available and stock. Pass a skuId to /product-prices to track one variant." }, "selectedSkuId": { "type": [ "string", "null" ], "description": "The variant AliExpress selects by default." }, "totalStock": { "type": [ "number", "null" ], "description": "Units in stock across variants." }, "purchaseLimit": { "type": [ "string", "null" ], "description": "Per-order limit, as displayed." }, "store": { "type": "object", "additionalProperties": true, "description": "storeId, sellerId, name, url, country, openedOn, positiveFeedbackPercent (0–100), feedbackCount, topRatedSeller and highlights." }, "rating": { "type": [ "number", "null" ], "description": "Average rating out of 5." }, "reviewCount": { "type": [ "number", "null" ], "description": "Reviews on the product." }, "soldText": { "type": [ "string", "null" ], "description": "Sales label as displayed." }, "soldCount": { "type": [ "number", "null" ], "description": "Sales count." }, "wishlistCount": { "type": [ "number", "null" ], "description": "Shoppers who saved it." }, "specifications": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Specification name/value pairs." }, "imageUrls": { "type": "array", "items": { "type": "string" }, "description": "Gallery images. Pass one to /media to download it." }, "videoUrl": { "type": [ "string", "null" ], "description": "Product video, when there is one." }, "descriptionUrl": { "type": [ "string", "null" ], "description": "URL of the seller’s long description." }, "shipping": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The default shipping option for the market: carrier, fee (null when free), free, shipFrom, deliveryDaysMin/Max, estimatedDeliveryFrom/To (yyyy-mm-dd), trackingAvailable and freeShippingThreshold." } }, "additionalProperties": false }, "market": { "type": "object", "additionalProperties": true, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "string", "description": "The AliExpress page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. product-search or product-reviews." }, "transport": { "type": "string", "description": "The upstream source the data came from: aliexpress." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "product-details", "market": { "shipTo": "US", "currency": "USD", "language": "en_US" }, "notes": [], "product": { "productId": "1005009494458560", "title": "AJAZZ NK61 Wired Gaming Mechanical Keyboard 60% RGB Hot-Swappable 61 Keys Red Switch Mini Keyboard for Gamer PC", "url": "https://www.aliexpress.com/item/1005009494458560.html", "available": true, "categoryId": "70802", "price": { "amount": 16.33, "currency": "USD", "formatted": "US $16.33" }, "originalPrice": { "amount": 41.14, "currency": "USD", "formatted": "US $41.14" }, "discountPercent": 60, "rating": 4.7, "reviewCount": 2708, "soldText": "10,000+ sold", "variantProperties": [], "variants": [], "store": {}, "specifications": [], "shipping": {} } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/product-prices": { "post": { "operationId": "product-prices", "tags": [ "Prices" ], "summary": "Check prices for up to 20 products", "description": "A compact price check built to be polled: up to 20 products in one request, each reported in request order with a status — ok, unavailable (listed but cannot be bought), not_found, or failed (could not be checked this time; check it again later) — plus availability, currency, the lowest and highest variant price, the original price, total stock, and one variant’s price and stock. Name a variant with { product, skuId } to track it; otherwise the default variant is reported, and requestedSkuMissing says when a named one is no longer offered. One product that cannot be checked does not fail the rest, and a batch refused part-way returns what it priced with the rest marked failed. It is much lighter and faster than one /product-details call per product. Pin shipTo and currency and keep them fixed between checks: a price read in a different market is a different price, not a price change. AliExpress refuses product lookups in bursts, and this route depends on them: an occasional 503 is temporary, so wait a little and retry. Search, category listings and reviews are served another way and are not affected. A 404 means the product does not exist or is not public and is not worth retrying. Billing: each product that gets a definitive result — a price, or a status such as out of stock, ended, unavailable or not found — counts as one request, so pricing 20 products bills 20. Products that fail on our side (blocked, timed out, not reached) are not billed, and duplicates count once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Up to 20 products, each a product id or URL, or { product, skuId } to also price one variant." }, "shipTo": { "type": "string", "description": "Two-letter country code the shopper ships to, for example US or DE. Changes prices, shipping and availability.", "example": "US" }, "currency": { "type": "string", "description": "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.", "example": "USD" }, "language": { "type": "string", "description": "Language for titles and labels: en_US, de_DE or pt_BR. Any other value is a 400.", "example": "en_US" }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "products" ] }, "examples": { "default": { "value": { "products": [ "1005009494458560", "1005006994630464" ], "shipTo": "US", "currency": "USD" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pagesScraped": { "type": "number", "description": "Products that received a definitive result. Each counts as one request against your plan; failed products and duplicates do not." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "productId": { "type": "string", "description": "Global product id." }, "status": { "type": "string", "description": "ok, unavailable, not_found, or failed. failed is temporary — check that product again later." }, "available": { "type": [ "boolean", "null" ], "description": "Whether it can be bought." }, "currency": { "type": [ "string", "null" ], "description": "Currency the prices are in." }, "price": { "type": [ "number", "null" ], "description": "Lowest current variant price." }, "priceMax": { "type": [ "number", "null" ], "description": "Highest current variant price." }, "originalPrice": { "type": [ "number", "null" ], "description": "Price before the discount." }, "totalStock": { "type": [ "number", "null" ], "description": "Units in stock across variants." }, "variant": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The requested or default variant: skuId, price, available, stock, and requestedSkuMissing when a requested variant was not offered." } } }, "description": "One entry per requested product, in request order." }, "itemCount": { "type": "number", "description": "Entries in items." }, "market": { "type": "object", "additionalProperties": true, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "string", "description": "The AliExpress page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. product-search or product-reviews." }, "transport": { "type": "string", "description": "The upstream source the data came from: aliexpress." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "product-prices", "market": { "shipTo": "US", "currency": "USD", "language": "en_US" }, "notes": [], "itemCount": 2, "items": [ { "productId": "1005009494458560", "status": "ok", "available": true, "currency": "USD", "price": 16.33, "originalPrice": 41.14, "variant": {} }, { "productId": "1005006994630464", "status": "ok", "available": true, "currency": "USD", "price": 28.48, "originalPrice": 81.04, "variant": {} } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/product-reviews": { "post": { "operationId": "product-reviews", "tags": [ "Reviews" ], "summary": "Get buyer reviews for a product", "description": "Buyer reviews for one product, 20 per page, with the rating summary — the average, the total, the positive share and the count at each star — and how many reviews each filter holds. Each review carries its rating, date, text translated into the requested language where AliExpress did so and the reviewer’s original words, the masked reviewer name and country, the variant bought, the shipping method, photos, helpful count, any follow-up review and the seller’s reply. Many AliExpress reviews are a rating with no text, so text is null on those. Sort by latest to follow new reviews. A product with no reviews and an unknown product id both come back as an empty list, not a 404. If limit stops a response part-way through a page, the next cursor repeats that page — de-duplicate by reviewId, and notes says when it happens.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "description": "AliExpress product id or any product page URL." }, "sort": { "type": "string", "description": "best_match, or latest for newest first.", "example": "best_match" }, "filter": { "type": "string", "description": "all, with_photos, or additional (reviews with a follow-up).", "example": "all" }, "limit": { "type": "number", "description": "Maximum reviews returned (max 1000), or -1 for the maximum allowed.", "example": "20" }, "pages": { "type": "number", "description": "Pages of 20 to collect in one request (max 50), or -1 for the maximum allowed. Each page counts as one request.", "example": "1" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "shipTo": { "type": "string", "description": "Two-letter country code the shopper ships to, for example US or DE. Changes prices, shipping and availability.", "example": "US" }, "language": { "type": "string", "description": "Language for titles and labels: en_US, de_DE or pt_BR. Any other value is a 400.", "example": "en_US" }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "product" ] }, "examples": { "default": { "value": { "product": "1005009494458560", "sort": "latest", "shipTo": "US", "language": "en_US" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "description": "Global product id the reviews belong to." }, "ratings": { "type": "object", "additionalProperties": true, "description": "average, total, positivePercent, and fiveStar through oneStar counts." }, "filterCounts": { "type": "object", "additionalProperties": true, "description": "Reviews available under each filter: all, with_photos, additional." }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "reviewId": { "type": "string", "description": "Stable review id — de-duplicate on it." }, "rating": { "type": [ "number", "null" ], "description": "Stars out of 5." }, "date": { "type": [ "string", "null" ], "description": "Date as displayed, for example \"12 Sep 2026\"." }, "text": { "type": [ "string", "null" ], "description": "Review text in the requested language where AliExpress translated it. Null for a rating-only review." }, "originalText": { "type": [ "string", "null" ], "description": "The reviewer’s own words, when they differ from text." }, "reviewerName": { "type": [ "string", "null" ], "description": "Reviewer name, masked by AliExpress." }, "reviewerCountry": { "type": [ "string", "null" ], "description": "Two-letter country of the reviewer." }, "anonymous": { "type": "boolean", "description": "Whether the reviewer posted anonymously." }, "variant": { "type": [ "string", "null" ], "description": "The variant bought, for example \"Color:Black\"." }, "shippingMethod": { "type": [ "string", "null" ], "description": "Shipping method the order used." }, "imageUrls": { "type": "array", "items": { "type": "string" }, "description": "Photos attached to the review." }, "helpfulCount": { "type": [ "number", "null" ], "description": "Shoppers who marked it helpful." }, "additionalReview": { "type": [ "object", "null" ], "additionalProperties": true, "description": "A follow-up the reviewer added later, with its own text and photos." }, "sellerReply": { "type": [ "string", "null" ], "description": "The seller’s reply, when there is one." } } }, "description": "The reviews on this page or pages." }, "reviewCount": { "type": "number", "description": "Reviews in this response." }, "totalReviews": { "type": [ "number", "null" ], "description": "Reviews matching the filter in total." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as cursor to continue, or null when there is no next page." }, "hasNextPage": { "type": "boolean", "description": "Whether more reviews are available beyond this response." }, "market": { "type": "object", "additionalProperties": true, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "string", "description": "The AliExpress page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "resultType": { "type": "string", "description": "Which shape this response is, e.g. product-search or product-reviews." }, "transport": { "type": "string", "description": "The upstream source the data came from: aliexpress." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "product-reviews", "market": { "shipTo": "US", "currency": "USD", "language": "en_US" }, "notes": [], "productId": "1005009494458560", "sort": "latest", "filter": "all", "ratings": { "average": 4.7, "total": 2708, "positivePercent": 93.3, "fiveStar": 2275, "fourStar": 252, "threeStar": 92, "twoStar": 33, "oneStar": 56 }, "filterCounts": { "all": 2708, "with_photos": 544, "additional": 45 }, "reviewCount": 20, "totalReviews": 2708, "pagesScraped": 1, "nextCursor": "eyJwIjoyfQ", "hasNextPage": true, "reviews": [ { "reviewId": "60099036673946467", "rating": 4, "text": "Good keyboards, but the seller's packaging is very poor.", "originalText": "Buenos teclados pero el embalaje por parte del vendedor es muy malo", "date": "09 Sep 2026", "reviewerName": "R***a", "reviewerCountry": "CO", "anonymous": false, "variant": "Color:Black", "shippingMethod": "AliExpress Selection Standard Shipping", "imageUrls": [], "helpfulCount": 0, "additionalReview": null, "sellerReply": null } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse an AliExpress URL", "description": "Turn any AliExpress URL into the fields the other routes take: kind — product, search, category, store or short-link — plus whatever the URL carries: productId and skuId, the search query, page and filters, the categoryId, or the storeId. Works for regional hosts (de.aliexpress.com) and the US storefront. Short share links (a.aliexpress.com) do not carry the product; open one and pass the page it leads to. It makes no request to AliExpress and does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any AliExpress URL, to be parsed into structured request input." }, "format": { "type": "string", "description": "json, or markdown to get the result rendered as text.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://www.aliexpress.com/w/wholesale-mechanical-keyboard.html?sortType=total_tranpro_desc" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the URL points at: product, search, category, store, or short-link." }, "productId": { "type": "string", "description": "Present when kind is product — the global id." }, "skuId": { "type": "string", "description": "Present when a product URL selects a variant." }, "query": { "type": "string", "description": "Present when kind is search." }, "page": { "type": "number", "description": "Present when a search or category URL names a page." }, "filters": { "type": "object", "additionalProperties": true, "description": "Filters a search or category URL encodes." }, "categoryId": { "type": "string", "description": "Present when kind is category." }, "storeId": { "type": "string", "description": "Present when kind is store." }, "url": { "type": "string", "description": "The URL as parsed." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "search", "query": "mechanical keyboard", "page": 1, "filters": { "sort": "orders" }, "url": "https://www.aliexpress.com/w/wholesale-mechanical-keyboard.html?sortType=total_tranpro_desc" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/media": { "get": { "operationId": "media", "tags": [ "Utility" ], "summary": "Download a product image or video", "description": "Stream a product image, variant image, review photo or product video, using a url taken from a result. Only AliExpress’s own image and video hosts are accepted. HTTP Range requests are supported, so a video can be fetched in pieces. This is a GET with query parameters, not a JSON POST, and it bills as one request. The file is served in whatever format AliExpress stores — an image URL ending in .png can come back as image/webp, so trust Content-Type rather than the extension.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Product image, review photo or video URL, as returned on a result. Passed as a query parameter.", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Content-Disposition filename to serve the file as (max 200 characters).", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Standard HTTP Range request header, for example bytes=0-65535. Sent as a header, not a query parameter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }