Volume Discount

The Volume Discount (DxV) feature allows sellers to offer discounts based on the quantity of products purchased. This resource lets you create, update, delete, and manage promotions linked to the volume discount system.

Create campaign

Sellers can create a volume discount campaign, defining specific parameters to apply discounts according to quantity purchased.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/$USER_ID' \
--header 'Version: v2' \
--header 'Content-Type: application/json' \
--data '{
    "promotion_type": "VOLUME",
    "sub_type": "$SUB_TYPE",
    "buy_quantity": $BUY_QUANTITY,
    "pay_quantity": $PAY_QUANTITY,
    "allow_combination": true,
    "name": "$CAMPAIGN_NAME",
    "start_date": "$START_DATE",
    "finish_date": "$FINISH_DATE"
}'

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/123456789' \
--header 'Version: v2' \
--header 'Content-Type: application/json' \
--data '{
    "promotion_type": "VOLUME",
    "sub_type": "BNGM",
    "buy_quantity": 2,
    "pay_quantity": 1,
    "allow_combination": true,
    "name": "test campaña bngm",
    "start_date": "2025-10-07T00:00:00",
    "finish_date": "2025-10-20T00:00:00"
}'

Response:

{
     "id": "C-MLB360923", 
   "type": "VOLUME", 
   "sub_type": "BNGM|BNSP|SPONTH", 
   "(*)"buy_quantity": 9, 
   "(*)"pay_quantity": 3, 
   "(*)"discount_percentage": 30, 
   "allow_combination": true, 
   "status": "pending", 
   "start_date": "2023-07-17T00:00:00", 
   "finish_date": "2023-07-20T23:59:59", 
   "name": "test campaña bngm"
}

Parameters

• promotion_type: must be VOLUME.
• name: unique name to identify the campaign.
• start_date: campaign start date in local format.
• finish_date: campaign end date in local format.
• allow_combination: determines if different items can be combined to apply the promotion. It is not possible to combine a volume promo with another discount.
• sub_type: promotion subtype. Can be one of the following:
  • BNGM (Buy N Get M): Customer pays for M units and receives N units. Example: pay 3 and take 9.
  • BNSP (Buy N Save P%): Customer receives a percentage discount when buying N units. Example: 50% OFF buying 2.
  • SPONTH (Save P% on the Nth): Customer receives a percentage discount on the Nth unit. Example: 50% OFF on the 2nd unit.

Required fields by subtype

Based on the subtype, you must send 2 of the following fields:

Subtype	Required Fields	Example
BNGM	buy_quantity + pay_quantity	buy_quantity: 9, pay_quantity: 3
BNSP	buy_quantity + discount_percentage	buy_quantity: 2, discount_percentage: 50
SPONTH	buy_quantity + discount_percentage	buy_quantity: 2, discount_percentage: 50

Response fields

• id: unique campaign identifier.
• type: campaign type. Value: VOLUME.
• sub_type: promotion subtype (BNGM, BNSP, or SPONTH).
• buy_quantity: number of items the customer must purchase.
• pay_quantity: number of items the customer pays for (BNGM only).
• discount_percentage: discount percentage applied (BNSP and SPONTH only).
• allow_combination: indicates if different items can be combined.
• status: campaign status (pending, started, finished).
• start_date: campaign start date.
• finish_date: campaign end date.
• name: campaign name.

Update campaign

Use this resource to modify an existing volume discount campaign.

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/$PROMOTION_ID?user_id=$USER_ID&callers=$USER_ID' \
--header 'Version: v2' \
--header 'Content-Type: application/json' \
--data '{
    "promotion_type": "VOLUME",
    "sub_type": "$SUB_TYPE",
    "buy_quantity": $BUY_QUANTITY,
    "pay_quantity": $PAY_QUANTITY,
    "allow_combination": true,
    "name": "$NEW_NAME"
}'

Example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/C-MLM5689?user_id=123456789&callers=123456789' \
--header 'Version: v2' \
--header 'Content-Type: application/json' \
--data '{
    "promotion_type": "VOLUME",
    "sub_type": "BNSP",
    "buy_quantity": 3,
    "discount_percentage": 60,
    "allow_combination": true,
    "name": "Updated campaign name"
}'

Response:

{
    "id": "C-MLM5689",
    "type": "VOLUME",
    "sub_type": "BNSP",
    "status": "pending",
    "start_date": "2024-08-22T17:20:00",
    "finish_date": "2024-08-28T00:00:00",
    "name": "Updated campaign name",
    "buy_quantity": 3,
    "discount_percentage": 60,
    "allow_combination": true
}

Delete campaign

Use this resource to delete a specific volume discount campaign by its ID.

Request:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/$PROMOTION_ID?user_id=$USER_ID&callers=$USER_ID&promotion_type=VOLUME' \
--header 'Version: v2' \
--header 'Content-Type: application/json'

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/seller-campaign/C-MLM360923?user_id=123456789&callers=123456789&promotion_type=VOLUME' \
--header 'Version: v2' \
--header 'Content-Type: application/json'

Response: HTTP 200 OK (empty body)

Get campaign items

Use this resource to obtain the candidate items and existing offers for a seller's volume discount campaign.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$PROMOTION_ID?user_id=$USER_ID&callers=$USER_ID&promotion_type=VOLUME' \
--header 'Version: v2'

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/C-MLM614177?user_id=123456789&callers=123456789&promotion_type=VOLUME' \
--header 'Version: v2'

Response:

{
    "results": [
        {
            "id": "MLM4007773188",
            "status": "candidate",
            "original_price": 20,
            "buy_quantity": 3,
            "discount_percentage": 20,
            "allow_combination": true,
            "start_date": "2025-09-25T06:00:00Z",
            "finish_date": "2025-10-26T05:59:59Z",
            "sub_type": "BNSP"
        }
    ]
}

Response fields

• id: item identifier.
• status: item status in the promotion (candidate, active, finished).
• original_price: original price of the item.
• buy_quantity: number of items required for the promotion.
• pay_quantity: number of items the customer pays for (BNGM only).
• discount_percentage: discount percentage applied (BNSP and SPONTH only). Value range: 0-100.
• allow_combination: true if items can be combined, false otherwise.
• start_date: promotion start date for this item.
• finish_date: promotion end date for this item.
• sub_type: promotion subtype (BNGM, BNSP, or SPONTH).

Indicate items to a campaign

Use this resource to link a specific item to a volume discount campaign so that discount rules apply to that item.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID&callers=$USER_ID' \
--header 'Version: v2' \
--header 'Content-Type: application/json' \
--data '{
    "promotion_id": "$PROMOTION_ID",
    "promotion_type": "VOLUME"
}'

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM4007773188?user_id=123456789&callers=123456789' \
--header 'Version: v2' \
--header 'Content-Type: application/json' \
--data '{
    "promotion_id": "C-MLM614177",
    "promotion_type": "VOLUME"
}'

Response:

{
    "price": 11000,
    "original_price": 13000,
    "currency_id": "MXN",
    "offer_id": "OFFER-MLM4007773188-1111"
}

Parameters

• promotion_id: the campaign ID to link the item to.
• promotion_type: must be VOLUME.

Response fields

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

Errors

HTTP Code	Error	Description
400	Invalid promotion type	promotion_type is not VOLUME or not enabled.
400	Conflicting ranges	Offer with same range start date / end date already exists.
400	Offers_Maximum_Quantity_Reached	Maximum 5 quantity discounts per item reached.
404	Promotion Not Found	Invalid promotion_id.
403	Invalid caller.id	Caller is not owner of the campaign.

Remove items from a campaign

Use this resource to remove an item previously linked to a volume discount campaign, preventing discounts from applying to that item.

Request:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?promotion_type=VOLUME&promotion_id=$PROMOTION_ID&user_id=$USER_ID&callers=$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/MLM4007773188?promotion_type=VOLUME&promotion_id=C-MLM614177&user_id=123456789&callers=123456789' \
--header 'Version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907'

Response: HTTP 200 OK (empty body)

Errors

HTTP Code	Error	Description
400	No offers found for item	The item is not linked to any volume discount offer.
400	Invalid promotion type	promotion_type is not VOLUME.
403	Invalid caller.id	Caller is not owner of the campaign.

Next: Deal of the Day