Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Última actualización 10/10/2024
Catalog competition
Notification for status changes
With the Item competition topic you can subscribe and start receive notifications of the change of status of catalog items, and will allow you to recognize the item that modifies its competition status to winner.
Competition detail
With the resource /price_to_win?siteId=$SITE_ID&version=v2 you recognize detail information about the status of the catalog publication: it may be winning, sharing first, losing or listed. When a publication has a listed status it means that it cannot win in the catalog because it does not comply with certain reasons that prevent it from competing, but it is still a publication that a buyer can purchase and view from Mercado Libre's main search engine.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/price_to_win?siteId=$SITE_ID&version=v2Example of a request to a publication that is losing in the competition:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1234567/price_to_win?version=v2Response with status:competing:
{
"item_id": "MLA930793214",
"current_price": 267999,
"currency_id": "ARS",
"price_to_win": 267999,
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
}
],
"status": "winning",
"consistent": true,
"visit_share": "maximum",
"competitors_sharing_first_place": 0,
"reason": [],
"catalog_product_id": "MLA16163648",
"winner": {
"item_id": "MLA930793214",
"price": 267999,
"currency_id": "ARS",
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
}
]
}
}Example of request for a publication that is winning in the competition:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA765432/price_to_win?version=v2Response with status:winning:
{
"item_id": "MLA930793214",
"current_price": 267999,
"currency_id": "ARS",
"price_to_win": 267999,
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
}
],
"status": "winning",
"consistent": true,
"visit_share": "maximum",
"competitors_sharing_first_place": 0,
"reason": [],
"catalog_product_id": "MLA16163648",
"winner": {
"item_id": "MLA930793214",
"price": 267999,
"currency_id": "ARS",
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
}
]
}
}Example of a request for a publication that is sharing first place in the competition:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA9876543/price_to_win?version=v2Response with status: sharing_first_place:
{
"item_id": "MLA9876543",
"current_price": 493000,
"currency_id": "ARS",
"price_to_win": 485109,
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
}
],
"status": "sharing_first_place",
"consistent": true,
"visit_share": "medium",
"competitors_sharing_first_place": 1,
"reason": [],
"catalog_product_id": "MLA15934914",
"winner": {
"item_id": "MLA765432",
"price": 48150,
"currency_id": "ARS",
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas al mismo precio que publicaste"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "opportunity",
"description": "Envíos en el día por Mercado Envíos"
}
]
}
}
Example of a request for a publication that is not in competition:
curl -X GET https://api.mercadolibre.com/items/MLA1146313673/price_to_win?access_token=$ACCESS_TOKENResponse:
{
"item_id": "MLA1146313673",
"current_price": 239999,
"currency_id": "ARS",
"price_to_win": null,
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "opportunity",
"description": "Envíos en el día por Mercado Envíos"
}
],
"status": "listed",
"consistent": true,
"visit_share": "minimum",
"competitors_sharing_first_place": null,
"reason": [
"reputation_below_threshold"
],
"catalog_product_id": "MLA16163648",
"winner": {
"item_id": "MLA930793214",
"price": 267999,
"currency_id": "ARS",
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
}
]
}
}Example of a request for a publication that is not in competition:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA456789/price_to_win?version=v2Response with status: listed:
{
"item_id": "MLA456789",
"current_price": 239999,
"currency_id": "ARS",
"price_to_win": null,
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "opportunity",
"description": "Envíos en el día por Mercado Envíos"
}
],
"status": "listed",
"consistent": true,
"visit_share": "minimum",
"competitors_sharing_first_place": null,
"reason": [
"reputation_below_threshold"
],
"catalog_product_id": "MLA15934914",
"winner": {
"item_id": "MLA765432",
"price": 48150,
"currency_id": "ARS",
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas al mismo precio que publicaste"
},
{
"id": "free_shipping",
"status": "boosted",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
},
{
"id": "same_day_shipping",
"status": "opportunity",
"description": "Envíos en el día por Mercado Envíos"
}
]
}
}Response fields
price_to_win: indicates the price (in the current currency of the publication) so that you have a more competitive publication, that is, request PUT to the /items resource with the suggested price, your publication will have a more competitive price in the Catalog.
boosts: characteristics of the publication that provide chances of winning, such as:
- same_day_shipping: shipping on day with Mercado Envíos.
- fulfillment: Mercado Envíos Full.
- free_installments: interest-free fees.
- free_shipping: free Shipping con Mercado Envios.
- shipping_quarantine: shipping normally.
- shipping_collect: Mercado Envios Colecta.
- Winning: always will be maximum.
- Competing: always will be minimum.
- Sharing_first_place: always will be medium. competitors_sharing_first_place: the amount of sellers sharing the first place. It will also depend on the state of the publications.
- Winning: will always be 0, since by winning, you will take all sales and visibility in the catalog.
- Competing: will always be null, since if you lose, you will have to improve the conditions to share the first place or win.
- Listed: will always be null, since if you lose, you will have to improve the conditions to share the first place or win.
- Sharing_first_place: will show the value of sellers that are competing for the first place.
Now, you can recognize within the boost the state of these and draw a comparison table accordingly.
| Boost status | Detail |
|---|---|
| boosted | It has the condition of sale and currently applies the boost. |
| not_boosted | It has the condition of sale but it is not a boost that improves the chances of winning. |
| opportunity | It does not have the condition of sale. If applied, it would improve the chances of winning. |
| not_apply | The sales condition does not apply as a boost to the product where the item competes. |
status: the product is winning for the public or for minority segments, for example, as those who do not take advantage of same day shipping. When it is winning, the value is winning, otherwise it will be competing for the one who is losing, and a new value is added sharing_first_place for when the first place is shared with other publications of the product page.
visit_share: the level of visibility your publication has in the catalog. These values can vary depending on the state:
reason: Mostrará información únicamente cuando la publicación no esté compitiendo, permitiendo identificar el motivo por el cual no lo está haciendo y así realizar acciones de mejora.
catalog_product_id: Indica el ID de la página de producto a la que pertenece la publicación.
winner: Indica el detalle del producto que está actualmente como ganador, permitiendo realizar una comparación rápida, con el item_id de la publicación que estás consultando, mostrando campos como: item_id, price, currency_id y boosts.
Reasons
There are different reasons why a publication is not competing within the catalog, below we list all the possible reasons that the price_to_win endpoint will answer in the reason attribute, which will allow you to perform the different actions to improve your publication and enter it to the competition.
| Reason | Description |
|---|---|
| non_trusted_seller | The seller cannot compete because he is marked as unreliable seller. It appears at the bottom of the list. |
| reputation_below_threshold | The seller cannot compete because he does not achieve the reputation needed to win. Appears on the list. |
| item_reputation_below_threshold | The publication cannot compete, as it does not reach the reputation required to win. It appears in the listings. |
| winner_has_better_reputation | The seller has a reputation that could compete but there is a winner with a better reputation. At the moment, it only appears in the listings (yellow case with green winner). |
| manufacturing_time | The publication has manufacturing team, appears only on the list, and cannot win because the winner has immediate stock. |
| temporarily_winning_manufacturing_time | The publication has manufacturing team, is temporarily winning because there are no competitors at the same level of reputation without manufacturing team. |
| temporarily_competing_manufacturing_time | The publication has a manufacturing team, it is competing temporarily because there are no competitors at the same level of reputation without a manufacturing team, the winner also has a manufacturing team. |
| temporarily_winning_best_reputation_available | The seller is not green but has a reputation that can win and is the best offer available. He is winning temporarily. If a better offer appears, stop winning. |
| temporarily_competing_best_reputation_available | The seller is not green, but has the best reputation available, he is competing temporarily. The winner is also of the same reputation. If a better seller comes along, it will go back to just being on the list. |
| item_paused | The item is paused, it cannot be listed. |
| item_not_opted_in | No optin was made from the publication, it cannot appear in the list, the item_id call was used from a publication that is not from a catalog or is a test item, so it cannot enter the competition. |
| shipping_mode | The seller is not competing because their shipping method is inferior to the winner. ME2 > ME1 > Custom Shipping > Not Specified. |
| newbie_program_seller | The seller has reached the sales limit defined by the startup dosage program. |
Winning publication
Using the /products/{product_id} feature, in addition to knowing the product's features and status, you can recognize by the buy_box_winner field which publication is winning on the product page.
Example of a product page detail short answer:
"id": "MLM12345",
"status": "active",
"sold_quantity": 391,
"domain_id": "MLM-CELLPHONES",
"permalink": "https://www.mercadolibre.com.mx/apple-iphone-13-pro-128-gb-grafito,
"name": "Apple iPhone 13 Pro (128 GB) - Grafito",
"family_name": "Apple iPhone 13 Pro",
"buy_box_winner": {
"item_id": "MLM987654321",
"category_id": "MLM1055",
"seller_id": 1234567,
"price": 25219,
"currency_id": "MXN",
"sold_quantity": 362,
"available_quantity": 110,
"shipping": {
"mode": "me2",
"tags": [
"mandatory_free_shipping"
],
"free_shipping": true,
"logistic_type": "fulfillment",
"store_pick_up": false
},
"warranty": "Garantía de fábrica: 12 meses",
"condition": "new",
"sale_terms": [...],
"official_store_id": 3953,
"original_price": 25999,
"listing_type_id": "gold_pro",
"accepts_mercadopago": true,
"seller_address": {...},
"international_delivery_mode": "none",
"tags": [...],
"item_override_attributes": [],
"seller": {
"reputation_level_id": "GREEN",
"tags": []
},
"deal_ids": [...],
"tier": "candidate",
"inventory_id": "DHEV26968",
"product_id": "MLM18494248",
"site_id": "MLM"
},
"buy_box_winner_price_range": {
"min": {
"price": 25219,
"currency_id": "MXN"
},
"max": {
"price": 38999,
"currency_id": "MXN"
}
},
"pickers": [ ... ],
"pictures": [ ... ],
"main_features": [ ... ],
"attributes": [ ... ],
"short_description": { ... },
"parent_id": "MLM18494246",
"children_ids": [],
"settings": { ... },
"buy_box_activation_date": "2022-04-22T15:20:15Z",
"authority_types": [ ... ],
"date_created": "2021-09-27T18:13:54Z"
}List of publications for a product page
If you need to know which catalog publications (from all sellers) are competing for sales of a particular product page, make the following call:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/$PRODUCT_ID/itemsExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/MLA18494233/itemsSimplified response
{
"paging": {
"total": 41,
"offset": 0,
"limit": 100
},
"results": [
{
"item_id": "MLA1110011006",
"site_id": "MLA",
"seller_id": 1234567,
"accepts_mercadopago": true,
"sold_quantity": 25,
"available_quantity": 1,
"price": 492499,
"category_id": "MLA1055",
"currency_id": "ARS",
"warranty": "Garantía de fábrica: 12 meses",
"condition": "new",
"listing_type_id": "gold_special",
"international_delivery_mode": "none",
"tier": "",
"inventory_id": "",
"tags": [
"good_quality_picture",
"good_quality_thumbnail",
"extended_warranty_eligible",
"immediate_payment",
"cart_eligible"
],
"deal_ids": [],
"official_store_id": null,
"original_price": null,
"shipping": {
"free_shipping": true,
"store_pick_up": false,
"mode": "me2",
"logistic_type": "xd_drop_off",
"tags": [
"self_service_in",
"mandatory_free_shipping"
]
},
"seller_address": {...
},
"sale_terms": [
{
"value_struct": null,
"id": "INVOICE",
"name": "Facturación",
"value_name": "Factura A",
"value_id": "6891885"
},
{
"value_struct": {
"number": 12,
"unit": "meses"
},
"id": "WARRANTY_TIME",
"name": "Tiempo de garantía",
"value_name": "12 meses",
"value_id": null
},
{
"value_struct": null,
"id": "WARRANTY_TYPE",
"name": "Tipo de garantía",
"value_name": "Garantía de fábrica",
"value_id": "2230279"
}
]
},
{
"item_id": "MLA1150170600",
"site_id": "MLA",
"seller_id": 7654321,
"accepts_mercadopago": true,
"sold_quantity": 1,
"available_quantity": 1,
"price": 493000,
"category_id": "MLA1055",
"currency_id": "ARS",
"warranty": "Garantía de fábrica: 12 meses",
"condition": "new",
"listing_type_id": "gold_special",
"international_delivery_mode": "none",
"tier": "",
"inventory_id": "",
"tags": [...
],
"deal_ids": [],
"official_store_id": null,
"original_price": null,
"shipping": {
...
},
"seller_address": {
...
},
"sale_terms": [
...
]
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
},
{...
}
],
"experiments": null
}Consider that results will return all posts on the product page that are competing to win that product.
Filters
Use filters to decrease the response in the resource /products/$PRODUCT_ID/items This filter works the same as the Search /sites/{site}/search resource where you can use the values of available_filters as a parameter in the URL.
Currently, we offer the following filter options:
| Parameters | Value | Description |
|---|---|---|
| official_store | all | To show only products with winner of Official Stores. |
| official_store_id | id | To show the winner products of an Official Store. |
| discount | 10-100 | To show products with a winner with a discount greater than or equal to 10%. |
| price | 100-200 | For products with winner priced between 100 and 200. Depending on the local currency |
| shipping | fulfillment | For products with winner with Fulfillment. |
| shipping | mercadoenvios | For products with winner without Fulfillment. |
| shipping_cost | free | For products with winner with free shipping. |
| shipping_time | sameday/ nextday | It must be used together with the query param b.buyer_zones which indicates in which areas the buyer is located. |
| seller_id | id | Get the winner user_id |
Example of request using filters:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/MLM123456789/items?shipping_cost=freeNext: Brand Central.