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 10/07/2024

Price Discount

Sellers who want to give a specific offer for their items can use the following resources. They will be able to apply, remove and query discount.
They should have green reputation and, at least, 1 product sales.


To offer this discount it is necessary to:

  • Have green reputation.
  • The item must have status equal to active or paused.
  • Condition equal to new.
  • The exposure of the item can not be free.
  • And only for MLA this type of discount is not available in the book categories.

Offer discount for an item

For this type of offer, some requirements need to be met. Learn more about how to offer discounts.


Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "discount_percent": $DISCOUNT_PERCENT,
   "top_discount_percent": $TOP_DISCOUNT_PERCENT,
   "start_date": "$START_DATE",
   "finish_date": "$FINISH_DATE",
   "promotion_type": "PRICE_DISCOUNT"
}'
https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "discount_percent": 20,
   "top_discount_percent": 30,
   "start_date": "2020-10-19T00:00:00",
   "finish_date": "2020-10-20T00:00:00",
   "promotion_type": "PRICE_DISCOUNT"
}'
https://api.mercadolibre.com/seller-promotions/items/MLA876768946?app_version=v2'

Response:

{
    "price": 70,
    "original_price": 100
}

Parameters

discount_percent: discount percentage for all buyers.
top_discount_percent: discount percentage for best buyers (Mercado Puntos 3 to 6 level). (optional)
start_date: discount start date.
finish_date: discount finish date.


Considerations

  • Discount offer can be segmented setting an overall percentage for all buyers and a top percentage for our loyal buyers (Mercado Puntos 3 to 6 level).
  • The overall discount should be, at least, 5% lower than level 3 to 6 user discount for up to 35% discounts. For higher discounts, the difference should be, at least, 10%; that is, better discounts are given to higher levels.
  • The top discount should be lower than 80% and the lowest discount should be higher than or equal to 5%.
  • If the item price goes up, discounts will be automatically removed.
  • If when a discount starts an item is participating in a DEAL, it will not be applied until the related PRICE_DISCOUNT ends.
  • The maximum term for this type of PRICE_DISCOUNT is 31 days.
Reminder:
- for testing the TEST user should have green reputation and the item should have, at lest, 1 sale with the current price.


Item status

The table below shows the possible item statuses when you want to apply a price discount.



Status Description
started Item active discount.
finished Discount ended.
pending Programmed discount.
sync_requested Pending activation process.
restore_requested Pending discount removal process.


Delete a price discount for an item

Request:

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

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA876768946?promotion_type=PRICE_DISCOUNT

Remember that for individual offers (PRICE DISCOUNT), all the offer will be removed, you cannot remove by buyer level.


Response: Status 200 OK



Errors when offering discounts

Discounts of out set ranges.

{
   "key":"buyer_discount_not_in_range",
   "message":"buyers_discount_percentage parameter must be in range (5, 80)"
}
{
   "key":"best_buyer_discount_not_in_range",
   "message":"buyers_discount_percentage parameter must be in range (5, 80)"
}

Differences in discounts for 1-2 levels and 3-6 levels out of set ranges.

{
   "key":"discount_below_10_percent_difference",
   "message":"The best buyer discount difference cannot be below 10% when buyers discount is above 35%"
}
{
   "key":"discount_below_5_percent_difference",
   "message":"The discount difference cannot be below 5%"
}

When discount is not enough and seller needs to apply a higher discount, we will go back:

{
    "key": "error_credibility_price",
    "message": "The price is not credible."
}

Next post: Daily Deal