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

In addition, the item can only have discounts when it has the following tag loyalty_discount_eligible which represents that it complies with all the rules. 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

Call:

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

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

Call:

curl -X PUT "http://api.mercadolibre.com/promo/item/{itemId}?access_token=$ACCESS_TOKEN""

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 30 days. (YYYY-MM-DDThh:mm:ss).
discount_type: discount type. Today, PRICE_DISCOUNT is available.


Considerations

  • The "original_price" is only estimated with the new value when the discount changes the original price, that is, this happens when you make a discount for levels 1 and 2. If the original price is not changed, the discounts in sales_terms information will only be added in the item query.
  • Discount offer segmentation setting a higher percentage for our loyal buyers (Mercado Puntos level 3 to 6), and a lower percentage to the remaining buyers (Mercado Puntos level 1 and 2).
  • If the seller adds a discount, that item will be accessible from the discount marketplace landing page.
  • Once the item original price is changed, discounts will be automatically removed.

Learn more about offer discounts.


Remove discount

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

Call:

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.

Call:

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.


Considerations

  • The item should be from a site with this feature on. error failed_rules Code: EnabledSiteRule
  • Level 1 and 2 discount should be, at least, 5% less than 3 to 6 users' discount. That is, we give better discounts to higher levels. error failed_rules Code: PricePercentageDeltaRule
  • The user item should have, at least, 3 sales in the last 30, and within a certain price threshold. error failed_rules Code: ItemPriceVsMaxSalesPriceRule and ItemMoreEqThanXSalesRule
  • Qualified Sellers are those with a green and green reputation. Error code failed_rules: UserReputationRule.
  • The maximum discount must be less than 80%. Error code failed_rules: MaximumDiscountPercentageRule.
  • Minimum discount of 5%. Error code failed_rules: ItemValidDiscountRule.
  • The item should be new. Error code failed_rules: ItemConditionRule.
  • The item cannot be in a deal. Error code failed_rules: ItemNotInDealRule.
  • The item must have at least 5 reviews and the average of those reviews has to be >= 3. Error code failed_rules:ItemRatingRule.
  • The discount applies to items with a price greater than or equal to those established for each site. In case of being below the range an API error will be received: ItemMinPriceRuleTask.
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.

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.