Discount management

The resource can be used by all sellers with green reputation to manage discounts on items. In this guide, you can learn how developer this implementation, how apply, delete and query its.

Important:
At first, this will only be available for MLA, MLM and MLB sellers.

Contents

→Apply discount
    ↳Add discount only to level user 1 and 2
    ↳Add discount to level 3 to 6 users and to level 1 and 2 users
       ↳Parameters
       ↳Considerations
→Remove discount
→Query discount
→Posibles errores


Apply discount

Before applying a discount take into account that there are different discount rules according to the levels related to the new Mercado Puntos benefit program in our platform. They are:

  • Nivel 1: Initial
  • Nivel 2: Amateur
  • Nivel 3: Advance
  • Nivel 4: Professional
  • Level 5: Expert
  • Level 6: Legend

Discounts can be directly applied to levels 3 to 6, and for levels 1 and 2, you need to include levels 3 to 6 as well. That is, you cannot apply discounts for levels 1 and 2 only.

To apply a discount, you will need to make a PUT as shown below.


Add discount only to level user 1 and 2

Request:

curl -X PUT http://api.mercadolibre.com/promo/item/$ITEM_ID?access_token=$ACCESS_TOKEN 
{
	"best_buyers_discount_percentage" : XX, 
	"buyers_discount_percentage" : XX, 
	"start_date": "AAAA-MM-DDT00:00:00", 
	"finish_date": "AAAA-MM-DDT00:00:00", 
	"discount_type:" "PRICE_DISCOUNT"
}

Example:

curl -X PUT http://api.mercadolibre.com/promo/item/MLB1105211403?access_token=$ACCESS_TOKEN
{
 "best_buyers_discount_percentage" : null,
 "buyers_discount_percentage" :  10,
 "start_date": "2020-02-01T00:00:00",
   "finish_date": "2020-03-25T00:00:00",
 "discount_type": "PRICE_DISCOUNT"
}

Response:

{
   "price": 90.00,
   "original_price": 100.00
}

Add discount to level 3 to 6 users and to level 1 and 2 users

Request:

curl -X PUT http://api.mercadolibre.com/promo/item/$ITEM_ID?access_token=$ACCESS_TOKEN 
{
	"best_buyers_discount_percentage" : XX, 
	"buyers_discount_percentage" : XX, 
	"start_date": "AAAA-MM-DDT00:00:00", 
	"finish_date": "AAAA-MM-DDT00:00:00", 
	"discount_type:" "PRICE_DISCOUNT"
}

Example:

curl -X PUT http://api.mercadolibre.com/promo/item/MLB1105211403?access_token=$ACCESS_TOKEN
{
	"best_buyers_discount_percentage" : 30,
	"buyers_discount_percentage" : 20,
	"start_date": "2019-07-09T00:00:00",
  	"finish_date": "2019-07-15T00:00:00",
	"discount_type": "PRICE_DISCOUNT"
}

Response:

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

Parameters

best_buyers_discount_percentage: through this attribute we define levels 3 to 6.
buyers_discount_percentage: through this attribute we define levels 1 and 2.
start_date: start date of the validity of the discount. (YYYY-MM-DDThh:mm:ss).
finish_date: end date of the validity of the discount. The maximum term of validity must be 7 days. (YYYY-MM-DDThh:mm:ss).
discount_type: discount type. Today, PRICE_DISCOUNT is available.


Considerations

  • The loyalty_discount_eligible tag indicates that the product is eligible to apply a discount, but you must take into account the rules on how to offer them.
  • It is possible to segment the discount offer by establishing a higher percentage than our loyal buyers (level 3 to 6 of Mercado Puntos) and a lower percentage than the rest of the buyers (level 1 to 2 of Mercado Puntos).
  • The level 1 and 2 discount must be at least 5% less than that of users 3 to 6, for discounts of up to 35%. For higher discounts, the difference must be at least 10%, that is, we give better discounts at the highest levels.
  • The maximum discount must be less than 80% and the minimum discount to be offered must be greater than or equal to 5%.
  • If there is an increase in the price of the item, the discounts will be automatically removed.
  • If when starting the discount, the item is participating in a deal, said discount will not be applied until the associated deal ends.

Learn more about offer discounts.

Note:
For TEST users it is necessary that the account has a green reputation and the item has at least 3 sales with the current price.

Remove discount

The remove resource removes all the item discounts. You cannot remove for some user levels only.

Request:

curl -X DELETE http://api.mercadolibre.com/promo/item/$ITEM_ID?access_token=$ACCESS_TOKEN

Example:

curl -X DELETE http://api.mercadolibre.com/promo/item/MLB1105219833?access_token=$ACCESS_TOKEN

Response:

The response to this service is an 200 status without body in the response.


Query discount

To see an item discount, make a request GET in the Items resource.

Request:

curl -X GET http:/api.mercadolibre.com/promo/item/$ITEM_ID?access_token=$ACCESS_TOKEN

Example:

curl -X GET http:/api.mercadolibre.com/promo/item/MLA822573619?access_token=$ACCESS_TOKEN

Response:

{
    "id": "353-MLA822573619",
    "start_date": "2019-10-31T00:00:00",
    "finish_date": "2019-10-31T23:59:59",
    "seller_id": 468098195,
    "item_id": "MLA822573619",
    "price": 9000,
    "list_price": 10000,
    "prime_price": 8000,
    "status": "finished"
}

Discount status

Discounts may have in the following status:

started: active discount.
finished: discount finished.
pending: scheduled discount.
sync_requested: pending activation process. In this case, the discount is not yet reflected in the product.
restore_requested: pending removal process.


Reasons:

Show the reasons why the discount ended:

item_feed_pause: The publication has been paused;
job_excecution: The term has been ended;
impact_pending_pause_rollback: The item has been paused when the discount has starting;
item_feed_closed: If the item has been finalized, then the discount ends;
decrement_price: Price changes makes the discount exceed the maximum amount;
increment_price: Price increses makes the discount finalize.


Possible mistakes

Remember the invalid not_authorized ACCESS TOKEN and without ACCESS TOKEN, internal_server_error. Also, avoid mistakes frecuentes, like not inform:

  • The discount in the resource buyers_discount_percentage: null_discount.
  • The start date of the start_date discount: null_promo_start_date.
  • The end date of the finish_date discount: null_promo_finish_date.

The following messages may also appear in case of failure of some of the validations on discounts that are intended to be applied to the item:


Discounts outside the established 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": "best_buyers_discount_percentage parameter must be in range (5, 80)"
}

Differences between discounts for levels 1-2 and levels 3-6 outside the established margins

{
"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%"
}

In addition, for some items to validate the discount applied, we can identify this discount is not enough and the seller must apply a higher discount. For these cases, we will return the following error:

{
    "key": "error_credibility_price",
    "message": "The price is not credible."
}
or register to recieve the latest news about our API