Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 05/12/2023

Pre-negotiated discount per Item and Full stock sale campaign

Importante:
- From January 10, 2024 we will delete the previous version of the /seller-promotions resource.
- To get the answer with the new version, send the query param app_version=v2. See the documentation for each campaign for the changes.
- These campaigns are in the same documentation because they work with the same logic and the same parameters.

Sellers are regularly invited to participate in different website campaigns.
Pre-negotiated Discount per Item In this type of campaign the seller previously negotiates with Mercado Libre commercial representative a discount for certain items, setting price, offered discount and granted benefit.
Full stock sale campaign this type of campaign is very similar to the pre-agreed discount per item campaign, but with the difference that it is only for Full items.
If the seller received an invitation and wants to join, use the resources below.


Seller view








Check details about a campaign

Pre-negotiated discount exampl:

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

Pre-negotiated discount response:

{
   "id": "P-MLM394001",
   "type": "PRE_NEGOTIATED",
   "status": "started",
   "start_date": "2021-03-30T18:30:15.525Z",
   "finish_date": "2021-12-27T17:59:59.525Z",
   "deadline_date": "2021-05-27T17:59:59.525Z",
   "name": "Prueba descuento x item sin benefit",
   "offers": [
       {
           "id": "MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
           "original_price": 101,
           "new_price": 21,
           "status": "active",
           "start_date": "2021-05-10T16:00:00Z",
           "end_date": "2021-05-11T15:00:00Z",
           "benefits": {
               "type": "REBATE",
               "meli_percent": 9.9,
               "seller_percent": 69.3
           }
       }
   ]
}

Full stock sale campaign example:

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

Full stock sale campaign response:

{
   "id": "P-MLB12345",
   "type": "UNHEALTHY_STOCK",
   "status": "started",
   "start_date": "2023-08-30T18:30:15.525Z",
   "finish_date": "2023-12-27T17:59:59.525Z",
   "deadline_date": "2023-09-27T17:59:59.525Z",
   "name": "Prueba liquidación stock Full",
   "offers": [
       {
           "id": "MLB10203040-f588cf87-e298-498e-82ad-285b16dd11d5",
           "original_price": 101,
           "new_price": 21,
           "status": "active",
           "start_date": "2023-09-10T16:00:00Z",
           "end_date": "2021-09-11T15:00:00Z",
           "benefits": {
               "type": "REBATE",
               "meli_percent": 9.9,
               "seller_percent": 69.3
           }
       }
   ]
}

Specific campaigns fields


Offers: detail of pre-negotiated discount.

  • id: offer identification.
  • original_price: original item price.
  • new_price: final item price.
  • status: promotion item status.
  • start_date: start date of offer in promotion.
  • end_date: end date of offer in promotion.

  • Benefits: promotion benefit details.
        • type: benefit type.
        • meli_percent: percentage contributed by Mercado Libre.
        • seller_percent: percentage contributed by seller.


    Status

    These are the different status that these campaigns can go through.

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


    Check items in a campaign

    Perform the query below to see the items included in a campaign:


    Pre-negotiated discount example:

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

    Pre-negotiated discount response:

    {
   "results": [
       {
           "id": "MLM848619385",
           "status": "candidate",
           "price": 21,
           "original_price": 101,
           "offer_id": "MLM848619385-0e2f3064-0e13-425d-b4a7-0dee85414835",
           "meli_percentage": 24.8,
           "seller_percentage": 54.5,
           "start_date": "2021-05-11T22:00:00Z",
           "end_date": "2021-05-13T01:00:00Z"
       }
   ],
   "paging": {
       "total": 1
   }
}

    Full stock sale campaign example:

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

    Full stock sale campaign response:

    {
   "results": [
       {
           "id": "MLB10203040",
           "status": "candidate",
           "price": 21,
           "original_price": 101,
           "offer_id": "MLB10203040-0e2f3064-0e13-425d-b4a7-0dee85414835",
           "meli_percentage": 24.8,
           "seller_percentage": 54.5,
           "start_date": "2023-09-11T22:00:00Z",
           "end_date": "2023-09-13T01:00:00Z"
       }
   ],
   "paging": {
       "total": 1
   }
}

    When a new campaign is created, all applicable items are selected. The initial item (status) is candidate with a unique offer_id. When the seller adds an item to the campaign, item status changes and goes to programmed or active.



    Item status

    The table below shows the possible item statuses in 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.


    Accept a discount per Item

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

    Once a discount has been negotiated for an item, the seller can accept the pre-negotiation with the following resource.

    Request:

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

    Pre-negotiated discount exampl:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "promotion_id":"P-MLM394001",
   "offer_id":"MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
   "promotion_type":"PRE_NEGOTIATED"
}'
https://api.mercadolibre.com/seller-promotions/items/MLM848619385

    Pre-negotiated discount response:

    {
   "offer_id": "MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
   "price": 21,
   "original_price": 101
}

    Full stock sale campaign example:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "promotion_id":"P-MLB12345",
    "offer_id":"MLB10203040-f588cf87-e298-498e-82ad-285b16dd11d5",
   "promotion_type":"UNHEALTHY_STOCK"
}'
https://api.mercadolibre.com/seller-promotions/items/MLB10203040

    Full stock sale campaign response:

    {
   "offer_id": "MLB10203040-f588cf87-e298-498e-82ad-285b16dd11d5",
   "price": 21,
   "original_price": 101
}

    Parameters

    promotion_id: promotion identification.
    offer_id: negotiated offer identification.
    promotion_type: type of promotion (PRE_NEGOTIATED).



    Remove a discount

    Use this resource for pre-negotiated discount per Item.

    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

    Pre-negotiated discount example:

    curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLB1834747833?promotion_type=PRE_NEGOTIATED&promotion_id=P-MLM394001&offer_id=MLM1834747833-9eafadd4-16d2-49ae-b272-9a7a34585cb8

    Response: Status 200 OK

    Note:
    Remember that if an item pre-negotiated discount or a Full stock sale campaign is removed, the item will no longer be a candidate.

    Next: Price Discount