AliExpress Category Products API

Endpoint facts

Method

GET

API path

/aliexpress/category-products

Auth

apiKey

Credits

3 credits/request

Charged on

Successful 2xx responses only

Platform

AliExpress

Response schema

#/definitions/aliexpress.categoryProductsResponseDoc

MCP tool

aliexpress_category_products

How this endpoint behaves

MCP tool: aliexpress_category_products

This is the category-browsing counterpart to keyword search: instead of a query it walks AliExpress's own category path.

Query parameters:

• category_id (required): the AliExpress web category id, the number in a /category/<id>/<slug>.html URL on aliexpress.com, for example 5090301 for Cellphones. This is not the id aliexpress_categories returns: those are navigation/platform ids in a different namespace and give an empty listing here. Discover valid ids with aliexpress_category_ids (pass q for a keyword or category_id to walk the tree), or copy the id from the category's page URL.
• slug (optional): the category's path segment in AliExpress's own URL, for example cellphones. It is cosmetic — the listing is selected by category_id — so it defaults to products. Supplying the real slug keeps your URLs identical to the site's.
• page (optional): 1-indexed page number, 1 through 60; defaults to 1.

Each product has the fields documented in aliexpress_search: product_id, title, url, image_url, price, currency_code, original_price, rating, sold_text, discount_percent, sku_id, ship_from, store_name.

Notable behavior:

• The response echoes the resolved category_id, slug, page, page_size, total_results, total_pages and count alongside products, source_url and fetched_at.
• Pagination is the site's own ?page=N. A page whose echoed number does not match the request is reported as an upstream contract break rather than silently returned.
• A category page that reports results but carries no parseable products is an upstream error, not an empty success — the same rule the search endpoint applies.
• Duplicate product ids within a page are collapsed.
• Ordering is AliExpress's own and is not documented as stable between calls.
• Pagination is reliable for the first pages and degraded deeper. Live sampling on 2026-10-26: page 1 and page 2 each returned 60 products with every promised field; page 3 returned a payload that reported 19 results and carried no parseable products, which this endpoint surfaces as an upstream error rather than as an empty success. Treat deep pages as best-effort and retry or stop rather than walking 15 pages blindly.

Errors:

• 400 for a missing/non-positive category_id, a slug containing anything other than lower-case letters/digits/hyphens (path traversal and query injection are rejected here), or a page outside 1-60. These are rejected before any upstream request.
• 503 when the upstream page cannot be used: a bot challenge page, a transport failure, an unparseable body, or a listing that reports results with no parseable products. A transient transport failure is retried once; a challenge is never retried, solved or bypassed.

Data source:

• The public category listing page https://www.aliexpress.com/category/<category_id>/<slug>.html, the same anonymous page family as aliexpress_search, with the same product fields. The locale is fixed to US English / USD.
• Measured live on 2026-10-26: pages 1 and 2 return 60 products with every promised field; deeper pages are degraded (see above).
• No login, account or device identity of yours is involved, and no challenge is solved.

Sampled response

Request, 26 Oct 2026

GET /aliexpress/category-products?category_id=5090301&slug=cellphones&page=1

Items in products

60

Fields filled in every checked item

8

Fields empty in some or all items

4

Shared guides

Related