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.

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.

Note:
This information allows you to quickly compare with the second listing on the publication of the item that is winning the product page.

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:

• 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.

visit_share: visibility level on the catalog publication. The values may vary depending on the states:

• Winning: will always be maximum.
• Competing: will always be minimum.
• Sharing_first_place: always will be medium.

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