Gestionar promociones

Documentación Mercado Libre

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

Última actualización 24/08/2023

Gestionar promociones

Importante:

A partir del 15 de agosto de 2023 eliminaremos la versión anterior de los recursos, 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, finished, pending y candidate.

Paginación

Para realizar la paginación deberás utilizar el parámetro searchAfter. El valor enviado en este parámetro es siempre el último id del ítem retornado en la llamada anterior.

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&searchAfter=$ITEM_ID&app_version=v2'

Ejemplo:

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

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": "MLB2674512267",
       "limit": 50,
       "total": 14424
   }
}

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