Documentación Mercado Libre

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

Documentación

Última actualización 11/07/2024

Campaigns with automated co-participation and competitive pricing campaign

Important:
- We've changed the name from "Smart campaign" to "campaign with automated co-participation", but we haven't changed anything in the API and it still has the "type" smart.
- These campaigns are in the same documentation because they work with the same logic and the same parameters.

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 the automated co-participation campaign (SMART) we no longer send the sub_type information.

For promotion details, perform the query below:

Automated co-participation 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-participation 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"
}

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
  

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": "Gánale a la competencia con un aporte de Mercado Libre"
}

Fields response

  • id: campaign ID.
  • type: campaign type (SMART, 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: campaign name.


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:

Automated co-participatio 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-participatio 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
  }
}

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 pricin 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
  }
}

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' \
  -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-participation 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-participation 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 identification
  • promotion_type: promotion type(SMART or PRICE_MATCHING).
  • offer_id: identification of the agreed offer.

Delete a 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-participation 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

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