Developers

Documentación Mercado Libre

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

Última actualización 05/12/2023

Descuento pre-acordado por ítem y Campaña de liquidación stock Full

Importante:

A partir del 10 de enero de 2024 eliminaremos la versión antigua del recurso de /seller-promotions.
- Para obtener la respuesta con la nueva versión envía el query param app_version=v2. Consulta la documentación de cada campaña para estar al tanto de los cambios.
- Estas campañas se encuentran en la misma documentación porque trabajan con la misma lógica y los mismos parámetros.

Los vendedores son invitados periódicamente a participar de diferentes campañas que se realizan en el sitio.
Descuento pre-acordado por ítem: En este tipo de campaña el vendedor pre-acuerda un descuento para determinados ítems con un agente comercial de Mercado Libre, donde se establece el precio, el descuento ofrecido y el beneficio otorgado.
Campaña de liquidación stock Full: Este tipo de campaña es muy similar a la campaña de descuento pre-acordado por ítem, pero con la diferencia que es solo para ítems de full.
Si el vendedor recibió una invitación y quiere sumarse, puede hacerlo con los siguientes recursos.

Vista del vendedor

Consultar detalles de una campaña

Ejemplo de descuento pre-acordado:

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

Respuesta de descuento pre-acordado:

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

Ejemplo de liquidación stock Full:

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

Respuesta de liquidación stock Full:

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

Campos específicos de estas campañas

Offers: detalle del descuento pre-acordado.

id: id de la oferta

original_price: precio original del ítem

new_price: precio final del ítem

status: estado del ítem en la promoción

start_date: fecha de inicio de la oferta en la promoción

end_date: fecha de fin de la oferta en la promoción

Benefits: detalle de los beneficios de la promoción.

type: tipo de beneficio.
meli_percent: porcentaje que aporta Mercado Libre.
seller_percent: porcentaje que aporta el vendedor.

Estados de las campañas

Estos son los distintos estados por los cuales las campañas pueden pasar.

Estado	Descripción
pending	Aprobada que aún no inició.
started	Activa
finished	Finalizada

Consultar ítems en una campaña

Para conocer los ítems que forman parte de una campaña puedes realizar la siguiente consulta:

Ejemplo de descuento pre-acordado:

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

Respuesta de descuento pre-acordado:

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

Ejemplo de liquidación stock Full:

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'

Respuesta de liquidación stock Full:

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

Al crearse una nueva campaña se seleccionan todos los ítems aplicables a la misma. El estado inicial (status) de los ítems es candidate y cuentan con un offer_id único. Al momento que el vendedor incorpora un ítem a la campaña su status se modifica y pasa a estar programmed o active.

Estado de los ítems

En la siguiente tabla puedes encontrar los posibles estados que pueden tomar los ítems dentro de estos tipos de campañas.

Estado	Descripción
candidate	Candidato para participar de la promoción.
pending	Promoción aprobada y programada.
started	Activo en la campaña.
finished	Eliminado de la campaña.

Aceptar descuento

Nota:

Para indicar y eliminar esta campaña de un ítem, cambiamos el wording de "deal_id" a "promotion_id".

Una vez que se ha acordado un descuento para un ítem, con el siguiente recurso se puede dar la confirmación por parte del vendedor.

Llamada:

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

Ejemplo de descuento pre-acordado:

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

Respuesta de descuento pre-acordado:

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

Ejemplo de liquidación stock Full:

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

Respuesta de liquidación stock Full:

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

Parámetros

promotion_id: identificación de la promoción.
offer_id: identificación de la oferta acordada.
promotion_type: tipo de promoción (PRE_NEGOTIATED o UNHEALTHY_STOCK).

Eliminar descuento

Con esta función puede eliminar la oferta del ítem.

Llamada:

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

Ejemplo de descuento pre-acordado:

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

Ejemplo liquidación stock Full:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLB10203040?promotion_type=UNHEALTHY_STOCK&promotion_id=P-MLB12345&offer_id=MLB10203040-f588cf87-e298-498e-82ad-285b16dd11d5'

Respuesta: Status 200 OK

Nota:

Ten en cuenta que si eliminas un descuento pre-acordado o liquidación stock Full el ítem ya no se será candidato.

Siguiente: Descuento individual