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:

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.
  • To make a call to this API, you will need an access 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.

Example:

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

Response:

{
  "paging": {
    "total": 2,
    "offset": 0,
    "limit": 0
  },
  "filters": {
    "site_id": "MLA"
  },
  "results": [
    {
      "id": "MLA90",
      "name": "pruebaIntegracion",
      "description": "Prueba Integracion",
      "site_id": "MLA",
      "status": "test",
      "offers_reception_deadline": "2016-08-30T23:00:00-04:00",
      "start_time": "2016-08-18T03:00:00.000Z",
      "end_time": "2016-08-19T02:59:00.000Z",
      "requisites": [
        {
          "name": "RequisiteDiscount",
          "criteria": "original_price",
          "categories": [
            "MLA1144"
          ],
          "parameters": {
            "value": "20",
            "type": "gold_special"
          },
          "description": "Items with listing gold_special type must have at least 20% off"
        },
        {
          "name": "RequisiteDiscount",
          "criteria": "original_price",
          "categories": [
            "MLA1144"
          ],
          "parameters": {
            "value": "15",
            "type": "gold_premium"
          },
          "description": "Items with listing type gold_premium must have at least 15% off"
        },
        {
          "name": "CATEGORIES_REQUISITE",
          "criteria": "NA",
          "categories": [
            "MLA5726",
            "MLA1276",
            "MLA1384"
          ],
          "parameters": {
          },
          "description": "Items must belong to the specified categories"
        },
        {
          "name": "RequisiteFreeShipping",
          "criteria": "retail_price",
          "categories": [
            "MLA5725"
          ],
          "parameters": {
            "currency": "ARS",
            "value": "500"
          },
          "description": "Items in the specified categories and with price higher than ARS 500 must have free shipping"
        }
      ]
    }
  ]
}

One important field you should pay attention in this response is the field “dead_line”, which indicates up to when you will be able to suggest your products. After that time, you will not be allowed to suggest items for the campaign.
The field “requisites” contains a set of requisites that your proposed items must meet in order to join the campaign. These requisites are defined by Mercado Libre for each 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 (example):

curl -X POST -d '{"item_id":"MLA632979587","deal_price":149,"regular_price":200,"declared_stock":8,"declared_free_shipping":true, "brand":"brand1","model":"model1","declared_oro_premium_full":true}' 'https://api.mercadolibre.com/users/{User_id}/deals/{Deal_id}/proposed_items?access_token=$ACCESS_TOKEN'

Response (example):

{
  "item_id": "MLA633000763",
  "regular_price": 200,
  "deal_price": 149,
  "declared_stock": 8,
  "declared_free_shipping": true,
  "declared_oro_premium_full": true,
  "category_l1": "MLA1953",
  "category_l2": "MLA3530",
  "brand": "brand1",
  "model": "model1",
  "date_created": "2016-08-29T14:08:10.902-04:00",
  "last_updated": "2016-08-29T14:08:10.902-04:00",
  "status": "pending_approval",
  "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
}

Modify a product in a campaign

Request:

curl -X PUT -d '{"deal_price":150}' 'https://api.mercadolibre.com/users/{User_id}/deals/{Deal_id}/proposed_items/{Item_id}?access_token=$ACCESS_TOKEN'

Response (example):

{
  "item_id": "MLA633000763",
  "regular_price": 200,
  "deal_price": 152,
  "declared_stock": 8,
  "declared_free_shipping": true,
  "declared_oro_premium_full": true,
  "category_l1": "MLA1953",
  "category_l2": "MLA3530",
  "brand": "brand1",
  "model": "model1",
  "date_created": "2016-08-29T14:08:11.000-04:00",
  "last_updated": "2016-08-29T14:34:53.662-04:00",
  "status": "pending_approval",
  "title": "Item De Testeo, Por Favor No Ofertar --kc:off"
}

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

Response:

{O
"item_id": "MLA632979587",
"current_price": null,
"regular_price": 200,
"deal_price": 170,
"declared_stock": 8,
"declared_free_shipping": true,
"declared_oro_premium_full": true,
"category_l1": "MLA1953",
"category_l2": "MLA3530",
"brand": "brand1",
"model": "model1",
"date_created": "2016-08-29T11:52:01.000-04:00",
"last_updated": "2017-08-03T16:15:32.344-04:00",
"status": "rejected",
"title": "Item De Testeo, Por Favor No Ofertar --kc:off",
"processed_by": "$user_id",
"source": "public_api",
"discount": 26,
"rejections": [
{
"comment": null,
"requisite_rejection": null,
"reason": [
"El seller quitó al item del deal"
]
}
]
}

Response with status 204.
Note: Bear in mind that the following actions can be performed before the deadline set in offers_reception_deadline. After this date, it can only be performed through your commercial advisor (see the example of Query campaigns to which you have been invited.)

Obtain my products in a campaign

You can obtain the products 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

Response:

{
  "paging": {
    "total": 2,
    "offset": 0,
    "limit": 50
  },
  "filters": {
    "deal_id": "MLA90",
    "seller_id": "210456151"
  },
  "results": [
    {
      "item_id": "MLA632979587",
      "current_price": 170,
      "regular_price": 200,
      "deal_price": 149,
      "declared_stock": 8,
      "declared_free_shipping": true,
      "declared_oro_premium_full": true,
      "category_l1": "MLA1953",
      "category_l2": "MLA3530",
      "brand": "brand1",
      "model": "model1",
      "date_created": "2016-08-29T11:52:01.000-04:00",
      "last_updated": "2016-08-29T11:52:01.000-04:00",
      "status": "pending_approval",
      "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
      "discount": 26
    },
    {
      "item_id": "MLA632632625",
      "current_price": 200,
      "regular_price": null,
      "deal_price": 100,
      "declared_stock": 50,
      "declared_free_shipping": false,
      "declared_oro_premium_full": false,
      "category_l1": "MLA1953",
      "category_l2": "MLA3530",
      "brand": "Prueba",
      "model": "Cool",
      "date_created": "2016-08-26T10:34:04.000-04:00",
      "last_updated": "2016-08-26T10:34:04.000-04:00",
      "status": "pending_approval",
      "title": "Item De Testeo, Por Favor No Ofertar --kc:off",
      "discount": 50
    }
  ]
}

Please rate this