Documentation Mercado Libre

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

Documentation

Last update 26/02/2024

Unhealthy Stock Campaign

Sellers are periodically invited to participate in various campaigns that take place on the site. The Unhealthy Stock Campaign is exclusive for fulfillment items. If the seller has received an invitation and wants to join, they can do so using the following resources.

Check details about an unhealthy stock campaign

Request:

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

Example:

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

Response:

{
  "id": "P-MLC13457036",
  "type": "UNHEALTHY_STOCK",
  "status": "started",
  "start_date": "2023-10-02T17:00:00Z",
  "finish_date": "2023-10-16T15:00:00Z",
  "deadline_date": "2023-10-16T15:00:00Z",
  "name": "Acelera tus ventas de stock Full",
  "offers": [
      {
          "id": "",
          "original_price": 30,
          "new_price": 28,
          "status": "active",
          "start_date": "2023-10-05T14:02:52Z",
          "end_date": "",
          "benefits": {
              "type": "REBATE",
              "meli_percent": 0,
              "seller_percent": 6.7
          }
      }
  ]
}

Specific campaign fields

Offers: Detail of pre-negotiated discount.

  • id: Offer identification.
  • original_price Original item price.
  • new_price Final item price.
  • status Promotion item status.
  • start_date Start date of offer in promotion.
  • end_date End date of offer in promotion.
  • Benefits:Promotion benefit details.
  • type: Benefit type.
  • meli_percent: Percentage contributed by Mercado Libre.
  • seller_percent: Percentage contributed by seller.

Status campaign description

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

Check items in an unhealthy stock campaign

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$PROMOTION_ID?/items?user_id=$USER_ID
--header 'version: v2' \
--header 'X-Client-Id: \
--header 'X-Caller-Id: \

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLC13457036/items?user_id=1317418862
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \

Response:

{
  "results": [
  {
  "id": "MLC1386957825",
  "status": "started",
  "price": 28,
  "original_price": 30,
  "currency_id": "USD",
  "offer_id": "OFFER-MLC1386957825-10097412984",
  "seller_percentage": 6.7,
  "start_date": "2023-10-02T17:00:00Z",
  "end_date": "2023-10-16T15:00:00Z"
  },
  {
  "id": "MLC1386957833",
  "status": "candidate",
  "price": 96.57,
  "original_price": 101.54,
  "currency_id": "USD",
  "offer_id": "CANDIDATE-MLC1386957833-70237414751",
  "seller_percentage": 2,
  "start_date": "2023-10-02T17:00:00Z",
  "end_date": "2023-10-16T15:00:00Z"
  },
  {
  "id": "MLC1379437243",
  "status": "candidate",
  "price": 49.99,
  "original_price": 0,
  "currency_id": "USD",
  "offer_id": "CANDIDATE-MLC1379437243-70237419700",
  "seller_percentage": 4,
  "start_date": "2023-10-02T17:00:00Z",
  "end_date": "2023-10-16T15:00:00Z"
  },
  {
  "id": "MLC1379425217",
  "status": "candidate",
  "price": 20,
  "original_price": 0,
  "currency_id": "USD",
  "offer_id": "CANDIDATE-MLC1379425217-70237419697",
  "seller_percentage": 10,
  "start_date": "2023-10-02T17:00:00Z",
  "end_date": "2023-10-16T15:00:00Z"
  }
  ],
  "paging": {
  "offset": 0,
  "limit": 50,
  "total": 4
  }
  }

When a new campaign is created, all applicable items are selected. The initial item (status) is "candidate" with a unique "offer_id". When the seller adds an item to the campaign, item status changes and goes to programmed or active.



Status item description

Status Description
candidate Candidate item to participate in the promotion.
programmed Approved and programmed promotion item.
Active Campaign active item.


Accept an unhealthy stock discount per item / OPTIN.

Once a discount has been negotiated for an item, the seller can accept the unhealthy stock discount with the following resource.

Nota:
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 
  {
     "promotion_id":"$PROMOTION_ID",
      "offer_id":"$OFFER_ID",
     "promotion_type":"$PROMOTION_TYPE"
  }
  https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d 
  {
     "promotion_id":"P-MLC13457036",
      "offer_id":"CANDIDATE-MLC1379425217-70237419697",
     "promotion_type":"UNHEALTHY_STOCK"
  }
  
  https://api.mercadolibre.com/marketplace/seller-promotions/items/MLC1379425217?user_id=1317418862
  --header 'version: v2' \
  --header 'X-Client-Id: 1317417907' \
  --header 'X-Caller-Id: 1317417907' \
  

Response:

{
  "price": 18,
  "original_price": 20,
  "currency_id": "USD",
  "offer_id": "OFFER-MLC1379425217-10098413990"
  }

Parameters

promotion_id: Promotion identification.
offer_id: Negotiated offer identification.
promotion_type: Type of promotion (UNHEALTHY_STOCK).



Remove unhealthy stock discount

Use this resource to remove an unhealthy stock discount per Item.


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=UNHEALTHY_STOCK&promotion_id=$PROMOTION_ID

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/MLC1379425217?user_id=1317418862&promotion_type=UNHEALTHY_STOCK&promotion_id=P-MLC13457036&offer_id=OFFER-MLC1379425217-10098413990
  --header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \

Response: Status 200 OK


Nota:
Remember that if an item Unhealthy discount is removed, the item will no longer be a candidate.

Next:Price Discount (PRICE_DISCOUNT).