Volume discount campaigns

Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.

Last update 15/01/2026

Quantity discount campaigns

Important:

The new status filter is now available to filter campaign items using the status_item query param, which accepts "active" or "paused" values.

Sellers now have control over the creation of quantity discount campaigns that take place on the site. The main characteristic of this type of campaign is that a discount is applied when a certain quantity of items of a product is reached. We have also added the concept of discounts in different volume and discount situations, as well as the new concept of "combinable campaign" and "non-combinable campaign" which improves discount flexibility.

Important:

The old volume discount mechanism created by Mercado Libre has been discontinued. Campaigns created and activated before this change will be maintained until completion. As a custom campaign, Mercado Libre does not provide co-participation, similar to seller campaigns.

Seller view

Create campaign

In addition to the general campaign details, such as name, start date and end date, there are three types of volume campaigns to consider when creating:

BNGM(Buy N get M): pay 3 and take 9.

BNSP(Buy N save P%): 50% OFF buying 2.

SPONTH(Save P% on the Nth): 50% OFF on the 2nd unit.

It is also necessary to indicate whether it is possible to apply the discount on the selected quantity of the same item or if it is possible to combine different items to apply the discount.

To create a seller volume campaign, execute the following call:

BNGM example sending buy_quantity, pay_quantity and allow_combination allowing to combine different items:

curl -X POST -H 'https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "promotion_type": "VOLUME",
  "sub_type": "BNGM",
  "buy_quantity": 3,
  "pay_quantity": 2,
  "allow_combination": true,
  "name": "DxV teste BNGM",
  "start_date": "2024-08-29T00:00:00",
  "finish_date": "2024-09-29T00:00:00"
}
'

Response:

{
   "id": "C-MLB5790",
   "type": "VOLUME",
   "sub_type": "BNGM",
   "status": "pending",
   "start_date": "2024-08-29T00:00:00",
   "finish_date": "2024-09-29T23:59:59",
   "name": "DxV teste BNGM",
   "buy_quantity": 3,
   "pay_quantity": 2,
   "allow_combination": true
}

BNSP example sending buy_quantity, discount_percentage and allow_combination not allowing to combine different items:

curl -X POST -H 'https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2&version=test' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "promotion_type": "VOLUME",
  "sub_type": "BNSP",
  "buy_quantity": 5,
 "discount_percentage": 30,
  "allow_combination": false,
  "name": "DxV teste BNSP",
  "start_date": "2024-08-29T00:00:00",
  "finish_date": "2024-09-29T00:00:00"
}'

Response:

{
   "id": "C-MLB5789",
   "type": "VOLUME",
   "sub_type": "BNSP",
   "status": "pending",
   "start_date": "2024-08-29T00:00:00",
   "finish_date": "2024-09-29T23:59:59",
   "name": "DxV teste BNSP",
   "buy_quantity": 5,
   "discount_percentage": 30,
   "allow_combination": false,
}

SPONTH example sending buy_quantity, discount_percentage and allow_combination allowing to combine different items:

curl -X POST -H 'https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2&version=test' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
   "promotion_type": "VOLUME",
   "sub_type": "SPONTH",
   "buy_quantity": 2,
   "discount_percentage": 50,
   "allow_combination": true,
   "name": "DxV teste SPONTH",
  "start_date": "2024-08-29T00:00:00",
  "finish_date": "2024-09-29T00:00:00"
}'

Response:

{
   "id": "C-MLB5791",
   "type": "VOLUME",
   "sub_type": "SPONTH",
   "status": "pending",
   "start_date": "2024-08-29T00:00:00",
   "finish_date": "2024-09-29T23:59:59",
   "name": "DxV teste SPONTH",
   "buy_quantity": 2,
   "discount_percentage": 50,
   "allow_combination": true
}

promotion_type: VOLUME. Required.

name: campaign name that serves as identifier for this type of campaigns in the promotions center. Required.

start_date and finish date: campaign validity period. Required

allow_combination: if true, allows item combination. Required.

sub_type: specify the campaign sub-type BNGM/BNSP/SPONTH. Required.

Considering the subtype, 2 of the following fields must be sent: buy_quantity, pay_quantity, discount_percentage.

BNGM: you need to send buy_quantity indicating the quantity to buy (e.g. 9) and pay_quantity, indicating the quantity actually paid (e.g. 3).

BNSP: you need to send buy_quantity indicating the quantity to buy (e.g. 2) and discount_percentage, indicating the discount percentage (e.g. 50).

SPONTH: buy_quantity indicating the quantity to buy (e.g. 2) and discount_percentage indicating the discount percentage on that unit (e.g. 50).

Update campaign

For editing quantity discount campaigns, the following considerations must be taken into account:

The promotion_type field must always be sent (which must have the value VOLUME).

The start date and end date cannot be modified.

For active campaigns, only the name can be modified.

Only the seller who created the campaign will have permissions to modify it.

For scheduled campaigns, only the fields to be modified should be sent, taking into account:

If you want to modify the attributes of a campaign (buy_quantity, pay_quantity, discount_percentage) or change its subtype, all corresponding attributes must be indicated according to the subtype, even if they are not modified.

Example:

curl --location --request PUT 'https://api.mercadolibre.com/seller-promotions/promotions/C-MLB5783?app_version=v2&version=test' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
   "promotion_type": "VOLUME",
   "sub_type": "BNSP",
   "buy_quantity": 9,
   "discount_percentage": 30,
   "allow_combination": false,
   "name": "campanha de teste"
}'

The successful response is a 200 OK code. And has the same format as the campaign creation response:

{
   "id": "C-MLB5783",
   "type": "VOLUME",
   "sub_type": "BNSP",
   "status": "pending",
   "start_date": "2024-08-29T00:00:00",
   "finish_date": "2024-09-29T23:59:59",
   "name": "campanha de teste",
   "buy_quantity": 9,
   "discount_percentage": 30,
   "allow_combination": false
}

Delete campaign

A campaign can be deleted and its deletion will deactivate all existing offers associated with it:

curl --location --request DELETE 'https://api.mercadolibre.com/seller-promotions/promotions/{{Promo-ID}}?promotion_type=VOLUME&app_version=v2' \
--header 'Authorization: Bearer {{token}}'

The successful response is a 200 OK code, with the body as null.

Query campaign details

To get the details of a volume discount campaign, make the following query:

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/P-MLB1806017?promotion_type=VOLUME&app_version=v2

Response:

{
     "id": "C-MLB5790",
   "type": "VOLUME",
   "sub_type": "BNGM",
   "status": "started",
   "start_date": "2024-08-29T03:00:00Z",
   "finish_date": "2024-09-30T02:59:59Z",
   "name": "DxV teste BNGM",
   "buy_quantity": 3,
   "pay_quantity": 2,
   "allow_combination": false
}

Specific fields for this campaign

id: campaign identifier.

type: campaign type (VOLUME).

sub_type: specify the campaign sub-type BNGM/BNSP/SPONTH.

status: current campaign status.

start_date and finish_date: campaign validity period.

allow_combination: if true, allows item combination. Required.

buy_quantity: required quantity of items to access the discount.

pay_quantity: quantity of items that are paid

discount_percentage: discount percentage on each item.

allow_combination: if true, allows item combination.

Statuses

These are the different statuses that a volume discount campaign can go through.

Status	Description
pending	Approved promotion that has not yet started.
started	Active promotion.
finished	Finished promotion.

Query items in a campaign

To find out the candidate items and/or those that are part of a volume discount campaign, you can make the following query:

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions//P-MLB1806017/items?promotion_type=VOLUME&app_version=v2

Response:

{
  "results": [
      {
          "id": "MLB3500418540",
          "status": "candidate",
          "price": 1333.34,
          "original_price": 2000,
          "meli_percentage": 10,
          "seller_percentage": 23.3,
          "start_date": "2023-04-20T03:00:00Z",
          "end_date": "2023-08-01T02:00:00Z"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 1
  }
}

When a new campaign is created, all applicable items are selected. The initial status of the items is candidate and without an assigned offer id. When the seller adds an item to the campaign, its status is modified and a unique offer_id is assigned.

Item statuses

In the following table you can find the possible statuses that items can have within this type of campaign.

Status	Description
candidate	Candidate item to participate in the promotion.
pending	Item with approved and scheduled promotion.
started	Item active in the campaign.
finished	Item removed from the campaign

Add items to a campaign

Once you have been invited to participate in this type of campaign, you can indicate which products you want to include in it.

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "promotion_id":"$PROMOTION_ID",
   "promotion_type":"$PROMOTION_TYPE"
}' 
https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "promotion_id":"P-MLB379009",
   "promotion_type":"VOLUME"
}'
https://api.mercadolibre.com/seller-promotions/items/MLB1834747833&app_version=v2

Response:

{
  "offer_id": "MLB1834747833-9eafadd4-16d2-49ae-b272-9a7a34585cb8",
  "price": 1800,
  "original_price": 2000
}

Parameters

promotion_id: promotion identification.
promotion_type: promotion type (VOLUME).

Modifying items

To modify the price of an item that is participating in a volume discount campaign, the following steps must be taken, since it is not possible to modify the price directly.

Remove the item from the campaign;
Modify the item price as normal price synchronization;
Include the item in the campaign again.

Note:

Items participating in volume discount campaigns do not have a fixed price, therefore if an item is participating and its price increases, it will automatically leave the offer and you will not be able to add it again.
- We recommend validating if the item is participating in a volume discount campaign when making a price modification (manual or automatic).

Delete items

With this resource you can delete the item offer.

Request:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&promotion_id=$PROMOTION_ID&offer_id=$OFFER_ID

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA632979587?promotion_type=VOLUME&promotion_id=1804&offer_id=MLA876618673-9eafadd4-16d2-49ae-b272-9a7a34585cb8&app_version=v2'Í

Response: Status 200 OK

Learn more about Quantity offers.

Next: Pre-negotiated item discount