Developers

Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.

Última actualización 07/02/2024

Manage Promotions

Importante:

From January 10, 2024 we will delete the previous version of the /seller-promotions resource.
To get the answer with the new version, send the query param app_version=v2. See the documentation for each campaign for the changes.

Use the /seller-promotions resource to centralize all the available promotion types, such as traditional campaigns (DEAL), Mercado Libre co-funded campaigns (MARKETPLACE_CAMPAIGN), price discounts (PRICE_DISCOUNT), lightning deals (LIGHTNING), deals of the day (DOD), volume discount (VOLUME), and pre-negotiated discount per item (PRE NEGOTIATED). Besides the new types of deals that we will make available.

Promotion Characteristics

Campaign type	Name	Price definition	Price suggestion	Bonus MELI	Stock to participate	Deadline	Approval
Traditional	DEAL	User defines	No	No	No	Yes	Yes
Co-funded campaigns	MARKETPLACE CAMPAIGN	User accepts	No	Yes	No	Yes	No
Volume discount	VOLUME	User accepts	No	Yes	No	Yes	No
Deals of the day	DOD	User accepts	Yes	No	Yes, informative	No	No
Lightning deals	LIGHTNING	User defines	Sim	No	Yes, required	No	No
Pre-negotiated discount per item	PRE_NEGOTIATED	User agree and accepts	No	Yes	Yes	Yes	No
Seller campaign	SELLER_CAMPAIGN	User defines and accepts	No	No	No	Yes	No
Smart campaign	SMART	User accepts	No	Yes	No	Yes	No

Promotion Availability by Country

Site	Traditional campaigns (DEAL)	Co-funded campaigns (MARKETPLACE CAMPAIGN)	Price discounts (PRICE DISCOUNT)	Volume discoun (VOLUME)	Pre-negotiated discount per item (PRE_NEGOTIATED)	Deals of the day (DOD)	Lightning deals (LIGHTNING)
MLA, MLB, MLM, MCO, MLC, MLU, MPE.
MLV

Campaigns available for sellers

Reminder - a user can have more than one and different types of invitations.

Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/6313668461356551933?app_version=v2'

Response:

{
  "results": [
      {
          "id": "P-MLB1806015",
          "type": "MARKETPLACE_CAMPAIGN",
          "status": "started",
          "start_date": "2023-04-20T02:00:00Z",
          "finish_date": "2023-08-01T02:00:00Z",
          "deadline_date": "2023-08-01T01:00:00Z",
          "name": "Campanha de teste v2",
          "benefits": {
              "type": "REBATE",
              "meli_percent": 5,
              "seller_percent": 25
          }
      },
      {
          "id": "P-MLB1806017",
          "type": "VOLUME",
          "status": "started",
          "start_date": "2023-04-20T03:00:00Z",
          "finish_date": "2023-08-01T02:00:00Z",
          "deadline_date": "2023-08-01T01:00:00Z",
          "name": "Leva 3 paga 2",
          "benefits": {
              "type": "VOLUME",
              "meli_percent": 9.9999,
              "seller_percent": 23.3331,
              "name": "3x2",
              "buy_quantity": 3,
              "pay_quantity": 2,
              "item_discount_percent": 33.333
          }
      },
      {
          "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": "deals de teste v2"
      },
      {
          "id": "P-MLB1809008",
          "type": "DEAL",
          "status": "started",
          "start_date": "2023-04-21T21:00:00Z",
          "finish_date": "2023-08-01T02:00:00Z",
          "deadline_date": "2023-08-01T01:00:00Z",
          "name": "Deals de test v2"
      },
      {
          "id": "P-MLB1809009",
          "type": "DEAL",
          "status": "started",
          "start_date": "2023-04-21T23:00:00Z",
          "finish_date": "2023-08-01T02:00:00Z",
          "deadline_date": "2023-08-01T01:00:00Z",
          "name": "campanha de teste"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 5
  }
}

Response fields

id: promotion ID code.
type: promotion type (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, SELLER_CAMPAIGN, SMART).
status: status.
start_date: promotion start date.
finish_date: promotion finish date.
deadline_date: maximum term to add promotional items.
name: promotion name.
deadline_date: maximum time limit for accepting the invitation to participate in the promotion.
benefits: promotion benefit configuration.

Consult candidate items

The /seller-promotions/candidates> resource allows you to identify the items invited to participate in a promotion. Whenever an item obtains the status of candidate in a promotion a notification is sent with the candidate_id, with this resource it is possible to identify the item, the promotion and the status.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID?app_version=v2

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663?app_version=v2

Response:

{    
    "id": "CANDIDATE-MLB1254949426-803130663",    
    "item_id": "MLB1254949426",    
    "promotion_id": "P-MLB4629001",    
    "type": "MARKETPLACE_CAMPAIGN",    
    "status": {        
    "id": "candidate"    
  } 
}

Response fields

id: candidate identification code.

item_id: item associated with the candidate.

promotion_id: promotion id.

type: promotion type (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART).

status: status of the applicant.

Note:

The candidate id is obtained through the notification of the public candidate topic.

Check offers

Use the /seller-promotions/offers resource allows you to identify changes in the offer of an item. All changes are sent by notifications with the offer_id, and it is possible to identify the item, the promotion, and the status.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID?app_version=v2

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792?app_version=v2

Response:

{    
    "id": "OFFER-MLB1970246686-42701792",    
    "item_id": "MLB1970246686",    
    "promotion_id": "P-MLB3329001",    
    "type": "DEAL",    
    "status": {        
    "id": "ACTIVE"    
  } 
}

Response fields

id: Identification code of the offer.
item_id: Item associated with the offer.
promotion_id: Promotion id.
type: type of promotion (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART).
status: status of the offer (programmed, active, e inactive).

Note:

You get the id of the offer through a notification in the public offers.

Promotion details

Perform the following query to access the specific details of traditional campaigns, co-funded campaigns, and volume discounts.

Request:

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

Para obtener más información, acceda a las documentaciones de cada campaña.

Status

Find below the different and possible promotion type statuses:

View promotion items

Note:

In this query the status of the item in the campaign is obtained.

Perform the query below to check the items included in a given promotion:

Request:

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

It is also possible to view items of a:

Filters

You can apply filters by item or status.

Request:

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

Filter example by item:

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

Response:

{
   "results": [
       {
           "id": "MLA604400000",
           "status": "started",
           "price": 23968,
           "original_price": 28549
       }
   ],
   "paging": {...}
}

Example of filter by status started:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' /seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&status=started&app_version=v2

Response:

{
   "results": [
       {
            "id": "MLA639970000",
            "status": "started",
            "price": 4037,
            "original_price": 4427
        },
        {
            "id": "MLA639973333",
            "status": "started",
            "price": 6007,
            "original_price": 6587
        },
],
   "paging": [...]
}

Note:

The status that can be filtered are: started, pending and candidate.

Important:

- The query param to send this value starts to be called search_after and no longer searchAfter. But searchAfter will continue to be accepted for a while.
- The value of search_after will be unified to use only distinct values, eliminating ambiguity.

To perform pagination, you must use the searchAfter parameter.
In the GET response, we return the searchAfter parameter, which will be used to scroll through the results. To do this you must retrieve this ID and make the following request with the query param search_after={search_after}. This ID is a string, so you have to accept the string and use it later in your calls.

Note:

If you do not use the limit parameter, 50 items of the total will be returned by default. You can add a maximum limit of 50.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&app_version=v2&limit=50&search_after={$SEARCH_AFTER}'

Example of pagination:

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

Response:

"results": [
       {
           "id": "MLB2674512266",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674506199",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674506138",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674505931",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674505924",
           "status": "candidate",
           "price": 0,
           "original_price": 0
 
 […]
 
 "paging": {
       "searchAfter": 
       "d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca3b5b55MLB2674512267",
       "limit": 50,
       "total": 14424
   }
}

Considerations

Search_after will be returned on all pages except the last page.
The only way to advance the response (paginate) is through the use of this parameter.
When iterating the results, each request will return the search_after that should be used in the next call.
Always use the search_after that was provided by the request response, since it can change and expire (they have a TTL of 5 minutes).
Backward paging is not possible.

Participate in a Promotion

You can participate in different types of promotions and even offer an item price discount by:

Check Item Promotions

Here you can obtain all the promotions that the item has and the status of the promotions at the moment of the consult.

Request:

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

Example:

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

Resposta:

[
  {
      "type": "PRICE_DISCOUNT",
      "status": "candidate",
      "price": 4000,
      "start_date": "2023-04-26T00:00:00",
      "finish_date": "2023-05-10T00:00:00"
  },
  {
      "type": "DOD",
      "status": "candidate",
      "price": 4000,
      "start_date": "2023-04-28T00:00:00",
      "finish_date": "2023-04-28T23:59:59"
  },
  {
      "id": "P-MLB1817004",
      "type": "MARKETPLACE_CAMPAIGN",
      "status": "pending",
      "start_date": "2023-04-27T23:00:00Z",
      "finish_date": "2023-06-01T02:00:00Z",
      "deadline_date": "2023-06-01T01:00:00Z",
      "name": "Campanha teste 10",
      "benefits": {
          "type": "REBATE",
          "meli_percent": 3,
          "seller_percent": 27
      }
  },
  {
      "id": "MLB1345",
      "type": "DEAL",
      "status": "pending",
      "start_date": "2023-04-27T23:00:00-03:00",
      "finish_date": "2023-05-31T23:00:00-03:00",
      "name": "teste 20"
  },
  {
      "id": "C-MLB300",
      "type": "SELLER_CAMPAIGN",
      "sub_type": "FIXED_PERCENTAGE",
      "status": "started",
      "price": 4250,
      "top_price": 3500,
      "start_date": "2023-04-27T00:00:00",
      "finish_date": "2023-05-05T23:59:59",
      "name": "camp del seller 1"
  },
  {
      "id": "P-MLB1812010",
      "type": "SMART",
      "status": "started",
      "name": "test-smart-2",
      "offers": [
          {
              "id": "OFFER-MLB3538191898-177685",
              "original_price": 5000,
              "new_price": 3000,
              "prime_price": null,
              "status": "active",
              "start_date": "2023-04-26T11:40:00Z",
              "end_date": "2023-05-30T15:47:00Z",
              "benefits": {
                  "type": "REBATE",
                  "meli_percent": 20,
                  "seller_percent": 20
              }
          }
      ]
  },
  {
      "id": "C-MLB302",
      "type": "SELLER_CAMPAIGN",
      "sub_type": "FLEXIBLE_PERCENTAGE",
      "status": "candidate",
      "start_date": "2023-04-27T12:04:00",
      "finish_date": "2023-05-05T00:00:00",
      "name": "camp del seller 2"
  }
]

Modify Items

You can modify items included in a deal by:

Nota:

To edit price discounts (PRICE DISCOUNT), deals of the day (DOD) and lightning deals (LIGHTNING) delete the promotion and apply it again.

Delete Items

You can change the items included in a given deal by:

Test Campaigns

For test campaigns, please send user data and/or items in the following support.
Reminder - both users and items should be test users and items.

Nota:

You must add the version=test parameter inside the calls to interact with the test promotions.

Next Post: Traditional Campaigns

Manage Promotions

Promotion Characteristics

Promotion Availability by Country

Campaigns available for sellers

Response fields

Consult candidate items

Check offers

Response fields

Promotion details

Status

View promotion items

Filters

Pagination

Considerations

Participate in a Promotion

Check Item Promotions

Modify Items

Delete Items

Test Campaigns