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.

Contenidos

→Características de las promociones
→Disponibilidad de promoción por país
→Consultar las promociones disponibles para el vendedor
→Consultar ítems candidatos
→Consultar ofertas
→Consultar detalles de la promoción
↳Estado
→Consultar ítems de la promoción
→Participar en una promoción
→Consultar promociones del ítem
→Modificar ítems
→Eliminar ítems
→Asignar campañas de pruebas

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:

estados de campaña tradicional

estado de una campaña co-fondeada

estado de campaña descuento por volumen

estado de campaña con descuento pre-acordado por ítem

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

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