List AliExpress category navigation API

Endpoint facts

Method

GET

API path

/aliexpress/categories

Auth

apiKey

Credits

3 credits/request

Charged on

Successful 2xx responses only

Platform

AliExpress

Execution

Managed browser rendering where the target needs it

Response schema

#/definitions/aliexpress.categoriesResponseDoc

MCP tool

aliexpress_categories

How this endpoint behaves

MCP tool: aliexpress_categories

The numeric category_id values here are AliExpress's platform/taxonomy ids. They are not the web category ids that aliexpress_category_products or aliexpress_search's cat_id accept; use aliexpress_category_ids to discover those.

Query parameters:

• category_tab (optional): a top-level tab id copied from an unfiltered response, for example electronics. Omit it to list the top-level tabs only.

Response shape:

• count: number of top-level categories returned (about 24).
• category_tab: echoes the expanded tab, omitted when it was not requested.
• categories: the level-1 category tabs, in AliExpress's own order. Each node has id (navigation slug such as electronics), name, level (1), category_id (the numeric platform category id), and icon_url.
• When category_tab is given, that tab's node also carries children: its level-2 categories (level: 2, parent_id set), each with children of level-3 categories (level: 3, parent_id set) that carry category_id, search_keyword and search_url.

Honest id semantics:

• category_id is exposed only where AliExpress's payload carries one. That is the level-1 tabs and the level-3 categories; level-2 categories have no numeric platform id in the payload, so the field is omitted for them rather than invented.
• search_keyword/search_url exist for level-3 categories because that is where AliExpress's navigation payload carries a search keyword (its own url field is an aecmd:// app-scheme URL, which is not exposed). Pass search_keyword to aliexpress_search as q, or follow search_url.
• The payload's layoutInfo declares four render sections (categories, subCategories, rankList, searchList), but the measured anonymous response only returns the tab list plus the level-2/3 tree for a selected tab. There are no rankList or searchList arrays in it, so none are returned here.

Errors:

• 400 for a category_tab that is not one of AliExpress's tab ids, including a value with characters a tab id can never contain. The tab set is upstream-owned, so the check is a shape check plus the upstream's own acceptance: an unknown but well-formed tab is reported as 400 carrying the tab id.
• 503 when AliExpress refuses or cannot serve the request: a bot challenge, a malformed or empty payload, or a transport failure. A transient transport failure is retried once; a challenge is never retried, solved or bypassed.

Data source:

• AliExpress's category navigation taxonomy as shown to an anonymous visitor in the site header, read from AliExpress's public web gateway and measured live on 2026-10-25. The locale is fixed to US English / USD.
• No login, account, cookie or device identity of yours is involved, and no challenge is solved.

Responses are cached for up to 24 hours per category_tab; fetched_at is when AliExpress was last queried.

Example response (no category_tab — top-level tabs only):

{
  "code": 200,
  "msg": "OK",
  "data": {
    "count": 2,
    "source_url": "https://www.aliexpress.com/",
    "fetched_at": "2026-10-25T10:05:33Z",
    "categories": [
      {
        "id": "electronics",
        "name": "Electronics",
        "level": 1,
        "category_id": "10536",
        "icon_url": "https://ae01.alicdn.com/kf/Sa1b2c3/electronics.png"
      },
      {
        "id": "home-garden",
        "name": "Home & Garden",
        "level": 1,
        "category_id": "100004412",
        "icon_url": "https://ae01.alicdn.com/kf/Sd4e5f6/home.png"
      }
    ]
  }
}

Example response with category_tab=electronics (the tab is expanded, and levels 2 and 3 appear as children):

{
  "code": 200,
  "msg": "OK",
  "data": {
    "count": 1,
    "category_tab": "electronics",
    "source_url": "https://www.aliexpress.com/",
    "fetched_at": "2026-10-25T10:05:33Z",
    "categories": [
      {
        "id": "electronics",
        "name": "Electronics",
        "level": 1,
        "category_id": "10536",
        "children": [
          {
            "id": "consumer-electronics",
            "name": "Consumer Electronics",
            "level": 2,
            "parent_id": "electronics",
            "children": [
              {
                "id": "semiconductors",
                "name": "Semiconductors",
                "level": 3,
                "parent_id": "consumer-electronics",
                "category_id": "100010632",
                "search_keyword": "semiconductors",
                "search_url": "https://www.aliexpress.com/w/wholesale-semiconductors.html?SearchText=semiconductors&catId=0"
              }
            ]
          }
        ]
      }
    ]
  }
}

Second-level categories never carry a numeric category_id because AliExpress's payload does not include one; only tabs and third-level categories expose it.

Sampled response

Request, 26 Oct 2026

GET /aliexpress/categories

Items in categories

24

Fields filled in every checked item

5

Shared guides

Related