Last update 28/12/2022

Deals

Mercado Libre's commercial team periodically sends sellers invitations to participate in the commercial campaigns that take place in each marketplace.
In this guide, you will learn the easiest and fastest way to submit, edit, delete and get information about deals submitted to a commercial campaign. Keep in mind that only sellers with green reputation can submit deals.



Get available campaigns

To be able to add deals to the products, the seller should know what campaigns the seller was invited to, for doing this you should use the following endpoint.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/users/$USER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/users/$USER_ID

Response:

{
   "results": [
       {
           "id": "MLM1907",
           "type": "DEAL",
           "status": "test",
           "start_date": "2020-01-31T07:59:00Z",
           "finish_date": "2022-11-01T16:59:00Z",
           "deadline_date": "2021-02-01T12:59:00-04:00",
           "name": "Name Deal"
       }
   ],
   "paging": {
       "offset": 0,
       "limit": 0,
       "total": 1
   }
}

Submit a deal to a campaign

For applying to a campaign you should send the item_id and desired price as well as the marketplace user_id of the country in which you want to participate in.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID&user_id=$user_id \
-d '{
	"deal_id": "Where item will be suggest, required for promotion type DEAL",
	"regular_price": "Regular item price before the promotion, required for type DEAL",
	"deal_price": "Item price for the promotion, required for type DEAL",	
	"promotion_type": "Required, options: DEAL|PRICE_DISCOUNT"
}'

The fields regular_price and deal_price should be in US dollars.

Note:
Up to now the field promotion_type only accepts the value “DEAL”.

Example:


curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM831248496?user_id=523132944 \
-d '{   
	"deal_id": "MLM1907",
      "regular_price": 327.65,
      "deal_price": 100,
      "promotion_type": "DEAL"
}'

Response:

{
   "price": 100,
   "original_price": 327.65,
   "currency_id": "USD"
}

The fields price and original_price are in US dollars.


Edit a deal in a campaign

To edit a deal of a certain campaign you should send the deal_id, item_id and desired price as well as the marketplace user_id of the country where the campaign takes place.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X PUT https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID&user_id=$USER_ID \
-d '{
    "deal_id": "Where item will be suggest, required for promotion type DEAL",
	"regular_price": "Regular item price before the promotion, required for type DEAL",
	"deal_price": "Item price for the promotion, required for type DEAL",	
	"promotion_type": "Required, options: DEAL"
}'

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN'  -X PUT https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM831320922?user_id=523132944 \
-d '{
    "deal_id": "MLM1907",
    "regular_price": 327.65,
    "deal_price": 90,
    "promotion_type": "DEAL"
}'

The fields regular_price and deal_price are expressed in US dollars.

Response:

{
   "price": 90,
   "original_price": 327.65
   "currency_id": "USD"
}

The fields price and original_price are expressed in US dollars.


Delete a deal from a campaign

If you wish to remove an item from a campaign, you should send the item_id, the deal_id and the promotion_type. You’ll also need the marketplace user_id of the site where the campaign is active.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X DELETE https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID&promotion_type=$PROMOTION_TYPE&deal_id=$DEAL_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X DELETE https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM831320922?user_id=523132944&promotion_type=DEAL&deal_id=MLM1907

This method just returns an status_code 200 if it was processed as expected.


Get campaigns details

To see the details of a campaign, you should send the marketplace user_id as well as the deal_id you wish to query.

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$DEAL_ID?promotion_type=DEAL&user_id=$USER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/MLM1907?promotion_type=DEAL&user_id=523132944

Response:

{
   "id": "MLM1907",
   "type": "DEAL",
   "status": "started",
   "start_date": "2020-01-31T07:59:00Z",
   "finish_date": "2022-11-01T16:59:00Z",
   "deadline_date": "2021-02-01T16:59:00Z",
   "name": "Name Deal"
}

Get active campaigns on an item

To get the details of campaigns of an item, you should send the marketplace user_id and the item_id.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?auser_id=$USER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM831248496?user_id=523132944

Response:

[
   {
       "id": "MLM1907",
       "type": "DEAL",
       "status": "started",
       "start_date": "2020-01-31T07:59:00Z",
       "finish_date": "2022-11-01T16:59:00Z",
       "deadline_date": "2021-02-01T16:59:00Z",
       "name": "Test Gaby"
   }
]

Get the items included in a campaign

To get all the items included in a campaign, you should send the marketplace useer_id and the deal_id.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$DEAL_ID/items?user_id=$USER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/MLM1907/items?user_id=523132944

Response:

{
   "results": [
       {
           "id": "MLM831246926",
           "status": "rejected",
           "price": 5.68,
           "original_price": 15.13,
           "currency_id": "USD"
       },
       {
           "id": "MLM831248496",
           "status": "pending_approval",
           "price": 100,
           "original_price": 327.65,
           "currency_id": "USD"
       },
       {
           "id": "MLM831320922",
           "status": "rejected",
           "price": 90,
           "original_price": 327.65,
           "currency_id": "USD"
       }
   ],
   "paging": {
       "offset": 0,
       "limit": 50,
       "total": 3
   }
}

The fields price and oringinal_price are expressed in US dollars.