Last update 23/08/2022

Catalog competition

In catalog, publications compete for the sales of the product page and an algorithm determines who will be the winner of those sales based on characteristics of the publication and the seller itself, such as Price, interest-free fees, full shipping, free shipping or in the same day.

Notification for change of competition status

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.


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.


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 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/MLA1142208727/price_to_win?siteId=MLA&version=v2

Response 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/MLA930793214/price_to_win?siteId=MLA&version=v2

Response 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/MLA1150170600/price_to_win?siteId=MLA&version=v2

Response with "status": "sharing_first_place":

{
   "item_id": "MLA1150170600",
   "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": "MLA18494233",
   "winner": {
       "item_id": "MLA1110011006",
       "price": 492499,
       "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 https://api.mercadolibre.com/items/MLA1146313673/price_to_win?access_token=$ACCESS_TOKEN

Response:

{
   "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"
           }
       ]
   }
}

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

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

      reason: reason why the item is not competing. Possible values are:

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

      catalog_product_id: the ID of the product page to which the publication belongs.
      winner: the detail of the product that is currently the winner, allowing a quick comparison with the item_id of the publication that is being consulted, showing fields like: "item_id", "price", "currency_id" and "boosts".


      Which publication is winning

      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 vendors) 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/items

      Example:

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

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


      Filtering

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

      Next: Special highlight "Recommended".