Documentation Mercado Libre

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

Documentation

Last update 26/02/2024

Seller campaigns

Sellers can create their own campaigns through their Mercado Libre account and manage them through the integration. If the seller has created a campaign and wants to manage the candidate items, he can do so with the following resources.


Create a campaign

To create a seller campaign please follow these steps:

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

  {
     "promotion_type": "SELLER_CAMPAIGN",
     "name": "test campana del seller",
     "sub_type": "FIXED_PERCENTAGE",
     "fixed_percentage": 15,
     "loyalty_percentage": 30,
     "start_date": "2023-07-17T00:00:00",
     "finish_date": "2023-07-20T00:00:00"
  }

Request fields

  • promotion_type: type of campaign to create, at the moment only SELLER_CAMPAIGN is allowed.
  • name: campaign name.
  • sub_type: in the case of Seller Campaigns, the sub_types allowed are FIXED_PERCENTAGE and FLEXIBLE_PERCENTAGE.
  • fixed_percentage: only for FIXED_PERCENTAGE (Required).
  • loyalty_percentage: only for FIXED_PERCENTAGE (Optional, discount with loyalty).
  • start_date: campaign start date in local format. The beginning of the day will always be taken as the start time.
  • finish_date: campaign end date in local format. The end of the day will always be taken as the end time.

Fixed_Percentage example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/1317418851
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \

  {
     "promotion_type": "SELLER_CAMPAIGN",
     "name": "test campana del seller 1317418851",
     "sub_type": "FIXED_PERCENTAGE",
     "fixed_percentage": 15,
     "loyalty_percentage": 30,
     "start_date": "2023-09-05T00:00:00",
     "finish_date": "2023-09-20T00:00:00"
  }

Fixed_Percentage example response:

{
  "id": "C-MLM122243",
  "type": "SELLER_CAMPAIGN",
  "name": "test campana del seller 1317418851",
  "sub_type": "FIXED_PERCENTAGE",
  "fixed_percentage": 10,
  "loyalty_percentage": 30,
  "start_date": "2023-09-06T00:00:00",
  "finish_date": "2023-09-20T23:59:59",
  "status": "started"
  }

Flexible_Percentage example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/1317418851
  --header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \
  {
  "promotion_type": "SELLER_CAMPAIGN",
  "name": "test campana del seller 1317418851",
  "sub_type": "FLEXIBLE_PERCENTAGE",
  "start_date": "2023-09-06T00:00:00",
  "finish_date": "2023-09-20T00:00:00"
  }

Flexible_Percentage example response:

{
    "id": "C-MLM122281",
    "type": "SELLER_CAMPAIGN",
    "name": "test campana del seller 1317418851",
    "sub_type": "FLEXIBLE_PERCENTAGE",
    "start_date": "2023-09-06T00:00:00",
    "finish_date": "2023-09-20T23:59:59",
    "status": "started"
}

Update a campaign

All fields can be modified, but only the fields that you wish to modify should be submitted. The only mandatory one is promotion_type, which must always be present. If you want to remove the loyalty discount, you must send remove_loyalty to true.


Request:

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

  {
     "promotion_type": "SELLER_CAMPAIGN",
     "name": "test campana del seller updated",
     "sub_type": "FIXED_PERCENTAGE"
  }
Note:
Take into account that we only send the “name” field because it is the only change that we want to impact. We add the word “updated” at the end of the “name”

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X PUT https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/C-MLM121797?user_id=1317418851
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \
  {
     "promotion_type": "SELLER_CAMPAIGN",
     "name": "test campana del seller 1317418851 FIXED",
     "sub_type": "FIXED_PERCENTAGE"
  }

Response:

{
  "id": "C-MLM122243",
  "type": "SELLER_CAMPAIGN",
  "name": "test campana del seller 1317418851 FIXED",
  "sub_type": "FIXED_PERCENTAGE",
  "fixed_percentage": 10,
  "loyalty_percentage": 30,
  "start_date": "2023-09-06T00:00:00",
  "finish_date": "2023-09-20T23:59:59",
  "status": "started"
}

Delete a campaign

To remove a seller campaign from the seller you must perform the following steps:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X DELETE https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/$PROMOTION_ID?promotion_type=SELLER_CAMPAIGN&user_id

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X DELETE https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/C-MLM121807?promotion_type=SELLER_CAMPAIGN&user_id=1317418851
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \
Note:
that the “C-MLM” number is different that the ones that we create in order to keep the created campaign for the next steps.

Response: Status 200 OK


View campaign details

View the details of the two subtypes of seller campaigns:

  • FIXED_PERCENTAGE - has a fixed discount percentage.
  • FLEXIBLE_PERCENTAGE - has no fixed percentage.

Request:

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

Fixed_Campaign example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/C-MLM122243?promotion_type=SELLER_CAMPAIGN&user_id=1317418851
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \

Fixed Campaign example response:

{
  "id": "C-MLM122243",
  "type": "SELLER_CAMPAIGN",
  "status": "started",
  "start_date": "2023-09-06T06:00:00Z",
  "finish_date": "2023-09-21T05:59:59Z",
  "name": "test campana del seller 1317418851 FIXED",
  "sub_type": "FIXED_PERCENTAGE"
}

Flexible_Campaign example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/C-MLM122281?promotion_type=SELLER_CAMPAIGN&user_id=1317418851
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \

Flexible_Campaign response example:

{
  "id": "C-MLM122281",
  "type": "SELLER_CAMPAIGN",
  "status": "started",
  "start_date": "2023-09-06T06:00:00Z",
  "finish_date": "2023-09-21T05:59:59Z",
  "name": "test campana del seller 1317418851 FLEXIBLE",
  "sub_type": "FLEXIBLE_PERCENTAGE"
}

Response fields

  • id: campaign identifier.
  • type: campaign type (SELLER_CAMPAIGN).
  • sub_type: currently we have two, which are: FIXED_PERCENTAGE and FLEXIBLE_PERCENTAGE.
  • fixed_percentage discount percentage for all buyers.
  • loyalty_percentage discount percentage for the best buyers (levels 3 to 6 of the Mercado Puntos).
  • status: campaign status.
  • start_date: date when the campaign starts.
  • finish_date: date when the campaign ends.
  • name: name of the campaign.


Seller campaing status

These are the different states that a seller's campaign can go through.

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


View items in a campaign

To see the items that are part of a seller campaign, make the following query:

Request:

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

Fixed_Percentage example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/C-MLM122243/items?promotion_type=SELLER_CAMPAIGN&user_id=1317418851
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \

Fixed_Percentage response example:

{
  "results": [
      {
          "id": "MLM2199514002",
          "status": "candidate",
          "price": 70,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184798066",
          "status": "candidate",
          "price": 30,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184785146",
          "status": "candidate",
          "price": 18,
          "original_price": 20,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184694464",
          "status": "candidate",
          "price": 100,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184694462",
          "status": "candidate",
          "price": 90,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184629206",
          "status": "candidate",
          "price": 110,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184629204",
          "status": "candidate",
          "price": 38,
          "original_price": 40,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184616078",
          "status": "candidate",
          "price": 123.5,
          "original_price": 130,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2183927324",
          "status": "candidate",
          "price": 60,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2183927322",
          "status": "candidate",
          "price": 45,
          "original_price": 50,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2183693560",
          "status": "candidate",
          "price": 39.2,
          "original_price": 70,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2172266146",
          "status": "candidate",
          "price": 45,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2132031350",
          "status": "candidate",
          "price": 20.37,
          "original_price": 21.42,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2132031328",
          "status": "candidate",
          "price": 19.2,
          "original_price": 20.4,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2131927804",
          "status": "candidate",
          "price": 16,
          "original_price": 18,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM1886904585",
          "status": "started",
          "price": 13.51,
          "original_price": 15.02,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM1886904569",
          "status": "candidate",
          "price": 25,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 17
  }
}

Fixed_Percentage example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/C-MLM122281/items?promotion_type=SELLER_CAMPAIGN&user_id=1317418851
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \

Fixed_Percentage response example:

{
  "results": [
      {
          "id": "MLM2199514002",
          "status": "candidate",
          "price": 70,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184798066",
          "status": "candidate",
          "price": 30,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184785146",
          "status": "candidate",
          "price": 18,
          "original_price": 20,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184694464",
          "status": "candidate",
          "price": 100,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184694462",
          "status": "candidate",
          "price": 90,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184629206",
          "status": "candidate",
          "price": 110,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184629204",
          "status": "candidate",
          "price": 38,
          "original_price": 40,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2184616078",
          "status": "candidate",
          "price": 123.5,
          "original_price": 130,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2183927324",
          "status": "candidate",
          "price": 60,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2183927322",
          "status": "candidate",
          "price": 45,
          "original_price": 50,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2183693560",
          "status": "candidate",
          "price": 39.2,
          "original_price": 70,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2172266146",
          "status": "candidate",
          "price": 45,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2132031350",
          "status": "candidate",
          "price": 20.37,
          "original_price": 21.42,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2132031328",
          "status": "candidate",
          "price": 19.2,
          "original_price": 20.4,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM2131927804",
          "status": "started",
          "price": 16,
          "original_price": 18,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM1886904585",
          "status": "candidate",
          "price": 13.51,
          "original_price": 15.02,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      },
      {
          "id": "MLM1886904569",
          "status": "candidate",
          "price": 25,
          "original_price": 0,
          "currency_id": "USD",
          "start_date": "2023-09-06T00:00:00",
          "end_date": "2023-09-20T23:59:59"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 17
  }
}

Items status

In the following table you will find the possible status that items in a seller campaign can have:

Status Description
candidate Candidate item to participate in the promotion.
pending Approved item and scheduled promotion.
started Active item in the campaign.
finished Deleted item from the campaign.


Indicate items for a campaign /OPTIN

Once you have created a campaign and items invited to participate in a seller campaign, you can indicate which products you want to include in the campaign.

Note:
This campaign is available on our api version 2, so please when you perform the optin include version = v2 at header.

Request:

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

Fixed_Percentage example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST
  https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM1886904585?user_id=1317418851
  --header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \
  {
     "promotion_id":"C-MLM122243",
     "promotion_type":"SELLER_CAMPAIGN"
  }

Fixed_Percentage response example:

{
  "price": 13.51,
  "original_price": 15.02,
  "currency_id": "USD"
}

Flexible_Percentage example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST
  https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2131927804?user_id=1317418851
  --header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \
  {
      "promotion_id":"C-MLM122281",
      "promotion_type":"SELLER_CAMPAIGN",
      "deal_price": 16,
      "top_deal_price": 12
    }

Flexible_Percentage response example:

{
    "price": 16,
    "original_price": 18,
    "currency_id": "USD"
}

Parameters

  • promotion_id: promotion ID.
  • promotion_type: promotion type (SELLER_CAMPAIGN).
  • deal_price price of the item in the promotion.
  • top_deal_price price of the item for the best buyers, with level 3 to 6 of the Mercado Puntos (it is optional to inform this price).

Delete Seller Campaign /OPTOUT

By performing this action you can indicate which products you want to exclude from a campaign.

Note:
This campaign is available on our api version 2, so please when you perform the optout include version = v2 at header.

Request

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

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' -d https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2184629204?promotion_type=SELLER_CAMPAIGN&promotion_id=C-MLM122243&user_id=1317418851&offer_id=1317418851
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \

Response: Status 200 OK



Validation errors: 400 bad request

Error message Description
The name already exists A seller campaign with the same name already exists.
Invalid sub_type When the sub_type of a SELLER_CAMPAIGN is neither FLEXIBLE_PERCENTAGE nor FIXED_PERCENTAGE.
The percentage is greater than allowed. the maximum percentage allowed is 70.000000 The maximum percentage allowed is 70%. If it is sent, for example, fixed_percentage: 71, it will return this error.
The percentage is less than allowed. the minimum percentage allowed is 10.000000 The percentage is below the allowed.
Fixed_percentage is required If the promotion is of type FIXED_PERCENTAGE, the fixed_percentage field is required.
Invalid promotion type When the promotion_type is invalid.
Start and finish dates must be in local format When the dates sent are not in local format (like the example) or are not sent at all.
Start_date cannot be earlier than today Start_date cannot be earlier than today.
Finish_date cannot be earlier than startdate Finish_date cannot be earlier than start_date.
Maximum period cannot exceed the allowed When the distance between the start and finish date is greater than the allowed one.
The percentage difference between sellerpercentage and loyaltypercentage does not meet the minimum required The difference between the seller_percentage and loyalty_percentage must be greater than or equal to 5%.
Maximum period cannot exceed the allowed When you want to update some date (or both), and the new period between them exceeds the allowed one.
Percentages of a FLEXIBLE PERCENTAGE promotion must be updated per offer An attempt is made to modify a percentage or loyalty percentage to a campaign that is of the flexible_percentage type. Percentages can only be set generally in fixed_percentages. For flexible promotions, the prices of particular offers must be edited.
The start_date field cannot be modified for the current promotion status You cannot change the start date of a promotion in the started state.

Next: Automated co-participation and competitive pricing campaign.