Deals

Sellers who receive advice from Mercado Libre's sales team are regularly invited to participate in different deals campaigns that take place during the year in our website. If you have received an invitation for one of this campaigns and you want to join, follow this tutorial to learn the basic of how to suggest your products.

Contents

→Consult the campaigns you were invited to
→Propose a product for a campaign
→Modify a product in a campaign
→Remove a product from a campaign
→Reactivate a product removed from a campaign
→Get products proposed for a campaign
→Get information about a specific campaign

Important:
- For testing purposes, a test user must be used. This guarantees that you will always have a deal (campaign) available for proposing ítems. Campaigns for an item will never be approved in test, they will remain in pending_approval status, that is, the sale price will not be shown.
- Para acessar essa API, você precisa de um acess_token.

Consult the campaigns you were invited to

This resource retrieves the deals campaigns associated to a user_id. There can be more than one per user.

Request:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/deals/search?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/users/443033562/deals/search?access_token=$ACCESS_TOKEN

Response:

{
   "paging":{
      "total":50,
      "offset":0,
      "limit":0
   },
   "filters":{
      "seller_id":443033562
   },
   "results":[
      {
         "id":"MLA480",
         "name":"refrigeracion 18-oldVersion",
         "description":"¡No te pierdas el especial de #Refrigeración en #MercadoLibre! #Aires #Heladeras y #Freezers",
         "site_id":"MLA",
         "status":"inactive",
         "offers_reception_deadline":"2018-02-14T19:00:00.000-04:00",
         "start_time":"2018-02-06T03:00:00.000Z",
         "end_time":"2018-02-15T02:59:00.000Z",
         "requisites":[
            {
               "name":"CATEGORIES_REQUISITE",
               "criteria":"NA",
               "categories":[
                  "MLA5726"
               ],
               "parameters":{

               },
               "description":"Items must belong to the specified categories"
            }
         ],
         "parameters":{
            "has_discounts":true,
            "general_req_config":"ENABLED",
            "freeze_prices":false,
            "free_shipping":false
         },
         "exhibitors":[
            {
               "id":8897,
               "deal":{
                  "id":1876
               },
               "description":"¡No te pierdas el especial de #Refrigeración en #MercadoLibre! #Aires #Heladeras y #Freezers",
               "dt_end_time":"2017-12-31T22:59:00.000-04:00",
               "dt_start_time":"2017-12-26T08:00:00.000-04:00",
               "end_time":"2018-01-01T02:59:00.000Z",
               "exhibitor_id":"search_desktop_main_slider",
               "parameters":{
                  "background_image":"https://http2.mlstatic.com/resources/deals/exhibitors_resources/mla-search-desktop-main-slider-background-image-0e3b35d5-f290-437a-b4a0-bd59861f6f55.jpg",
                  "permalink":"http://ofertas.mercadolibre.com.ar/refrigeracion",
                  "deal_id":"MLA480",
                  "included_categories_ids":[
                     "MLA1051",
                     "MLA5726",
                     "MLA1000",
                     "MLA1499",
                     "MLA407134"
                  ]
               },
               "params":[
                  {
                     "id":71620
                  }
               ],
               "site_id":"MLA",
               "start_time":"2017-12-26T12:00:00.000Z"
            },
            {
               "id":8902,
               "deal":{
                  "id":1876
               },
               "description":"¡No te pierdas el especial de #Refrigeración en #MercadoLibre! #Aires #Heladeras y #Freezers",
               "dt_end_time":"2018-02-14T22:59:00.000-04:00",
               "dt_start_time":"2018-02-13T23:00:00.000-04:00",
               "end_time":"2018-02-15T02:59:00.000Z",
               "exhibitor_id":"home_feed_mobile_native_big_banner",
               "parameters":{
                  "header_background_url_landscape_300x":"https://http2.mlstatic.com/resources/deals/exhibitors_resources/mla-home-feed-mobile-native-big-banner-header-background-url-landscape-300x-773ef349-56fd-4d69-847a-8642df88f1fa.jpg"               },
               "params":[
                  {
                     "id":70678
                  }
               ],
               "site_id":"MLA",
               "start_time":"2018-02-14T03:00:00.000Z"
            }
         ]
      }
   ]
}

The important fields that you should remember in this answer are:

  • offers_reception_deadline: indicate how long you can suggest your products. After this period, you will not be able to suggest products for the campaign.
  • requisites: it is a set of requirements that your suggested articles must meet in order to be included in the campaign. These requirements are defined by Mercado Libre for each campaign.
  • freeze_prices: It is important to know if the campaign has frozen prices, if this field has a "true" you will not be able to modify them while the current campaign.

Propose a product for a campaign

Once you know you have been invited to a deals campaign, you can select which of your products you want to include in the campaign and propose them. You might have to detail the conditions in which your products will participate in the campaign (i.e. discount price for the campaign, stock for the campaign, etc.). Your proposed items have a status associated. At first, this status is "pending_approval". When the commercial team validates the offer, it can be rejected and the status changes to "rejected" (the item is out of the deal), or it can be approved (the item will be in the deal.)

Request:

curl -X POST -d '{
    "item_id":"MLU472482134",
    "deal_price":149,
    "regular_price":200,
    "declared_free_shipping":true,
    "declared_oro_premium_full":true
}' 'https://api.mercadolibre.com/users/$USER_ID/deals/$DEAL_ID/proposed_items?access_token=$ACCESS_TOKEN'

Example:

curl -X POST -d '{
    "item_id":"MLU472482134",
    "deal_price":300,
    "regular_price":350,
    "declared_free_shipping":true,
    "declared_oro_premium_full":true
}' 'https://api.mercadolibre.com/users/443033562/deals/MLA1804/proposed_items?access_token=$ACCESS_TOKEN'

Response:

{
    "item_id": "MLU472482134",
    "current_price": 350,
    "regular_price": 350,
    "deal_price": 300,
    "deal_price_l36": null,
    "declared_stock": null,
    "declared_free_shipping": true,
    "declared_oro_premium_full": true,
    "category_l1": "MLU5725",
    "category_l2": "MLU442519",
    "brand": null,
    "model": null,
    "date_created": "2020-06-02T16:29:50.611-04:00",
    "last_updated": "2020-06-02T16:29:50.611-04:00",
    "status": "pending_approval",
    "title": "Item De Test - No Ofertar",
    "processed_by": "UNDEFINED",
    "source": "deals_sellers_fend",
    "discount": 14,
    "validation_color": "yellow"
}

Modify a product in a campaign

Request:

curl -X PUT -d '{
"deal_price":240
}' 'https://api.mercadolibre.com/users/$USER_ID/deals/$DEAL_ID/proposed_items/$ITEM_ID?access_token=$ACCESS_TOKEN'

Example:

curl -X PUT -d '{
"deal_price":240
}' 'https://api.mercadolibre.com/users/443033562/deals/MLA1804/proposed_items/MLU472482134?access_token=$ACCESS_TOKEN'

Response:

{
    "item_id": "MLU472482134",
    "current_price": 350,
    "regular_price": 350,
    "deal_price": 240,
    "deal_price_l36": null,
    "declared_stock": null,
    "declared_free_shipping": false,
    "declared_oro_premium_full": false,
    "category_l1": "MLU5725",
    "category_l2": "MLU442519",
    "brand": null,
    "model": null,
    "date_created": "2020-06-02T16:29:50.000-04:00",
    "last_updated": "2020-06-02T16:37:18.813-04:00",
    "status": "pending_approval",
    "title": "Item De Test - No Ofertar",
    "processed_by": "UNDEFINED",
    "source": "deals_sellers_fend",
    "discount": 31,
    "validation_color": "yellow"
}

Remove a product from a campaign

Request:

curl -X DELETE https://api.mercadolibre.com/users/$USER_ID/deals/$DEAL_ID/proposed_items/$ITEM_ID?access_token=$ACCESS_TOKEN

Example:

curl -X DELETE https://api.mercadolibre.com/users/443033562/deals/MLA1804/proposed_items/MLA632979587?access_token=$ACCESS_TOKEN

Response:

{
    "item_id": "MLU471811349",
    "current_price": null,
    "regular_price": 1000,
    "deal_price": 800,
    "deal_price_l36": null,
    "declared_stock": null,
    "declared_free_shipping": null,
    "declared_oro_premium_full": false,
    "category_l1": "MLU5725",
    "category_l2": "MLU442519",
    "brand": null,
    "model": null,
    "date_created": "2020-05-08T16:46:00.000-04:00",
    "last_updated": "2020-06-02T17:06:30.091-04:00",
    "status": "rejected",
    "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
    "processed_by": "UNDEFINED",
    "source": "deals_sellers_fend",
    "discount": 20,
    "validation_color": "red",
    "rejections": [
        {
            "comment": null,
            "requisite_rejection": null,
            "reason": [
                "El seller quitó al item del deal"
            ]
        }
    ]
}

The response HTTP status is 200.

Note:
To modify or delete an item, it can be done before the deadline in offers_reception_deadline expires. After this date, it can only be done through your commercial advisor. Look at the example Consult the campaigns to which you have been invited.

Reactivate a product removed from a campaign

To reactivate a product in a campaign that had been removed, it is necessary to make a PUT with the proposed deal:

Request:

curl -X PUT -d '{
    "item_id":"MLU472482134",
    "deal_price":149,
    "regular_price":200,
    "declared_free_shipping":true,
    "declared_oro_premium_full":true
}' 'https://api.mercadolibre.com/users/$USER_ID/deals/$DEAL_ID/proposed_items/$ITEM_ID?access_token=$ACCESS_TOKEN'

Example:

curl -X PUT -d '{
    "item_id":"MLU472482134",
    "deal_price":149,
    "regular_price":200,
    "declared_free_shipping":true,
    "declared_oro_premium_full":true
}' 'https://api.mercadolibre.com/users/443033562/deals/MLA1804/proposed_items/MLU472482134?access_token=$ACCESS_TOKEN'

Response:

{
    "item_id": "MLU472482134",
    "current_price": 350,
    "regular_price": 350,
    "deal_price": 240,
    "deal_price_l36": null,
    "declared_stock": null,
    "declared_free_shipping": false,
    "declared_oro_premium_full": false,
    "category_l1": "MLU5725",
    "category_l2": "MLU442519",
    "brand": null,
    "model": null,
    "date_created": "2020-06-02T16:29:50.000-04:00",
    "last_updated": "2020-06-02T16:37:18.813-04:00",
    "status": "pending_approval",
    "title": "Item De Test - No Ofertar",
    "processed_by": "UNDEFINED",
    "source": "deals_sellers_fend",
    "discount": 31,
    "validation_color": "yellow"
}

Get products proposed for a campaign

You will be able to obtain the products that you have suggested for a campaign.

Request:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/deals/$DEAL_ID/proposed_items/search?access_token=$ACCESS_TOKEN

Example:

curl -X GET https://api.mercadolibre.com/users/210456151/deals/MLA90/proposed_items/search?access_token=$ACCESS_TOKEN

Response:

{   
    "paging": {
        "total": 2,
        "offset": 0,
        "limit": 50
    },
    "filters": {
        "seller_id": "555995008"
    },
    "results": [
        {
            "item_id": "MLU471811349",
            "status": "approved",
            "deal_price": 800,
            "regular_price": 1000,
            "declared_free_shipping": false,
            "declared_oro_premium_full": false,
            "current_price": 800,
            "discount": 20,
            "date_created": "2020-05-08T16:46:00.626-04:00",
            "last_updated": "2020-05-12T11:00:22.44-04:00",
            "title": "ITEM DE TESTEO, POR FAVOR NO OFERTAR --KC:OFF",
            "category_l1": "MLU5725",
            "category_l2": "MLU442519",
            "validation_color": "green",
            "source": "deals_admin",
            "processed_by": "UNDEFINED"
        },
        {
            "item_id": "MLU472482134",
            "status": "pending_approval",
            "deal_price": 240,
            "regular_price": 350,
            "declared_free_shipping": false,
            "declared_oro_premium_full": false,
            "current_price": 350,
            "discount": 31.5,
            "date_created": "2020-06-02T16:29:50.519-04:00",
            "last_updated": "2020-06-02T16:37:18.716-04:00",
            "title": "ITEM DE TEST - NO OFERTAR",
            "category_l1": "MLU5725",
            "category_l2": "MLU442519",
            "validation_color": "yellow",
            "source": "deals_sellers_fend",
            "processed_by": "UNDEFINED",
           
        }
    ]
}
Note:
Remember that the maximum value for limit is 200.

You can also filter this search with the following parameters:

  • category_id (string): to filter by category.
  • loyalty (boolean): only items with loyalty discounts.
  • item_id (string): by item id.
  • status (string): by offer status (approved, pending_approval o rejected).
  • title (string): by the title of the item.
  • free_shipping (string): by true, false, default.
  • opf (string): by true, false, default.
  • last_updated_start_time: date since the last modification of the item in the campaign.
  • last_updated_end_time: date until the last modification of the item in the campaign.
  • processed_by (string): user who processed the load of the item.

The date format is “yyyy-MM-dd’T’HH:mm:ss.SSS’Z’”


Get information about a specific campaign

To get information about a specific campaign, make a GET request with the deal ID. You will get specific data such as the end date, if it has frozen prices and free shipping.

Request:

curl -X GET https://api.mercadolibre.com/deals/$DEAL_ID

Example:

curl -X GET https://api.mercadolibre.com/deals/MLA90

Response:

{
  "teaser_uri": null,
  "landing_hub_uri": null,
  "post_deal_uri": null,
  "exhibitors": [
    {
      "id": 1483,
      "end_time": "2016-10-13T02:59:00.000Z",
      "exhibitor_id": "home_feed_mobile_native_big_banner",
      "description": "Tiempo libre",
      "site_id": "MLA",
      "start_time": "2015-12-17T03:00:00.000Z",
      "parameters": {}
    }
  ],
  "status": "inactive",
  "pre_deal_uri": null,
  "site_id": "MLA",
  "dead_line": "2015-12-17T03:00:00.000Z",
  "type": "without_discounts",
  "id": "MLA90",
  "end_time": "2016-10-13T02:59:00.000Z",
  "description": "Tiempo libre",
  "name": "tiempo libre-oldVersion",
  "start_time": "2015-12-17T03:00:00.000Z",
  "parameters": {
    "free_shipping": false,
    "has_discounts": false,
    "freeze_prices": false
  }
}
or register to recieve the latest news about our API