Price discount

Sellers who want to apply a specific discount to their items can use the following resources to create, remove, and query discounts.

Requirements

To offer this discount, the following conditions must be met:

• Seller must have a green reputation.
• Seller must have at least 1 product sale.
• Item status must be active.
• Item condition must be new.
• Item listing type cannot be free.

Offer discount for an item

Use this resource to apply a price discount to a specific item.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
    "deal_price": $DEAL_PRICE,
    "top_deal_price": $TOP_DEAL_PRICE,
    "start_date": "$START_DATE",
    "finish_date": "$FINISH_DATE",
    "promotion_type": "PRICE_DISCOUNT"
}' \
'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID' \
--header 'version: v2' \
--header 'X-Client-Id: $CLIENT_ID' \
--header 'X-Caller-Id: $CALLER_ID'

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
    "deal_price": 20,
    "top_deal_price": 15,
    "start_date": "2025-12-09T00:00:00",
    "finish_date": "2025-12-16T23:59:59",
    "promotion_type": "PRICE_DISCOUNT"
}' \
'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM3782207298?user_id=2487485082' \
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907'

Response:

{
    "price": 20,
    "original_price": 39.29,
    "currency_id": "USD",
    "offer_id": "OFFER-MLM3782207298-11795706698"
}

Parameters

• deal_price: discounted price for all buyers.
• top_deal_price: discounted price for loyalty program members (Mercado Puntos level 3 to 6). (optional)
• start_date: discount start date in local format.
• finish_date: discount end date in local format.
• promotion_type: must be PRICE_DISCOUNT.

Response fields

• price: the discounted price applied to the item.
• original_price: the original price of the item before the discount.
• currency_id: currency code (e.g., USD, MXN).
• offer_id: unique identifier for the created offer.

Considerations

• Discounts can be segmented by setting a general price for all buyers and a special price for loyalty members (Mercado Puntos level 3 to 6).
• For discounts up to 35%, the general discount must be at least 5% higher than the loyalty member discount. For discounts above 35%, the difference must be at least 10%.
• The maximum discount allowed is 80%, and the minimum discount must be at least 5%.
• If the item price increases, all discounts will be automatically removed.
• The maximum duration for a PRICE_DISCOUNT promotion is 14 days.
• If the item is already participating in a DEAL when the discount starts, the PRICE_DISCOUNT will not be applied until the DEAL ends.
• The start_date and finish_date parameters only consider the date, not the time. By default, discounts start at 00:00:00 on the start date and end at 23:59:59 on the finish date.

Item status

The table below shows the possible item statuses when applying a price discount:

Delete a price discount

Use this resource to remove a price discount from an item.

Request:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?promotion_type=PRICE_DISCOUNT&user_id=$USER_ID' \
--header 'version: v2' \
--header 'X-Client-Id: $CLIENT_ID' \
--header 'X-Caller-Id: $CALLER_ID'

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM3782207298?promotion_type=PRICE_DISCOUNT&user_id=2487485082' \
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907'

Response: HTTP 200 OK (empty body)

Errors

The following errors may occur when offering discounts:

Discount percentage out of range

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

Cause: The discount percentage is outside the allowed range (5% to 80%).

Insufficient discount difference between tiers

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

Cause: The difference between general and loyalty member discounts does not meet the minimum requirements.

Price credibility error

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

Cause: The discount results in a price that the system considers not credible. A higher original price or smaller discount may be required.

Next: Deal of the Day