Documentation Mercado Libre
Check out all the necessary information about APIs Mercado Libre.Documentation
Catalog competition
Publications competing notification
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 or vice versa. To view the competitor information and review the conditions under which the seller is competing to win the product page, use the /price_to_win resource to find out what actions to take.
Conditions and price of the winning item
With the resource /price_to_win?siteId=$SITE_ID&version=v2 you recognize the status of the catalog publication: it may be winning, sharing first, losing or listed. The latter means that you have reasons why the post is not competing.
You can also build a competition table to compare the conditions of the items and improve them based on the competition. With this functionality in your development, sellers will know what conditions to improve to win the product page.
Item missing example
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/price_to_win?siteId=$SITE_ID&version=v2
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456789/price_to_win?siteId=MLA&version=v2
Response:
{
"item_id": "MLA901414479",
"current_price": 12999,
"currency_id": "ARS",
"price_to_win": 11500,
"boosts": [
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
},
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "not_apply",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
}
],
"status": "competing",
"competitors_sharing_first_place": "null",
"visit_share": "minimum",
"consistent": true,
"reason": [],
"catalog_product_id": "MLA16107499",
"winner": {
"item_id": "MLA884484295",
"price": 13499,
"currency_id": "ARS",
"boosts": [
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
},
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "boosted",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "not_apply",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
}
]
}
}
Item winning example
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/price_to_win?siteId=$SITE_ID&version=v2
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456789/price_to_win?siteId=MLA&version=v2
Response:
{
"item_id": "MLA884484295",
"current_price": 13499,
"currency_id": "ARS",
"price_to_win": 13499,
"boosts": [
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
},
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "boosted",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "not_apply",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
}
],
"status": "winning",
"competitors_sharing_first_place": "0",
"visit_share": "maximum",
"consistent": true,
"reason": [],
"catalog_product_id": "MLA16107499",
"winner": {
"item_id": "MLA884484295",
"price": 13499,
"currency_id": "ARS",
"boosts": [
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
},
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "boosted",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "not_apply",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
}
]
}
}
Item sharing first place example
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456710/price_to_win?siteId=MLA&version=v2
Response:
{
"item_id": "MLA901414479",
"current_price": 12999,
"currency_id": "ARS",
"price_to_win": 11500,
"boosts": [
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
},
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "not_apply",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
}
],
"status": "sharing_first_place",
"competitors_sharing_first_place": "2",
"visit_share": "medium",
"consistent": true,
"reason": [],
"catalog_product_id": "MLA16107499",
"winner": {
"item_id": "MLA884484295",
"price": 13499,
"currency_id": "ARS",
"boosts": [
{
"id": "same_day_shipping",
"status": "boosted",
"description": "Envíos en el día por Mercado Envíos"
},
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "boosted",
"description": "Cuotas sin interés"
},
{
"id": "free_shipping",
"status": "not_apply",
"description": "Envíos gratis por Mercado Envíos"
},
{
"id": "shipping_collect",
"status": "boosted",
"description": "Mercado Envíos Colecta"
}
]
}
}
Item not competing example
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456710/price_to_win?siteId=MLA&version=v2
Response:
{
"item_id":"MLA123456710",
"current_price":68000,
"currency_id":"ARS",
"price_to_win":null,
"boosts":{
"same_day_shipping":false,
"fulfillment":false,
"free_installments":false,
"free_shipping":true,
"cross_docking":false,
"drop_off":true,
"shipping_quarantine":false
},
"status":"listed",
"competitors_sharing_first_place": null,
"visit_share": "minimum",
"reason":[
"item_paused"
]
}
Response fields
price_to_win: price in the current currency of the publication to be the winner, that is, request PUT to the /items resource with the suggested price, the publication will win the product page.
boosts: characteristics of the publication that provide chances of winning, such as:
- same_day_shipping: shipping on day with Mercado Envios.
- fulfillment: Mercado Envios Full.
- free_installments: interest-free fees.
- free_shipping: free Shipping with Mercado Envios.
- shipping_quarantine: shipping normally.
- shipping_collect: Mercado Envios Colecta.
- Winning: will be 0, so being the winner takes all the sales and visibility in the catalog.
- Competing: will be null, so when losing it has to improve the conditions to share the first place or to win.
- Listed: will be null, so when losing it has to improve the conditions to share the first place or to win.
- Sharing_first_place: number of sellers competing for first place.
- Winning: will always be maximum.
- Competing: will always be minimum.
- Sharing_first_place: always will be medium.
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: indicates whether the product is winning for the public or for minority segments such as those who do not take advantage of 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 and they are divided among all those who share the first place according to your conditions the levels of visibility on the product page.
competitors_sharing_first_place sellers quantity who share the first place. It will also depend on the states:
visit_share: visibility level on the catalog publication. The values may vary depending on the states:
reason: It will display information only when the publication is not competing, allowing you to identify the reason why it is not competing and thus take improvement actions.
In this request you will have to use an item_id of a catalog publication. If not, you will receive an 4XX error code. Moreover, there are variables such as the reputation that are used to determine the winner. However, for a good seller, the variables used to determine the winner will be the previous ones.
Reasons
There are different reasons why a publication is not competing within the catalog, below we list all the possible reasons that the endpoint de 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 is not in the whitelist of fraud. It cannot compete. It appears at the end in the listings. |
reputation_below_threshold | The seller does not reach the minimum reputation to win. It cannot compete. It only appears in the listings. |
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 item has manufacturing time, only appears in the listings and cannot win because the winner has immediate stock. |
temporarily_winning_manufacturing_time | The item has manufacturing time, it is temporarily winning because there are no competitors in the same reputation level without MF. |
temporarily_competing_manufacturing_time | The item has manufacturing time, it is competing temporarily because there are no competitors at the same reputation level without MF, the winner also has MF. |
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 it is the best reputation available, it is competing temporarily. The winner is also of the same reputation. If a best seller appears, it is only listed again. |
item_paused | The item is paused, it cannot be listed. |
item_not_opted_in | The item has not opted in, cannot be listed or is a test item. |
shipping mmode | Only available for MLB. Seller is not competing because their shipping method is inferior to the winner. ME2 > ME1 > Custom Shipping > Not Specified. |
Winning publication
Using the /products/$PRODUCT_ID resource, in addition to knowing the characteristics and status of the product, you can recognize the publication that is winning the product page using the buy_box_winner field.
Consult the list of publications for a product
If you need to know which seller´s products are the ones that compete for the sales of a particular product, make this request:
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/$PRODUCT_ID/items
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/MLB6309815/items
Short response:
{
"paging": {
"total": 7,
"offset": 0,
"limit": 100
},
"results": [
{
"item_id": "MLA824759321",
"category_id": "MLA1055",
"seller_id": 90205574,
"price": 13999,
"currency_id": "ARS",
"sold_quantity": 0,
"available_quantity": 1,
"shipping": {
"mode": "me2",
"tags": [
"mandatory_free_shipping"
],
"free_shipping": true,
"logistic_type": "fulfillment",
"store_pick_up": false
},
"warranty": "Garantía de fábrica: 1 años",
"condition": "new",
"sale_terms": [
{
"id": "INVOICE",
"name": "Facturación",
"value_id": "6891885",
"value_name": "Factura A",
"value_struct": null
},
{
"id": "WARRANTY_TYPE",
"name": "Tipo de garantía",
"value_id": "2230279",
"value_name": "Garantía de fábrica",
"value_struct": null
},
{
"id": "WARRANTY_TIME",
"name": "Tiempo de garantía",
"value_id": null,
"value_name": "1 años",
"value_struct": {
"number": 1,
"unit": "años"
}
}
],
"official_store_id": null,
"original_price": null,
"listing_type_id": "gold_special",
"accepts_mercadopago": true,
"seller_address": {
"city": {
"id": "TUxBQ0xBWmI3M2Q3",
"name": "Santa Fe"
},
"state": {
"id": "TUxBUFNBTmU5Nzk2",
"name": "Santa Fe"
},
"neighborhood": {
"id": "TUxBQk9UUjQyMjJa",
"name": "Otros Barrios"
}
},
"international_delivery_mode": "none",
"tags": [
"extended_warranty_eligible",
"good_quality_picture",
"good_quality_thumbnail",
"immediate_payment",
"cart_eligible"
],
"tier": ""
},
{},
{},
{},
{},
{},
{}
]
}
Take into account that “results” will give the items that are competing to win this product.
Filtering
This filtering will work in exactly the same way as in the resource of Search (/sites/{site}/search) where it is possible to use the values of available_filters as a parameter in the URL:
You currently have the following filtering 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. *100 for products with winner with a price greater than or equal to 100. *200 for products with winner with a price less than or equal to 200. |
shipping | fulfillment | For products with winner with FBM. |
shipping | mercadoenvios | For products with winner without FBM. |
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:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/MLB6309815/items?shipping_cost=free