Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 30/01/2024

Campaigns with automated co-participation (Smart) and competitive pricing campaign (Price Matching)

Sellers are regularly invited to participate in different website campaigns.
The main characteristic of this type of campaign is that Mercado Libre pays a percentage of the offered discount.
Automated co-participation campaigns are similar to those with co-participation, but already use an automated process to define the items that will be invited to participate in the discount. Competitive pricing campaigns, on the other hand, aim to achieve the best prices compared to other websites and marketplaces, and the candidates are regenerated every day, so an item can be a candidate for this type of campaign today and not tomorrow.
If the seller has received an invitation and wants to participate, you can do so with the following resources.

View campaign details

Note:
For both campaigns, the responses have the same fields, changing only the "type" information (SMART or PRICE_MATCHING).

For promotions details, perform the query below::

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

Automated co-participation example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13765128?user_id=1317418851&promotion_type=SMART' \
  --header 'x-client-id: 1317417907' \
  --header 'x-caller-id: 1317417907' \
  --header 'version: v2' \

Automated co-participation response:

{
  "id": "P-MLM13765128",
  "type": "SMART",
  "status": "started",
  "start_date": "2024-01-18T18:00:00Z",
  "finish_date": "2024-02-01T18:00:00Z",
  "deadline_date": "2024-02-01T18:00:00Z",
  "name": "Suggested offers"
}

Competitive pricing example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  
  'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13637333?user_id=1317418851&promotion_type=PRICE_MATCHING'\
  --header 'x-client-id: 1317417907' \
  --header 'x-caller-id: 1317417907' \
  --header 'version: v2' \

Competitive pricing example:

{
  "id": "P-MLM13637333",
  "type": "PRICE_MATCHING",
  "status": "started",
  "start_date": "2024-01-22T18:00:00Z",
  "finish_date": "2024-01-29T18:00:00Z",
  "deadline_date": "2024-01-29T18:00:00Z",
  "name": "Beat the competition with a contribution from Mercado Libre"
}

Response fields

  • id: campaign ID.
  • type: campaign type (SMART or PRICE_MATCHING).
  • status: campaign status.
  • start_date: date when the campaign starts.
  • finish_date: date in which the campaign ends.
  • deadline_date: deadline for creating the campaign.
  • name: name of the campaign.


Status

Find below the different automated co-participation and competitive pricing campaign status:

Status Description
pending Promotion approved but not yet started.
started Active promotion.
finished Finished promotion.


View campaign items

Perform the query below to see candidate items and/or the items included in a campaign:

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

Automated co-participatio example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13765128/items?user_id=1317418851&promotion_type=SMART' \
  --header 'x-client-id: 1317417907'\
  --header 'x-caller-id: 1317417907'\
  --header 'version: v2' \

Automated co-participatio response:

{
  "results": [
    {
          "id": "MLM2183927322",
          "status": "candidate",
          "price": 50,
          "original_price": 0,
          "currency_id": "USD",
          "offer_id": "CANDIDATE-MLM2183927322-70470900567",
          "meli_percentage": 2,
          "seller_percentage": 8,
          "start_date": "2024-01-18T18:00:00Z",
          "end_date": "2024-02-01T18:00:00Z"
      }


  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 1,
      "searchAfter": ""
  }
}

Competitive pricin example:

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

Competitive pricing response:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  
  'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13637333?/items?user_id=1317418851&promotion_type=PRICE_MATCHING'\
  --header 'x-client-id: 1317417907' \
  --header 'x-caller-id: 1317417907' \
  --header 'version: v2' \

Competitive pricing response:

{
   "results": [
       {
           "id": "MLM2045828002",
           "status": "candidate",
           "price": 50,
           "original_price": 0,
           "currency_id": "USD",
           "offer_id": "CANDIDATE-MLM2045828002-70313533801",
           "meli_percentage": 5,
           "seller_percentage": 5,
           "start_date": "2023-12-01T06:00:00Z",
           "end_date": "2023-12-31T23:00:00Z"
       }
   ],
   "paging": {
       "offset": 0,
       "limit": 50,
       "total": 1
   }
}

When a new campaign is created, all applicable items are selected. The initial item (status) is a candidate with no assigned offer_id. When the seller adds an item to the campaign, item status changes to started and a unique offer_id is assigned.



Items-status

The following table shows the possible item status in these types of campaigns.

Status Description
candidate Candidate item to participate in the promotion.
pending Approved and programmed promotion item.
started Campaign active item.
finished Item deleted from campaign.


Indicate items for a campaign

Note:
The automated co-participation campaign can have a time limit of 30 days, while the Price Matching campaign can have a time limit of up to 10 days.

Once you are invited to participate in one of these campaigns, you can specify the products to be included.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID
  -d '{
     "promotion_id":"$PROMOTIONDEAL_ID",
     "promotion_type":"$PROMOTION_TYPE",
     "offer_id":"$OFFER_ID"
  }'

Automated co-participation example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'  
  'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2183927322?user_id=1317418851' \
  --header 'x-client-id: 1317417907' \
  --header 'x-caller-id: 1317417907' \
  --header 'version: v2' \
  -data '{
   "promotion_id": "P-MLM13765128",
   "promotion_type": "SMART",
   "offer_id": "CANDIDATE-MLM2183927322-70470900567"
  }
  '

Automated co-participation response:

{
  "price": 45,
  "original_price": 50,
  "currency_id": "USD",
  "offer_id": "OFFER-MLM2183927322-10176551135"
}

Competitive pricing example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
  'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2045828002?user_id=1317418851' \
  --header 'x-client-id: 1317417907' \
  --header 'x-caller-id: 1317417907' \
  --header 'version: v2' \
  -data '{
   "promotion_id": "P-MLM13637333",
   "promotion_type": "PRICE_MATCHING",
   "offer_id": "CANDIDATE-MLM2045828002-70470900888"
  }
  '

Competitive pricing response:

{
  "price": 45,
  "original_price": 50,
  "currency_id": "USD",
 "offer_id": "OFFER-MLM2045828002-10000001972",
}

Parameters

  • promotion_id: identification of the promotion
  • promotion_type: type of promotion (SMART or PRICE_MATCHING).
  • offer_id: iidentification of the agreed offer.

Delete a campaign

Request:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID&promotion_type=$PROMOTION_TYPE&promotion_id=$PROMOTION_ID&offer_id=$OFFER_ID
  --header 'X-Caller-Id: \
  --header 'version: v2' \
  --header 'X-Client-Id: \

Automated co-participation example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2183927322?promotion_type=SMART&promotion_id=P-MLM13765128&offer_id=OFFER-MLM2183927322-10176551135
  --header 'X-Caller-Id: 1317417907' \
  --header 'X-Client-Id: 1317417907' \
  --header 'version: v2' \

Response: Status 200 OK

Competitive pricing example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2045828002?promotion_type=PRICE_MATCHING&promotion_id=P-MLM13637333&offer_id=OFFER-MLM2045828002-10000001972
  --header 'X-Caller-Id: 1317417907' \
  --header 'X-Client-Id: 1317417907' \
  --header 'version: v2' \

Response: Status 200 OK