Última actualización 15/03/2023

Gestionar promociones

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). 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
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 por volumen VOLUME Usuario acepta No Sí No Sí No
Descuento pre-acordado por ítem PRE_NEGOTIATED Usuario acuerda y acepta No Sí Sí Sí No


Disponibilidad de promoción 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

Consultar las promociones disponibles para el 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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/631366846

Respuesta:

{
  "results": [
    {
      "id": "MLB686",
      "type": "DEAL",
      "status": "started",
      "start_date": "2020-02-04T17:50:00Z",
      "finish_date": "2022-10-31T17:20:00Z",
      "deadline_date": "2020-01-30T02:00:00Z",
      "name": "HOTSALE"
    },
    {
           "id": "DOD-MLB1000",
           "type": "DOD",
           "status": "started",
           "start_date": "2000-01-01T00:00:00.000Z"
       },
       {
           "id": "LGH-MLB1000",
           "type": "LIGHTNING",
           "status": "started",
           "start_date": "2000-01-01T00:00:00.000Z"
       },
       {
           "id": "P-MLB379009",
           "type": "VOLUME",
           "status": "started",
           "start_date": "2021-03-25T16:40:00Z",
           "finish_date": "2021-04-30T18:00:00Z",
           "name": "test volume MLB",
           "benefits": {
               "type": "VOLUME",
               "meli_percent": 8,
               "seller_percent": 17,
               "name": "4x3",
               "buy_quantity": 4,
               "pay_quantity": 3,
               "item_discount_percent": 25
           }
       },
       {
           "id": "P-MLB380001",
           "type": "VOLUME",
           "status": "started",
           "start_date": "2021-03-25T19:00:00Z",
           "finish_date": "2021-04-30T18:00:00Z",
           "name": "test volume MLB BNSP",
           "benefits": {
               "type": "VOLUME",
               "meli_percent": 10,
               "seller_percent": 30,
               "name": "buy 4 save 40%",
               "buy_quantity": 4,
               "item_discount_percent": 40
           }
       },
       {
           "id": "P-MLB380002",
           "type": "VOLUME",
           "status": "started",
           "start_date": "2021-03-25T19:30:00Z",
           "finish_date": "2021-04-30T18:00:00Z",
           "name": "test volume MLB SPONTH",
           "benefits": {
               "type": "VOLUME",
               "meli_percent": 8,
               "seller_percent": 17,
               "name": "save 50% on 2nd",
               "buy_quantity": 2,
               "item_discount_percent": 25
           }
       },
       {
           "id": "P-MLB382001",
           "type": "MARKETPLACE_CAMPAIGN",
           "status": "started",
           "start_date": "2021-03-25T22:36:00Z",
           "finish_date": "2021-04-30T18:00:00Z",
           "name": "test cofondeada",
           "benefits": {
               "type": "REBATE",
               "meli_percent": 2,
               "seller_percent": 8
           }
       },
       {
           "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"
       }
  ],
  "paging": {
    "offset": 0,
    "limit": 50,
    "total": 7
  }
}

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).
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

Ejemplo:

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

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).

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

Ejemplo:

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

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).
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

Conoce más detalles sobre campaña tradicional , campaña co-fondeada (marketplace campaign) y descuento por volumen.


Estado

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


Consultar ítems de la promoción

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

Además, puedes consultar ítems de una campaña tradicional, de una campaña co-fondeada y los items que pueden acceder a descuento por volumen.
Aquí puedes consultar los ítems de una oferta del día, de una oferta relámpago y estado de campaña con descuento pre-acordado por ítem

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

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

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

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'

Ejemplo: 

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

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


Participar de una promoción

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

Consultar promociones del ítem

Para ofertas de tipo DEALS solo devolveremos los ítems con estado aprobado (status=approved).
No aprobaremos campañas con ítems test, es decir, quedarán con estado pending_approval y no mostraremos el precio con promoción.

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA876768946

Respuesta:

[
  {
    "id": "2864-MLB876768946",
    "type": "PRICE_DISCOUNT",
    "status": "started",
    "price": 700,
    "top_price": 650,
    "start_date": "2020-09-09T00:00:00",
    "finish_date": "2020-09-15T00:00:00"
  },
  {
    "id": "MLB686",
    "type": "DEAL",
    "status": "started",
    "price": 680,
    "start_date": "2021-03-04T17:50:00Z",
    "finish_date": "2021-10-31T17:20:00Z",
    "deadline_date": "2021-03-03T02:00:00Z",
    "name": "HOT SALE"
  },
  {
    "id": "P-MLB119001",
    "type": "MARKETPLACE_CAMPAIGN",
    "status": "started",
    "start_date": "2021-04-15T18:37:40.881Z",
    "finish_date": "2021-04-30T18:37:40.881Z",
    "name": "10% en herramientas"
    "benefits": {
           "type": "REBATE",
           "meli_percent": 2,
           "seller_percent": 8
       }
  },
  {
       "id": "1504782-MLA874447795",
       "type": "DOD",
       "status": "started",
       "price": 789,
       "start_date": "2021-04-19T00:00:00",
       "finish_date": "2021-04-19T23:59:59.999999999"
   },
   {
       "id": "1499515-MLA915978647",
       "type": "LIGHTNING",
       "status": "started",
       "price": 745,
       "start_date": "2021-04-19T06:00:00",
       "finish_date": "2021-04-19T12:00:00",
       "remaining_stock": 3
   },
   {
       "id": "P-MLB379009",
       "type": "VOLUME",
       "status": "started",
       "start_date": "2021-03-25T16:40:00Z",
       "finish_date": "2021-04-30T18:00:00Z",
       "name": "test volume MLB",
       "benefits": {
           "type": "VOLUME",
           "meli_percent": 8,
           "seller_percent": 17,
           "name": "4x3",
           "buy_quantity": 4,
           "pay_quantity": 3,
           "item_discount_percent": 25
       }
   },
   {
       "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
               }
           }
       ]
   }

]

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 siguiente formulario.
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