Blog / API guides

Mercado Libre API: Category Prices and Reviews as JSON

17 Aug 2026Perceptlayer7 min read

The Mercado Libre API returns product data for Latin American marketplaces as JSON, with one key and no scraper. Call /v1/mercadolibre/category-products with a site and a category_id and you get the category's best sellers and offers, each with price, previous price, currency, discount label and shipping text. Every call costs 1 credit.

Which Mercado Libre endpoints return product data?

Eleven endpoints cover the marketplace, and each costs 1 credit per successful call. Four of them matter for price and review tracking: categories for category data, category-products for the products in a category, reviews for individual reviews and review-summary for the rating overview. The rest cover discovery, shipping, stores and suggestions.

Related Products, Suggestions, Category Attributes, Store and Stores round out the set. All of them sit on the Mercado Libre API page, part of the Marketplaces APIs.

How do you get a key and make the first call?

Sign up, verify an email address and you get 1,000 free credits every month, with no credit card. Send the key in the X-API-Key header. Keys start with sk_live_. The authentication docs cover the api_key query parameter for places where headers aren't possible, and the quick start walks through a first call.

Get a free API key, then call categories for a category:

curl "https://api.perceptlayer.com/v1/mercadolibre/categories?site=MLA&category_id=MLA1574" \
  -H "X-API-Key: $API_KEY"

site and category_id are both optional on this endpoint. The site values are MLA, MLB, MLM, MLC, MCO, MPE, MLU, MEC and MLV, one per country marketplace. The recorded sample below is MLA, which resolves to mercadolibre.com.ar and prices in ARS.

How do you find the category you want to track?

Start from a keyword and let category-discovery map it to categories, because the API has no free-text item search. It takes site and q (up to 200 characters) and an optional limit. It returns matching categories (the Category Discovery page lists the fields); pass a category's ID to category-products. suggestions takes site, q (up to 100 characters) and limit.

curl "https://api.perceptlayer.com/v1/mercadolibre/category-discovery?site=MLA&q=camara%20de%20seguridad&limit=5" \
  -H "X-API-Key: $API_KEY"

Do this once per category and store the IDs. Category discovery is a setup step, not part of the tracking loop, so it costs you a handful of credits in total rather than per run. If you need the fields a category's items must carry, Category Attributes takes only a category_id.

Which parameters does Category Products take?

category-products takes two required parameters and nothing else. The Category Products page has the playground if you'd rather try it in the browser first.

Here's the call behind the recorded response:

curl "https://api.perceptlayer.com/v1/mercadolibre/category-products?site=MLA&category_id=MLA1574" \
  -H "X-API-Key: $API_KEY"

There's no limit or offset on this endpoint, so one call returns whatever the category's lists hold at that moment.

What does a price record look like?

Each product carries the current price, the previous_price, the currency and a discount_label, plus shipping text and a fulfilled_by_mercado_libre flag. That's enough to build a price history without opening a single product page. This is an excerpt of the recorded response for category MLA1574 on MLA:

{
  "success": true,
  "data": {
    "site": "MLA",
    "category_id": "MLA1574",
    "products": [
      {
        "position": 2,
        "tab": "affiliate-profile-best-sellers",
        "item_id": "MLA1550818153",
        "product_id": "MLA43779215",
        "title": "Camara Seguridad Geotek 3mp Ip Wifi Exterior Full Hd Domo Vision Nocturna …",
        "brand": "GEOTEK",
        "official_store": true,
        "highlight": "MÁS VENDIDO",
        "price": 46567,
        "previous_price": 74999,
        "currency": "ARS",
        "discount_label": "37% OFF",
        "shipping_text": "Envío gratis",
        "shipping_note": "por ser tu primera compra",
        "fulfilled_by_mercado_libre": true
      }
    ],
    "total": 33,
    "source_tabs": [
      { "id": "affiliate-profile-best-sellers", "title": "Más vendidos", "count": 18 },
      { "id": "affiliate-profile-offers", "title": "Ofertas", "count": 15 }
    ]
  },
  "meta": { "endpoint_family": "category_products", "billable": true, "duration_ms": 764 }
}

Three things worth knowing. tab says which list a product came from, and source_tabs counts them: 18 best sellers and 15 offers make the total of 33. item_id identifies the listing, while product_id is only present on some products, so don't treat it as always there. And previous_price is a single value per product, not a series. Your own stored snapshots are the history.

How do you turn this into a price tracker?

Call the endpoint on a schedule, key each product by item_id, and store price, previous_price and currency with a timestamp. Compare today's price to the last stored one, not to previous_price. The script below does the first half: it pulls the category and prints the products whose listed discount is deepest.

import os
import requests

BASE = "https://api.perceptlayer.com"
HEADERS = {"X-API-Key": os.environ["API_KEY"]}

resp = requests.get(
    f"{BASE}/v1/mercadolibre/category-products",
    headers=HEADERS,
    params={"site": "MLA", "category_id": "MLA1574"},
    timeout=30,
)
resp.raise_for_status()
print("credits used:", resp.headers.get("X-Credits-Used"))

rows = []
for p in resp.json()["data"]["products"]:
    old, new = p.get("previous_price"), p.get("price")
    if old and new:
        rows.append((round(100 * (old - new) / old), p["item_id"], new, p["currency"]))

for pct, item_id, price, currency in sorted(rows, reverse=True)[:10]:
    print(f"{pct}% off  {item_id}  {price} {currency}")

Writing each run to a database table keyed by item_id and date gives you the history. Handle failures as covered in Docs: Errors: a 429 or 503 carries a Retry-After header.

How do you pull reviews and rating summaries?

Use review-summary for the overview and reviews for the individual entries, both keyed by site and id. Set id_type to item or product to say what the id is. reviews also accepts limit, offset, rating (an integer filter) and order (relevance or date). We don't have a recorded response for these two, so check the Review Summary and Reviews pages for the returned fields.

curl "https://api.perceptlayer.com/v1/mercadolibre/review-summary?site=MLA&id=MLA43779215&id_type=product" \
  -H "X-API-Key: $API_KEY"

curl "https://api.perceptlayer.com/v1/mercadolibre/reviews?site=MLA&id=MLA43779215&id_type=product&order=date&limit=20" \
  -H "X-API-Key: $API_KEY"

The product_id from the category response is the natural id here, with id_type=product. Where a product has no product_id, use its item_id with id_type=item. A sensible pattern is to poll review-summary for every tracked product and fetch reviews only when the summary changes.

What does tracking one category cost?

Tracking one category daily costs 30 credits a month, and adding review summaries for its 33 products once a week brings it to 162. All of these endpoints cost 1 credit per successful call, so the arithmetic is a count of calls. The credits docs explain how debits work.

That fits comfortably inside the 1,000 free credits a month. Scale it out: 10 categories pulled 4 times a day for 30 days is 10 × 4 × 30 = 1,200 calls × 1 credit = 1,200 credits for the price pulls alone, which is past the free tier. Paid credits come in prepaid packs starting at 10,000 credits, last 12 months, and have no subscription. Pricing has what credits cost. Failed calls return X-Credits-Used: 0, and the rate limits are per account.

When is the official API a better fit?

If you sell on the marketplace and need to create listings or manage orders, use Mercado Libre's own developer platform. You register an application, and calls on behalf of a seller authenticate through OAuth 2.0 access tokens, so it's built around a seller's own account: listings, orders and similar seller data. That's the right fit for running a store, but it means registering an app and running the token flow before you read anything.

This API is the other trade-off. It only reads public market data and never touches a seller account, so it can't create or change anything. For read-only data across a category, such as best sellers, offers, prices and reviews, with one key and a site parameter that switches between the nine country sites, it's the shorter path. Browse the storefront itself, for example mercadolibre.com.ar, to check any value against what a shopper sees.

Data is collected from publicly available sources and returned as found at the time of the call, so a price you pull is the price shown then. For the same workflow on other stores see the Walmart product search API and the Google Shopping API.

Your next step: open the Mercado Libre API page, pick category-products, enter MLA and MLA1574 in the playground and run the call with your key.

mercado libreecommerceprice trackinglatin americareviews