Traditional campaigns

The traditional campaign, known as DEAL, is a type of promotion organized by Mercado Libre, in which invited sellers can offer their products at promotional prices.

Sellers are periodically invited by Mercado Libre to participate in DEAL campaigns. If they accept the invitation, they can include products and define promotional prices within the parameters established by the platform.

Query campaign details

To get the details of a DEAL type offer, use the following endpoint:

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB1806019?promotion_type=DEAL&app_version=v2

Response:

{
  "id": "P-MLB1806019",
  "type": "DEAL",
  "status": "started",
  "start_date": "2023-04-20T03:00:00Z",
  "finish_date": "2023-08-01T02:00:00Z",
  "deadline_date": "2023-08-01T01:00:00Z",
  "name": "HOTSALE"
}

Statuses

These are the different statuses that a traditional campaign can go through.

Query campaign items

To find out which items are part of a traditional campaign, use the following endpoint

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB1806019/items?promotion_type=DEAL&app_version=v2'

Response:

{
  "results": [
      {
          "id": "MLB3538191898",
          "status": "candidate",
          "price": 0,
          "original_price": 5000,
          "max_discounted_price": 4800,
          "suggested_discounted_price": 4150,
          "min_discounted_price": 1600,
          "start_date": "2024-11-27T00:00:00",
          "end_date": "2024-12-05T00:00:00",
          "sub_type": "FLEXIBLE_PERCENTAGE"
   },
      {
          "id": "MLB3538191900",
          "status": "started",
          "price": 1000,
          "original_price": 1500,
          "max_discounted_price": 1300,
          "suggested_discounted_price": 1200,
          "min_discounted_price": 1000,
          "start_date": "2024-12-01T00:00:00",
          "end_date": "2024-12-10T00:00:00",
          "sub_type": "FIXED_AMOUNT",
          "top_deal_price": 1100,
          "discount_percentage": 33.33,
          "currency": "BRL"
      },
      {
          "id": "MLB3538191901",
          "status": "pending",
          "price": 0,
          "original_price": 2000,
          "max_discounted_price": 1800,
          "suggested_discounted_price": 1700,
          "min_discounted_price": 1500,
          "start_date": "2024-12-05T00:00:00",
          "end_date": "2024-12-15T00:00:00",
          "sub_type": "FLEXIBLE_PERCENTAGE",
          "currency": "BRL"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 2
  }
}

Parameters

id: item id.
status: item status in the campaign.
price: item price in the campaign.
original_price: item price without discount.
min_discounted_price: minimum price that the seller can set for the item in the campaign. In other words, it is the maximum discount the item can have.
max_discounted_price: Maximum discounted price considered credible.
suggested_discounted_price: Attractive promotional price suggestion. It can be null if there is no reliable suggestion for the item.
top_deal_price: item price for top buyers, with Mercado Puntos level 3 and 6. This field will only appear if the item is active in the campaign and if the seller set a value for it when adding the item to the campaign.

Item statuses

In the following table you can find the possible statuses that items can have within this type of campaign.

Discount Suggestion for Promotions

The Discount Suggestion feature allows sellers to receive automatic promotional price suggestions, in order to increase the competitiveness of their offers. This suggestion considers price history and other internal factors to generate an appropriate discount.

The seller-promotions/promotions resource allows you to obtain information about candidate items for a promotion campaign.

Supported campaign types

• Traditional campaigns
• Individual discount
• Seller campaigns

Add items to a campaign

Once invited to participate in a traditional campaign, you can indicate which products you want to include in it.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
  "top_deal_price":$TOP_DEAL_PRICE
  "promotion_id":"$PROMOTION_ID"
   "deal_price":$DEAL_PRICE,
   "promotion_type":"$PROMOTION_TYPE"
}'
https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
  "deal_price": 4000,
  "top_deal_price": 3000,
  "promotion_id": "P-MLB1806019",
  "promotion_type": "DEAL"
 }' 
https://api.mercadolibre.com/seller-promotions/items/MLB3295112047?app_version=v2

Response:

{
  "price": 4000,
  "top_price": 3000,
  "original_price": 5000
}

Error response:

Error 400: Occurs when the provided deal_price does not meet the requirements for the "Suggested Price".

{
  {
    "message": "Errors: ERROR_CREDIBILITY_DISCOUNTED_PRICE - The discounted price is not credible.",
    "error": "bad_request",
    "status": 400,
    "cause": [
      {
        "error_code": "ERROR_CREDIBILITY_DISCOUNTED_PRICE",
        "error_message": "The discounted price is not credible."

   }
   
}

Parameters

deal_price: item price in the promotion.
top_deal_price: item price for top buyers, with Mercado Puntos level 3 to 6 (this price is optional)
promotion_id: promotion identification.
promotion_type: promotion type (DEAL.)

Modify items

To modify items that are participating in a promotion, perform the following operation:

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
-d'{
   "deal_price":$DEAL_PRICE,
   "top_deal_price":$TOP_DEAL_PRICE,
   "promotion_id":"$PROMOTION_ID"
   "promotion_type":"DEAL"
}'
https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
-d'{
  "deal_price": 3900,
  "top_deal_price": 3000,
  "promotion_id": "P-MLB1806019",
  "promotion_type": "DEAL"
 }'
https://api.mercadolibre.com/seller-promotions/items/MLB3295112047?app_version=v2

Response:

{
  "price": 3900,
  "top_price": 3000,
  "original_price": 5000
}

Delete items

With this resource you can delete the item offer.

Request:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&promotion_id=$PROMOTION_ID&app_version=v2

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLB3295112047?promotion_type=DEAL&promotion_id=P-MLB1806019=&app_version=v2

Response: Status 200 OK

Possible Error Messages

When interacting with the API, it is important to be aware of the error messages that may occur, especially in cases of invalid requests or lack of access. In case of problems, it is recommended to verify access permissions and request parameters, in addition to keeping the authentication token updated.

Next: Co-funded campaigns