Developers

Documentación Mercado Libre

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

Última actualización 07/02/2024

Gestionar promociones

Importante:

A partir del 10 de enero de 2024 eliminaremos la versión anterior 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.

Con el recurso /seller-promotions puedes centralizar todos los tipos de promociones disponibles como campañas tradicionales (DEAL),campañas co-fondeadas por Mercado Libre (MARKETPLACE CAMPAIGN), descuentos individuales (PRICE DISCOUNT), ofertas relámpago (LIGHTNING), ofertas del día (DOD), descuento por volumen (VOLUME), descuento pre-acordado por item (PRE NEGOTIATED), campaña del vendedor (SELLER_CAMPAIGN) y campaña smart (SMART). Además de los nuevos tipos de ofertas que disponibilicemos.

Características de las promociones

Tipo de campaña	Nombre	Definición de precio	Sugerencia de precio	Bonificación MELI	Stock para participar	Deadline	Aprobación
Tradiconal	DEAL	Usuario define	No	No	No	Sí	Sí
Co-fondeada	MARKETPLACE CAMPAIGN	Usuario acepta	No	Sí	No	Sí	No
Descuento por volumen	VOLUME	Usuario acepta	No	Sí	No	Sí	No
Oferta del día	DOD	Usuario define	Sí	No	Sí, informativo	No	No
Oferta relámpago	LIGHTNING	Usuario define	Sí	No	Sí, mandatorio	No	No
Descuento pre-acordado por ítem	PRE_NEGOTIATED	Usuario acuerda y acepta	No	Sí	Sí	Sí	No
Campaña del vendedor	SELLER CAMPAIGN	Usuario define y acepta	No	No	No	Sí	No
Campaña Smart	SMART	Usuario acepta	No	Sí	No	Sí	No

Disponibilidad por país

Sitio	Campañas tradicionales (DEAL)	Campaña co-fondeada (MARKETPLACE CAMPAIGN)	Descuento individual (PRICE DISCOUNT)	Descuento por volumen (VOLUME)	Descuento pre-acordado por ítem (PRE_NEGOTIATED)	Oferta del día (DOD)	Oferta relámpago (LIGHTNING)
MLA, MLB, MLM, MCO, MLC, MLU, MPE
MLV

Promociones del vendedor

Recuerda que un usuario puede tener más de una invitación y de diferentes tipos.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/$USER_ID?app_version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/1356551933?app_version=v2

Respuesta:

{
      "results": [
          {
              "id": "P-MLB1806015",
              "type": "MARKETPLACE_CAMPAIGN",
              "status": "started",
              "start_date": "2023-04-20T02:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "Campanha de teste v2",
              "benefits": {
                  "type": "REBATE",
                  "meli_percent": 5,
                  "seller_percent": 25
              }
          },
          {
              "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
              }
          },
          {
              "id": "P-MLB1806019",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-20T03:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "deals de teste v2"
          },
          {
              "id": "P-MLB1809008",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-21T21:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "Deals de test v2"
          },
          {
              "id": "P-MLB1809009",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-21T23:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "campanha de teste"
          }
      ],
      "paging": {
          "offset": 0,
          "limit": 50,
          "total": 5
      }
   }

Campos de la respuesta

id: código de identificación de la oferta.
type: tipo de la oferta (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRE NEGOTIATED, SELLER_CAMPAIGN, SMART).
status: Estado
start_date: fecha de inicio de la oferta.
finish_date: fecha de fin de la oferta.
deadline_date: plazo máximo para aceptar la invitación.
name: nombre de la promoción.
deadline_date: plazo máximo para incorporar los ítems a la promoción.
benefits: configuración de beneficios de la promoción.

Consultar items candidatos

El recurso /seller-promotions/candidates permite identificar los ítems invitados a participar de una promoción. Siempre que un ítem obtiene el status de candidate en una promoción se envía una notificación con el candidate_id, con este recurso es posible identificar el ítem, la promoción y el status.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID?app_version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663?app_version=v2

Respuesta:

{    
    "id": "CANDIDATE-MLB1254949426-803130663",    
    "item_id": "MLB1254949426",    
    "promotion_id": "P-MLB4629001",    
    "type": "MARKETPLACE_CAMPAIGN",    
    "status": {        
    "id": "candidate"    
  } 
}

Campos de respuesta

id: código de identificación del candidato.

item_id: ítem asociado al candidato.

promotion_id: id de la promoción.

type: tipo de promoción (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART).

status: estado del candidato.

Nota:

El id del candidato se obtiene a través de la notificación del topic public candidate.

Consultar ofertas

El recurso /seller-promotions/offers permite identificar cambios en la oferta de un ítem. Todos los cambios se envían por medio de notificaciones con el offer_id, es posible identificar el item, la promoción y el estado.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID?app_version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792?app_version=v2

Respuesta:

{    
    "id": "OFFER-MLB1970246686-42701792",    
    "item_id": "MLB1970246686",    
    "promotion_id": "P-MLB3329001",    
    "type": "DEAL",    
    "status": {        
    "id": "ACTIVE"    
  } 
}

Campos de la respuesta

id: código de identificación de la oferta.
item_id: ítem asociado a la oferta.
promotion_id: id de la promoción.
type: tipo de promoción (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART).
status: estado de la oferta. (programmed, active, e inactive).

Nota:

El id de la oferta lo obtienes por medio de una notificación del tópico public offers.

Consultar detalles de la promoción

Realiza la siguiente consulta para acceder a los detalles particulares de una campaña tradicional, campaña co-fondeada y para los descuentos por volumen.

Llamada:

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

Para obtener más información, acceda a las documentaciones de cada campaña.

Estado

A continuación puedes encontrar los posibles estados que pueden tener los distintos tipos de promociones:

Consultar ítems de la promoción

Nota:

En esta consulta se obtiene el estado del ítem en la campaña.

Para conocer los ítems que forman parte de una determinada oferta puedes realizar la siguiente consulta:

Llamada:

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

Además, puedes consultar ítems de una campaña:

Filtros

Puedes aplicar filtros por ítem o status.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?promotion_type=$PROMOTION_TYPE&status=$STATUS&item_id=$ITEM_ID&app_version=v2

Ejemplo de filtro por ítem:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&item_id=MLA604400000&app_version=v2

Respuesta:

 {
   "results": [
       {
           "id": "MLA604400000",
           "status": "started",
           "price": 23968,
           "original_price": 28549
       }
   ],
   "paging": {...}
}

Ejemplo de filtro por status started:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' /seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&status=started&app_version=v2

Respuesta:

  {
   "results": [
       {
            "id": "MLA639970000",
            "status": "started",
            "price": 4037,
            "original_price": 4427
        },
        {
            "id": "MLA639973333",
            "status": "started",
            "price": 6007,
            "original_price": 6587
        },
],
   "paging": [...]
}

Nota:

Los status que se pueden filtrar son: started, pending y candidate.

Paginación

Importante:

- El query param para enviar este valor comienza a llamarse search_after y no más searchAfter. Pero se continuará aceptando searchAfter por un tiempo.
- Se unifica el valor de search_after para que solo utilice valores distintos, eliminando la ambigüedad.

Para realizar la paginación deberás utilizar el parámetro search_after.
En la respuesta del GET, devolvemos el parámetro searchAfter, el cual servirá para poder recorrer los resultados. Para ello se deberá recuperar dicho ID y realizar la siguiente request con el query param search_after={search_after}. Este ID es un string, por eso tienen que aceptar el string y usarlo luego en sus pegadas.

Nota:

Si no utilizas el parámetro de limit, se retornarán por defecto 50 ítems del total. Puedes agregar un limit máximo de 50.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&app_version=v2&limit=50&search_after={$SEARCH_AFTER}'

Ejemplo de paginación:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB13451002MLB9377/items?promotion_type=DEAL&app_version=v2&limit=50&search_after=d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca1b1a42'

Respuesta:

"results": [
       {
           "id": "MLB2674512266",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674506199",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674506138",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674505931",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674505924",
           "status": "candidate",
           "price": 0,
           "original_price": 0
 
 […]
 
 "paging": {
       "searchAfter":
"d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca3b5b55",
       "limit": 50,
       "total": 14424
   }
}

Consideraciones

Se devolverá search_after en todas las páginas, excepto en la última.
La única forma de avanzar en la respuesta (paginar) es a través del uso de este parámetro.
Al iterar los resultados, cada llamada retornará el search_after que deberá ser utilizado en la siguiente llamada.
Siempre se debe utilizar el search_after que fue proporcionado por la respuesta del request, ya que este puede cambiar y expirar (tienen un TTL de 5 minutos).
No es posible realizar paginados hacia atrás.

Cómo participar

Puedes participar en distintos tipos de promociones e incluso ofrecer un descuento individual para los ítems:

Consultar promociones del ítem

Aca puede obtener todas las promociones que tiene el item y los status de las promociones en el momento de la consulta.

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

Ejemplo:

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

Respuesta:

[
      {
          "type": "PRICE_DISCOUNT",
          "status": "candidate",
          "price": 4000,
          "start_date": "2023-04-26T00:00:00",
          "finish_date": "2023-05-10T00:00:00"
      },
      {
          "type": "DOD",
          "status": "candidate",
          "price": 4000,
          "start_date": "2023-04-28T00:00:00",
          "finish_date": "2023-04-28T23:59:59"
      },
      {
          "id": "P-MLB1817004",
          "type": "MARKETPLACE_CAMPAIGN",
          "status": "pending",
          "start_date": "2023-04-27T23:00:00Z",
          "finish_date": "2023-06-01T02:00:00Z",
          "deadline_date": "2023-06-01T01:00:00Z",
          "name": "Campanha teste 10",
          "benefits": {
              "type": "REBATE",
              "meli_percent": 3,
              "seller_percent": 27
          }
      },
      {
          "id": "MLB1345",
          "type": "DEAL",
          "status": "pending",
          "start_date": "2023-04-27T23:00:00-03:00",
          "finish_date": "2023-05-31T23:00:00-03:00",
          "name": "teste 20"
      },
      {
          "id": "C-MLB300",
          "type": "SELLER_CAMPAIGN",
          "sub_type": "FIXED_PERCENTAGE",
          "status": "started",
          "price": 4250,
          "top_price": 3500,
          "start_date": "2023-04-27T00:00:00",
          "finish_date": "2023-05-05T23:59:59",
          "name": "camp del seller 1"
      },
      {
          "id": "P-MLB1812010",
          "type": "SMART",
          "status": "started",
          "name": "test-smart-2",
          "offers": [
              {
                  "id": "OFFER-MLB3538191898-177685",
                  "original_price": 5000,
                  "new_price": 3000,
                  "prime_price": null,
                  "status": "active",
                  "start_date": "2023-04-26T11:40:00Z",
                  "end_date": "2023-05-30T15:47:00Z",
                  "benefits": {
                      "type": "REBATE",
                      "meli_percent": 20,
                      "seller_percent": 20
                  }
              }
          ]
      },
      {
          "id": "C-MLB302",
          "type": "SELLER_CAMPAIGN",
          "sub_type": "FLEXIBLE_PERCENTAGE",
          "status": "candidate",
          "start_date": "2023-04-27T12:04:00",
          "finish_date": "2023-05-05T00:00:00",
          "name": "camp del seller 2"
      }
   ]

Modificar ítems

Puedes modificar los ítems que están participando en una determinada oferta:

Nota:

Para editar los descuentos individuales (PRICE DISCOUNT), las ofertas del día (DOD) y las ofertas relámpago (LIGHTNING) debes eliminar la promoción y aplicarla nuevamente.

Eliminar ítems

Puedes eliminar los ítems que están participando en una determinada oferta:

Asignar campañas de pruebas

Para realizar pruebas con campañas de test, envíanos los datos de tu usuario y/o ítems en el soporte por site.

Recuerda que tanto los usuarios como los ítems deben ser de test.

Nota:

Debes agregar el parámetro version=test dentro de las llamadas para interactuar con las promociones de test.

Next post: Campañas co-fondeadas