datawebotMercado Libre product data: listings, variations and catalog IDs
Understand Mercado Libre listing, variation and catalog IDs. Interpret public available_quantity bands and compare listing search with seller OAuth.
Why item and catalog IDs are not interchangeable
Treat a Mercado Libre item as a seller's marketplace offer. A linked catalog product can help with product matching, but it does not replace the item, its seller, selected variation, price or local market. Keep each documented identifier in its own field.
Scroll to compare →
| Record layer | Fields to preserve | What the field identifies |
|---|---|---|
| Marketplace site | site_id, currency_id | The local marketplace and its currency; official examples include MLA (Argentina), MLB (Brazil) and MLM (Mexico). |
| Listing / offer | id (item ID), seller_id, category_id | A concrete marketplace listing and the seller responsible for that offer. Do not deduplicate offers by title alone. |
| Selected variation | variation_id, attribute_combinations | The specific option combination, such as a size or color, when the listing has variations. |
| Catalog relation | catalog_product_id, item_relations | A product-matching relationship. It does not identify the seller's price or replace the related item and variation. |
| Price observation | price, currency_id, source URL, observation time | A time-bound offer value. Keep it attached to the site, item, seller and selected variation it describes. |
Choose a matching rule that preserves the offer
A product comparison often needs two grains: one row per seller offer and a separate product-level match. Use the catalog relation as a candidate link, then preserve the fields that let someone reproduce the comparison.
Scroll to compare →
| Comparison | Match or group by | Keep distinct |
|---|---|---|
| Same catalog product, different sellers | Use catalog_product_id as a product-level match when present; validate distinguishing attributes. | Keep each item id, seller_id, price, currency_id and observation time as a separate offer. |
| One listing with several options | Use item id plus variation_id and its attribute_combinations for an option-level observation. | Do not assume every variation has the same price, identifiers or catalog relation. |
| Same product on different site codes | Group only after a verified product match across local sites. | Retain site_id, currency_id and each local item/seller offer; an item ID is not a global product key. |
How to interpret public available_quantity values
Mercado Libre documents the public available_quantity field as referential: the response value maps to a range of real quantities. Preserve that meaning and do not report the public value as an exact competitor stock count.
Scroll to compare →
| Underlying quantity band | Public reference value | Safe interpretation |
|---|---|---|
| 1–50 | 1 | Somewhere in the documented 1–50 band, not necessarily one unit. |
| 51–100 | 50 | A banded reference, not a precise count of 50. |
| 101–150 | 100 | A banded reference, not a precise count of 100. |
| 151–200 | 150 | A banded reference, not a precise count of 150. |
| 201–250 | 200 | A banded reference, not a precise count of 200. |
| 251–500 | 250 | A banded reference, not a precise count of 250. |
| 501–5,000 | 500 | A wide availability band; do not infer an exact level. |
| 5,001–50,000 | 5,000 | A wide availability band; do not infer an exact level. |
| 50,001–99,999 | 50,000 | A wide availability band; do not infer an exact level. |
When active listing search differs from seller OAuth access
Mercado Libre documents separate resources for active marketplace listings and a seller's account items. Choose based on whose data the workflow is authorized to access; an API token does not create permission to inspect another seller's private account.
Scroll to compare →
| Resource | Documented role | Access boundary |
|---|---|---|
| /sites/{SITE_ID}/search | Search active listings at a selected marketplace site; results follow the platform's listing rules. | A public-listing search path. API access requirements and permitted content use still apply. |
| /users/{USER_ID}/items/search | List items from a seller's account. | Private account data uses an access token. OAuth authorization is granted by the user; it is not a route to another seller's private records. |
Keep Mexico Developer Program terms in their stated scope
The cited terms are for Mercado Libre's Mexico Developer Program. They govern API and platform content used under that program; they are not a universal statement about every Mercado Libre site. Check the current terms that apply to the market and intended use.
Scroll to compare →
| Term topic | What the Mexico program terms state | Practical reading |
|---|---|---|
| Program scope | The terms set rules for participation in the Developer Program and access to or use of its API and content. | Identify the country program and account context before designing an access path. |
| Automated collection | Clause 7.6 restricts robots, harvesters, spiders, scraping or similar technology to access content outside what the program provides. | Do not treat a public page or API endpoint as permission to collect or reuse content. |
| API/content use | The terms limit use to stated program purposes and prohibit using API/content to develop products or services that compete with Mercado Libre. | Review the full current terms and intended use; this page is a source summary, not legal advice. |
Content reviewed 2026-10-02.