Documentation Mercado Libre

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

Documentation

Last update 15/01/2026

Automated Co-funded Campaigns and Competitive Pricing Campaigns

Important:
The new status filter is now available to filter campaign items using the query param status_item, which accepts the values "active" or "paused".
Important:
- These campaigns are included in the same documentation because they work with the same logic and parameters.
- As of October 14, 2024, competitive pricing campaigns have two types: PRICE_MATCHING and PRICE_MATCHING_MELI_ALL (100% funded by Mercado Libre).
- If the seller wishes to exclude their participation in 100% Mercado Libre competitive pricing campaigns (PRICE_MATCHING_MELI_ALL), they must access Mercado Libre to deactivate this feature. To remove specific items from

Sellers are periodically invited to participate in various campaigns held on the site. In the case of automated co-funded campaigns and competitive pricing campaigns, Mercado Libre assumes a percentage of the discount offered.
Automated co-funded campaigns work similarly to traditional co-funded campaigns, but use an automated process to select items that will be invited to participate. As for competitive pricing campaigns, their objective is to ensure that products reach the best price compared to other websites and marketplaces. Candidates for these campaigns are updated daily, which means that an item may be eligible today, but not necessarily tomorrow.

From now on, competitive pricing campaigns offer two types of promotions:

  • PRICE_MATCHING: The discount is co-funded between the seller and Mercado Libre.
  • PRICE_MATCHING_MELI_ALL: The discount is 100% funded by Mercado Libre, and the seller's participation is managed automatically, without any action required on their part.

This structure provides greater flexibility in implementing discounts, adapting to the characteristics of each campaign. If the seller has received an invitation and wants to join, they can do so with the following resources.



Query campaign details

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

To get the details of a promotion, make the following request:

Automated co-funded example:

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

Automated co-funded response:

{
  "id": "P-MLB1812010",
  "type": "SMART",
  "status": "started",
  "start_date": "2023-04-26T23:00:00Z",
  "finish_date": "2023-05-10T23:59:00Z",
  "deadline_date": "2023-05-10T23:59:00Z",
  "name": "test-smart-2"
}

Co-funded competitive pricing example:

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

Co-funded competitive pricing response:

{
  "id": "P-MLB2087012",
  "type": "PRICE_MATCHING",
  "status": "pending",
  "start_date": "2023-09-19T18:15:00Z",
  "finish_date": "2023-10-01T05:59:59Z",
  "deadline_date": "2023-10-01T05:59:59Z",
  "name": "Beat the competition with a contribution from Mercado Libre"
}

100% Mercado Libre competitive pricing example:

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

100% Mercado Libre competitive pricing response:

{
    "id": "P-MLB3528002",
    "type": "PRICE_MATCHING_MELI_ALL",
    "status": "started",
    "start_date": "2024-09-26T15:20:04Z",
    "finish_date": "2024-10-01T15:18:04Z",
    "deadline_date": "2024-10-01T15:18:04Z",
    "name": "100% funded by Mercado Libre"
}

Response fields

  • id: campaign identifier.
  • type: campaign type (SMART, PRICE_MATCHING or PRICE_MATCHING_MELI_ALL).
  • status: campaign status.
  • start_date: campaign start date.
  • finish_date: campaign end date.
  • deadline_date: deadline to create the campaign.
  • name: campaign name.


Statuses

These are the different statuses that automated co-funded and competitive pricing campaigns can go through.

Status Description
pending Approved promotion, but not yet started.
started Active promotion.
finished Finished promotion.


Query items in a campaign

To find out which items are part of a campaign, you can make the following request:

Automated co-funded example:

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

Automated co-funded response:

{
  "results": [
      {
          "id": "MLB3538191898",
          "status": "candidate",
          "price": 3000,
          "original_price": 5000,
          "offer_id": "CANDIDATE-MLB3538191898-25593903",
          "meli_percentage": 20,
          "seller_percentage": 20,
          "start_date": "2023-04-26T11:40:00Z",
          "end_date": "2023-05-30T15:47:00Z"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 1
  }
}

Co-funded competitive pricing 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'

Co-funded competitive pricing response:

{
   "results": [
       {
           "id": "MLB4048719074",
           "status": "candidate",
           "price": 3000,
           "original_price": 5000,
           "offer_id": "CANDIDATE-MLB4048719074-70000001705",
           "meli_percentage": 20,
           "seller_percentage": 20,
           "start_date": "2023-09-19T03:00:00Z",
           "end_date": "2023-09-26T02:59:59Z"
       }
   ],
   "paging": {
       "total": 1,
       "limit": 50
   }
}

100% Mercado Libre competitive pricing example:

Note:
For this type of campaign, a "candidate" status will not be displayed, since the activation process is automatically executed by Mercado Libre. When the campaign is shown to the seller, it indicates that the items have already been automatically activated in the campaign. 
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions//P-MLB3528002/items?promotion_type=PRICE_MATCHING_MELI_ALL&app_version=v2''

100% Mercado Libre competitive pricing response:

{
    "results": [
        {
            "id": "MLB3845318745",
            "status": "started",
            "price": 121.5,
            "original_price": 135,
            "offer_id": "OFFER-MLB3845318745-10000115845",
            "meli_percentage": 10,
            "seller_percentage": 0,
            "start_date": "2024-09-26T15:24:35Z",
            "end_date": "2024-09-28T23:59:59Z"
        }
    ],
    "paging": {
        "total": 1,
        "limit": 50
    }
}

When a new SMART and PRICE_MATCHING type campaign is created, all applicable items are selected. The initial item status is candidate and without an assigned offer id. When the seller adds an item to the campaign, its status is modified and a unique offer_id is assigned.



Item statuses

In the following table you can find the possible statuses that items can have within these types of campaigns.

Status Description
candidate Candidate item to participate in the promotion.
pending Item with approved and scheduled promotion.
started Item active in the campaign.
finished Item removed from the campaign


Add items to a campaign

Note:
Automated co-funded campaigns can have a maximum duration of 30 days, while competitive pricing campaigns can have up to 10 days.

Once you have been invited to participate in one of these campaigns, you can indicate which products you want to include in them.

Request:

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

Automated co-funded example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
    "promotion_id":"P-MLB1812010",
    "promotion_type":"SMART",
    "offer_id":"CANDIDATE-MLB3538191898-25593903"
  }
  '
  https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

Automated co-funded response:

{
  "offer_id": "OFFER-MLB3538191898-177685",
  "price": 3000,
  "original_price": 5000
}

Competitive pricing example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
     "promotion_id": "P-MLB2087012",
     "offer_id": "CANDIDATE-MLB4048719074-70000001705",
     "promotion_type": "PRICE_MATCHING"
  }
  '
  https://api.mercadolibre.com/seller-promotions/items/MLB4048719074?app_version=v2

Competitive pricing response:

{
    "offer_id": "OFFER-MLB4048719074-10000001972",
    "price": 3000,
    "original_price": 5000
 }

Parameters

  • promotion_id: promotion identifier.
  • promotion_type: promotion type (SMART or PRICE_MATCHING).
  • offer_id: agreed offer identifier.

Delete campaign

Request:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&promotiondeal_id=$PROMOTION&offer_id=$OFFER_ID'

Automated co-funded example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?promotion_type=SMART&promotion_id=P-MLB1812010&offer_id=OFFER-MLB3538191898-177685&app_version=v2

Response: Status 200 OK

Co-funded competitive pricing example:

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

Response: Status 200 OK

100% Mercado Libre competitive pricing example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLA1387793467?promotion_type=PRICE_MATCHING_MELI_ALL&promotion_id=P-MLA2072013&offer_id=OFFER-MLA1387793467-1000000151&app_version=v2

Response: Status 200 OK