Best sellers in Mercado Libre

Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.

Last update 22/06/2026

Best sellers on Mercado Libre

Query the top 20 best-selling products on Mercado Libre using the /highlights resource. You can filter by category, brand, product, and/or item.

Best sellers by category

Query the top 20 items/products within a specific category.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/highlights/$SITE_ID/category/$CATEGORY_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/highlights/MLB/category/MLB432825

Response:

{
    "query_data": {
        "highlight_type": "BEST_SELLER",
        "criteria": "CATEGORY",
        "id": "MLB432825"
    },
    "content": [
        {
            "id": "MLBU3013800008",
            "position": 1,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLBU3981133472",
            "position": 2,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLBU4039073621",
            "position": 3,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLBU3021966048",
            "position": 4,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLBU3969242429",
            "position": 5,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLB24162817",
            "position": 6,
            "type": "PRODUCT"
        },
        {
            "id": "MLBU4035041691",
            "position": 7,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLB47622621",
            "position": 8,
            "type": "PRODUCT"
        },
        {
            "id": "MLBU3981122876",
            "position": 9,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLB24723692",
            "position": 10,
            "type": "PRODUCT"
        },
        {
            "id": "MLB70334862",
            "position": 11,
            "type": "PRODUCT"
        },
        {
            "id": "MLBU670601037",
            "position": 12,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLBU3986388996",
            "position": 13,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLBU1966388133",
            "position": 14,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLBU3440726552",
            "position": 15,
            "type": "USER_PRODUCT"
        },
        {
            "id": "MLB6868664726",
            "position": 16,
            "type": "ITEM"
        },
        {
            "id": "MLB61695785",
            "position": 17,
            "type": "PRODUCT"
        },
        {
            "id": "MLB70659272",
            "position": 18,
            "type": "PRODUCT"
        },
        {
            "id": "MLB41966415",
            "position": 19,
            "type": "PRODUCT"
        },
        {
            "id": "MLB2064796357",
            "position": 20,
            "type": "PRODUCT"
        }
    ]
}

Response fields

query_data: information about the filter applied to the query.

highlight_type: ranking type. Fixed value: BEST_SELLER.
criteria: criteria used. Value: CATEGORY.
id: ID of the queried category.

content: list of up to 20 best-selling elements.

id: element identifier. The prefix varies by type (MLB, MLA, MLBU, etc.).
position: position within the ranking (1 = best seller).
type: element type. Possible values:
- ITEM: individual listing with no catalog association.
- PRODUCT: product from the official Mercado Libre catalog.
- USER_PRODUCT: product created by a seller (user catalog). The ID uses the MLBU prefix.

Note:

The list may contain a mix of all three types (ITEM, PRODUCT, USER_PRODUCT) based on the best-selling products in the category.

Best sellers by category and brand attribute

Get the top 20 items/products of a specific brand within a category. Use the attribute and attributeValue parameters to filter by any supported attribute.

Query parameters

attribute (required): name of the attribute to filter by. Example: BRAND.
attributeValue (required): ID of the attribute value. Example: 59387.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/highlights/$SITE_ID/category/$CATEGORY_ID?attribute=BRAND&attributeValue=$BRAND_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/highlights/MLA/category/MLA1055?attribute=BRAND&attributeValue=59387

Response:

{
    "query_data": {
        "highlight_type": "BEST_SELLER",
        "criteria": "CATEGORY",
        "id": "MLA1055"
    },
    "content": [
        {
            "id": "MLA55323897",
            "position": 1,
            "type": "PRODUCT"
        },
        {
            "id": "MLA65759096",
            "position": 2,
            "type": "PRODUCT"
        },
        {
            "id": "MLA45818964",
            "position": 3,
            "type": "PRODUCT"
        },
        {
            "id": "MLA46219511",
            "position": 4,
            "type": "PRODUCT"
        }
    ]
}

Note:

When an attribute filter is applied, the result may contain fewer than 20 elements if the brand does not have enough products in the category ranking.

Product position

Query the position of a product within the best sellers ranking and the category or dimension it is ranked in.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/highlights/$SITE_ID/product/$PRODUCT_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/highlights/MLA/product/MLA55323897

Response:

{
    "dimension": "attributes",
    "id": "MLA1055-BRAND-59387",
    "label": "Celulares y Smartphones Xiaomi",
    "position": 1
}

Response fields

dimension: criteria by which the product is ranked. Possible values:
- category: the product is in the top of a category.
- attributes: the product is in the top of a category filtered by attribute (e.g. brand).
id: identifier of the dimension.
- If dimension = category: category ID (e.g. MLA1055).
- If dimension = attributes: composite ID with format {CATEGORY_ID}-{ATTRIBUTE}-{VALUE_ID} (e.g. MLA1055-BRAND-59387).
label: descriptive name of the dimension (e.g. category name or category + brand).
position: position of the product within the ranking of that dimension.

Item position

Query the position of a listing (item) within the best sellers ranking.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/highlights/$SITE_ID/item/$ITEM_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/highlights/MLB/item/MLB6868664726

Response:

{
    "dimension": "category",
    "id": "MLB270287",
    "label": "Geladeiras",
    "position": 12
}

Response fields

dimension: criteria by which the item is ranked. Value: category.
id: ID of the category where the item is ranked.
label: category name.
position: position of the item within the ranking of that category.

Errors

Code	Message	Cause	Solution
400	Error site: ML	The site_id provided is not valid.	Use a valid site_id (MLA, MLB, MLM, MCO, MLC, etc.).
400	Invalid product id MLB	The product_id or item_id is invalid or does not belong to the specified site.	Verify the ID is correct and matches the site_id in the URL.
401	unspecified_token	No access token was sent or the format is incorrect.	Include the header Authorization: Bearer $ACCESS_TOKEN with a valid token.
404	item/product with id {id} not found	The item or product exists but does not appear in any best sellers ranking.	Only items/products that are in the top 20 of a category can be queried for position.
404	Dimension CATEGORY with id {id} not found	The category does not have an available best sellers list.	Make sure the category is a leaf node in the category tree (a category with no subcategories).