Catalog competition

Receive notifications of posts changing status in competition

With the Item competition topic you can subscribe to start receiving notifications of the change of status of the catalog items, and it will allow you to recognize the item that modifies its competition status to winner or vice versa.

To view competitor information and review the conditions the vendor is competing against to win the product page, you will need to use the /price_to_win resource to understand what actions they should take.

Learn more about how to receive notifications.


How to know the price to win

The catalogue publications compete to achieve the sales of the product page and there is an algorithm which determines who the winner of all those sales will be based on the characteristics of the publication and of the seller.
The algorithm that assesses which publication will be the winner takes into account the following:

  • The publication price
  • Interest-free installments
  • Full delivery, free shipping and same day delivery

Notes:

  • Some of these characteristics may only be applied to some purchasers (for example: same day delivery or discount of Mercado Puntos). In these cases we make the best effort to choose a winner considering the particular purchaser bearing also in mind what characteristics apply to him/her.
  • According to what was previously mentioned, we will talk about the “winner” in an univocal way, the seller could eventually be winning in general but not particularly for certain users (for example, if they live very far and they would never obtain a same day delivery). The resource will identify when an item is competing, is winning or when it is not competing, being able to identify the reasons why it does not compete.

For the sellers to compete efficiently, we offer a resource that indicates which the price is with the one you would win the sales keeping the rest of the conditions unchanged (at this moment deliveries and financing). The resource will allow you to identify if an item is competing, winning or not competing, being able to identify the reasons for not competing.


Request:

curl -X GET https://api.mercadolibre.com/items/$ITEM_ID/price_to_win?access_token=$ACCESS_TOKEN

Example of competing item:

curl -X GET https://api.mercadolibre.com/items/MLB1234/price_to_win?access_token=$ACCESS_TOKEN

Response:

{
    "item_id": "MLA123456789",
    "current_price": 21499.0,
    "currency_id": "ARS",
    "price_to_win": 17600.0,
    "boosts": {
        "fulfillment": false,
        "free_installments": false,
        "free_shipping": true,
        "same_day_shipping": false
    },
    "status": "competing",
    "reason": [],
    "catalog_product_id": "MLA9652755"
}

Example of winning item:

curl -X GET https://api.mercadolibre.com/items/MLB123456710/price_to_win?access_token=$ACCESS_TOKEN

Response:

{
    "item_id": "MLA123456710",
    "current_price": 20499.0,
    "currency_id": "ARS",
    "price_to_win": 20499.0,
    "boosts": {
        "fulfillment": false,
        "free_installments": true,
        "free_shipping": true,
        "same_day_shipping": false
    },
    "status": "winning",
    "reason": [],
    "catalog_product_id": "MLA9652755"
}

How to read the response:

  • The field status indicates whether we are winning for the general public (we could be winning for minority segments such as those who do not benefit from the same day delivery). When we are winning the value is winning, but when we are not it is competing.
  • The field boosts indicates which characteristics of our publication are contributing to our chances of winning. The possibilities are:
    • fulfillment: for publications located in the centre of fulfillment.
    • free_shipping: when the publication offers free shipping.
    • same_day_shipping: in cases that the article can be sent on the same day.
    • free_installments: when interest free installments are offered for the publication.
  • price_to_win indicates what the price is (the present currency of the publication) to be the winner. That is to say that by PUTTING the suggested price in the resource/items you may surely be the winner.
  • reason will show information when the item is not competing, being able to identify the reason why it is not doing so.
  • Possible values ​​for reason

    Reason Description
    non_trusted_seller The celler 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.
    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.

    In this call you will have to use an item_id of a catalogue publication, in case you do not do it you will obtain an error code 4XX.
    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.

    Know the conditions and price of the winning item

    The competition table will allow seller to compare and improve item conditions. With the new version of the resource price_to_win you can add via API a competition table to compare the conditions of an item that is competing and those of the winner. With this functionality in your development, sellers will know what conditions to improve to win the product page.

    Request:

    curl -X GET https://api.mercadolibre.com/items/$ITEM_ID/price_to_win?siteId=$SITE_ID&version=v2?access_token=$ACCESS_TOKEN

    Example:

    curl -X GET https://api.mercadolibre.com/items/MLA123456789/price_to_win?siteId=MLA&version=v2?access_token=$ACCESS_TOKEN

    Response:

    {
        "item_id": "MLA848886211",
        "current_price": 85990,
        "currency_id": "ARS",
        "price_to_win": 65200,
        "boosts": [
            {
                "id": "same_day_shipping",
                "status": "opportunity",
                "description": "Envíos en el dia 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_boosted",
                "description": "Envíos gratis por Mercado Envíos"
            },
            {
                "id": "shipping_quarantine",
                "status": "boosted",
                "description": "Envío con normalidad"
            },
            {
                "id": "shipping_collect",
                "status": "boosted",
                "description": "Mercado Envíos Colecta"
            }
        ],
        "status": "competing",
        "reason": [],
        "catalog_product_id": "MLA14186099",
        "winner": {
            "item_id": "MLA849174940",
            "price": 76999,
            "currency_id": "ARS",
            "boosts": [
                {
                    "id": "same_day_shipping",
                    "status": "not_apply",
                    "description": "Envíos en el dia por Mercado Envíos"
                },
                {
                    "id": "fulfillment",
                    "status": "boosted",
                    "description": "Mercado Envíos Full"
                },
                {
                    "id": "free_installments",
                    "status": "boosted",
                    "description": "Cuotas sin interés"
                },
                {
                    "id": "free_shipping",
                    "status": "not_boosted",
                    "description": "Envíos gratis por Mercado Envíos"
                },
                {
                    "id": "shipping_quarantine",
                    "status": "boosted",
                    "description": "Envío con normalidad"
                },
                {
                    "id": "shipping_collect",
                    "status": "opportunity",
                    "description": "Mercado Envíos Colecta"
                }
            ]
        }
    }

    In the new version of the resource, in addition to the fields already known in the previous version, we add the information of the item that we are consulting and that of the item that is winning (in case the item that is being consulted is competing).

    Therefore, first of all we visualize the price and the conditions of sale listed within boosts, with a status and explanation, allowing us to quickly compare with the second list that refers to the publication that is winning the product page.

    The boosts are those already mentioned in the response fields of the previous version.
    Now, you can recognize the status of these in the boost and draw a comparative 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 will allow you to quickly compare with the second listing about the item publication that is winning the product page.

    Know the publication that is winning a product

    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.


    How to get to know the list of publications for a product

    If you need to know which articles (of all of the sellers) are the ones that compete for the sales of a particular product, you have a resource that provides you with that information.


    Request:

    curl -X GET https://api.mercadolibre.com/products/{product_id}/items

    Example:

    curl -X GET https://api.mercadolibre.com/products/MLB6309815/items

    Simplified 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,
          "installments": {
            "quantity": 1,
            "amount": 13999,
            "rate": 0,
            "currency_id": "ARS"
          },
          "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": [
            "brand_verified",
            "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.
    installments no_interest For products with winner in installments, without interests.
    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 https://api.mercadolibre.com/products/MLB6309815/items?shipping_cost=free
    or register to recieve the latest news about our API