Volume discount campaigns

Sellers are regularly invited to participate in different website campaigns. The main characteristic of this type of campaign is that a discount is applied when a given number of product items is reached. For example, Get 4 Pay 3, 2x1 or second item at half price.
Besides Mercado Libre assumes a percentage of the offered discount. If you received an invitation and want to join, use the resources below.

Seller view

View campaign details

To get the details of a volume discount campaign, use the query below:

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": "P-MLB1806017",
  "type": "VOLUME",
  "status": "started",
  "start_date": "2023-04-20T03:00:00Z",
  "finish_date": "2023-08-01T02:00:00Z",
  "deadline_date": "2023-08-01T01:00:00Z",
  "name": "Leva 3 paga 2",
  "benefits": {
      "type": "VOLUME",
      "meli_percent": 9.9999,
      "seller_percent": 23.3331,
      "name": "3x2",
      "buy_quantity": 3,
      "pay_quantity": 2,
      "item_discount_percent": 33.333
  }
}

Specific campaign fields

Benefits: promotion benefit details

Discounts types

Find below the different types of discount for this campaign:

• Get 2 Pay 1
• 70% OFF buying 2
• 70% OFF in the 2nd unit




Status

View in the table below the different status a volume discount campaign can go through.

Status	Description
pending	Promotion approved but not yet started.
started	Active promotion.
finished	Finished promotion.





View items in a campaign

Use the query to see candidate items and/or the items included in a volume discount campaign:




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 item (status) is candidate with no assigned offer id. When the seller adds an item to the campaign, item status changes and a unique offer_id is assigned.





Item status

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

Status	Description
candidate	Candidate item to participate in the promotion.
pending	Approved and programmed promotion item.
started	Campaign active item.
finished	Item deleted from campaign

Indicate items for a campaign

Note:
See that to indicate and remove this campaign from an item, we change the wording from deal_id to promotion_id.

Once you are invited to participate in this type of campaign, you can indicate the products to be included.

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: type of promotion (VOLUME).






Modify items

Since prices cannot be changed directly, follow the steps to change the price of an item included in a volume discount campaign.


• Delete the item from the campaign;
• Change item price just like regular price synchronization;
• Add the item back to the campaign.


Nota:
- Since items included in volume discount campaigns (marketplace campaign) have no fixed price, when the price of an included item rises, it will be automatically removed from the offer and you will not be able to add it back.
- We recommend checking if the item is participating in a volume discount campaign before making price changes (manual or automatic).



Delete items

Perform the task below to delete Items for a Volume discount campaigns

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




Next: Pre-negotiated discount per item