Last update 25/08/2022

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.




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'

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 21 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