Documentación Mercado Libre

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

Documentación

Última actualización 27/06/2024

Gestionar promociones

Importante:
Ya está disponible en MLV y MEC las campañas de descuentos individuales (PRICE_DISCOUNT), oferta relámpago (LIGHTNING), ofertas del dia (DOD) y campañas tradicionales (DEAL).

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), campañas co-fondeada automatizada (SMART),campañas de precios competitivos (PRICE_MATCHING), campaña de liquidación stock Full (UNHEALTHY_STOCK) y campañas de cupones del vendedor (SELLER_COUPON_CAMPAIGN). Además de los nuevos tipos de ofertas que disponibilicemos.




Características de las promociones

Nombre de la campaña Tipo de campaña Definición de precio Sugerencia de precio Bonificación MELI Stock para participar Deadline Aprobación
Tradiconal DEAL Usuario define No No No
Co-fondeada MARKETPLACE CAMPAIGN Usuario acepta No No No
Descuento por volumen VOLUME Usuario acepta No No No
Oferta del día DOD Usuario define No Sí, informativo No No
Oferta relámpago LIGHTNING Usuario define No Sí, mandatorio No No
Descuento pre-acordado por ítem PRE_NEGOTIATED Usuario acuerda y acepta No No
Campaña del vendedor SELLER CAMPAIGN Usuario define y acepta No No No No
Campaña co-fondeada automatizada SMART Usuario acepta No No No
Campaña de precios competitivos PRICE_MATCHING Usuario acepta No No No
Campaña de liquidación stock Full UNHEALTHY_STOCK Usuario acuerda y acepta No 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)
Campaña co-fondeada automatizada
(SMART)
Campaña de precios competitivos
(PRICE_MATCHING)
Campaña de liquidación stock Full
(UNHEALTHY_STOCK)
Campaña del vendedor
(SELLER_CAMPAIGN)
MLA, MLB, MLM, MCO, MLC, MLU, MPE
MLV y MEC

Nota:
La campañas de cupones del vendedor (SELLER_COUPON_CAMPAIGN) esta disponible solo para MLB.


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, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
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, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).

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, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
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.


Delete masivo de ofertas

Puedes eliminar de forma masiva todas las ofertas que están en el ítem.

Nota:
Este delete masivo no se aplica en casos de ofertas de campañas del tipo DOD y LIGHTNING. Para estas ofertas, es necesario continuar eliminando una campaña por vez.

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

Ejemplo:

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

Respuesta:


 {
   "successful_ids": [
       {
           "offer_id": "OFFER-MLA1399846831-10000081416",
           "error": null
       },
       {
           "offer_id": "OFFER-MLA1399846831-10000081567",
           "error": null
       }
   ],
   "errors": []
}

En casos donde el ítem tenga campañas que no pueden ser eliminadas de forma masiva, la llamada tendrá una respuesta http 200, pero la respuesta contendrá los mensajes de error.


Ejemplo donde ninguna oferta puede ser eliminada:


{
   "successful_ids": [],
   "errors": [
       {
           "offer_id": "OFFER-MLA1399846831-10000081416",
           "error": "The offer of type DOD not allowed for delete."
       },
       {
           "offer_id": "OFFER-MLA1399846831-10000081828",
           "error": "The offer could not be deleted. Try again."
       }
   ]
}

Ejemplo donde las ofertas fueron eliminadas correctamente y también ocurrieron errores:


{
   "successful_ids": [
       {
           "offer_id": "OFFER-MLA1399846831-10000081416",
           "error": null
       },
       {
           "offer_id": "OFFER-MLA1399846831-10000081417",
           "error": null
       }
   ],
   "errors": [
       {
           "offer_id": "OFFER-MLA1399846831-10000081418",
           "error": "The offer of type DOD not allowed for delete."
       },
       {
           "offer_id": "OFFER-MLA1399846831-10000081419",
           "error": "The offer could not be deleted. Try again."
       }
   ]
}

Posibles errores

423_ENTITY_LOCKED: La solicitud no pudo ser procesada porque el ítem está temporalmente bloqueado para realizar solicitudes. La solicitud puede intentarse nuevamente después de unos segundos.

400_BAD_REQUEST: Cuando el formato del ítem es inválido.


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