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 -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/price_to_win

Example of competing item:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB1234/price_to_win

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 -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB123456710/price_to_win

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.

Possible values ​​for reason

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 -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": "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.

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

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:

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/MLB6309815/items?shipping_cost=free