Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 08/03/2023

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 day. In addition, we will speak of "the winner" in a unique way, although eventually the seller could be winning in general but not in particular for certain users (for example, if they live very far and they would not get a shipment in the day).

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

Important:
Sellers who share conditions of sale in their products similar to those of the catalog winner, have a visibility part on the product page and their status is "sharing_first_place".

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

Note:
The sharing_first_place status identifies all sellers with the best offer and a level of shared exposure in Catalog.

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