Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Brand Ads
Flujo técnico recomendado
- Consulta anunciante (advertiser id)
- Consulta las campañas, anuncios y keywords
- Consulta métricas de advertiser, campañas y keywords
Consultar anunciante
Los anunciantes (advertiser_id) son quienes invierten un presupuesto para la creación y distribución de anuncios publicitarios, con el objetivo de promocionar sus productos o servicios. Consulta el listado de anunciantes que tiene acceso a un usuario, según el tipo de producto que se requiera.
Parámetros obligatorios
product_id: tipo de producto. Valores disponibles: PADS (Product Ads), DISPLAY, BADS (Brand Ads).
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -H 'Api-Version: 1'
https://api.mercadolibre.com/advertising/advertisers?product_id=$PRODUCT_IDEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -H 'Api-Version: 1'
https://api.mercadolibre.com/advertising/advertisers?product_id=BADSRespuesta:
{
"advertisers": [
{
"advertiser_id": 000,
"site_id": "MLB",
"advertiser_name": "Advertiser AAA",
"account_name": "MLB - XZY"
},
{
"advertiser_id": 111,
"site_id": "MLM",
"advertiser_name": "Advertiser BBB",
"account_name": "MLM - XYZ"
},
{
"advertiser_id": 222,
"site_id": "MLA",
"advertiser_name": "Advertiser CCC",
"account_name": "MLA - XYZ"
},
{
"advertiser_id": 333,
"site_id": "MLC",
"advertiser_name": "Advertiser DDD",
"account_name": "MLC - XYZ"
}
]
}Campos de respuesta
advertiser_id: identificador del anunciante. Lo utilizarás para el resto de solicitudes.
site_id: identificador del país. Consulta la nomenclatura de los sites de Mercado Libre y sus respectivas monedas.
advertiser_name: nombre del anunciante.
account_name: nombre de la cuenta.
Tipos de campañas
Antes de consultar campañas, te recomendamos conocer los tipos de campañas. Además, puedes acceder a métricas de campañas a partir del 2023-02-09.
- Automatic: las campañas automáticas son administradas por Mercado Ads. Se ejecutará automáticamente la campaña para todos los items asociados al official_store_id del destination_id enviado y creará keywords, que no podrán ser editadas ni eliminadas, es decir, Mercado Ads administrará el inventario del advertiser y asignará las mejores keywords para sus anuncios.
- Custom: las campañas personalizadas son creadas y administradas por el usuario, donde el anunciante (advertiser) debe proveer un listado de ítems (mínimo 3, máximo 10) con los cuales configurar su anuncio y las keywords (mínimo 1, máximo 200) que son palabras clave para búsquedas en que quiere imprimirse. Luego podrá editar y eliminar estas keywords.
Buscar campañas
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaignsRespuesta:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 2
},
"campaigns": [
{
"campaign_id": 1,
"name": "campaign meli 1",
"start_date": "2024-01-01T00:06:22.000Z",
"end_date": "2024-01-01T00:06:22.000Z",
"advertiser_id": 1234,
"campaign_type": "custom",
"status": "active",
"site_id": "MLA",
"official_store_id": 12345,
"destination_id": 12345,
"headline": "esto es un headline",
"budget": {
"amount": 1111111.32,
"currency": "ARS"
},
"cpc": 100.5,
"items": [
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
],
"keywords": [
{
"campaign_id": 1,
"type": "custom",
"term": "auto",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]
}
]
}Campos de respuesta
campaign_id: Id que identifica a la campaña en el sistema.
name: nombre de la campaña.
start_date: fecha de inicio de la campaña en formato ISO-8601 con time-zone.
end_date: fecha de fin de la campaña.
advertiser_id: advertiser al que pertenece la campaña.
campaign_type: tipo de campaña: “custom” o “automatic”.
status: status de la campaña, los status posibles son “active”, “paused”, “disabled”.
site_id: país al que pertenece la campaña.
official_store_id: identificador de la Tienda Oficial sobre la que se creó la campaña.
destination_id: destination id asociado a la Tienda Oficial de la campaña.
headline: título/bajada a mostrar en el espacio publicitario de brand ads.
budget: array con información presupuestaria.
- amount: budget diario de la campaña.
- currency: moneda en la que se encuentra el budget. Para más información, consulta /currencies.
cpc: costo por click máximo de la campaña.
items: listado de ítems que formarán parte de la campaña. Aplica solo a campañas tipo custom (mínimo 3 items y máximo 10). Los ítems deben pertenecer a la tienda oficial asociada al destination provisto en el campo de destination_id.
keywords: array con información de las keywords.
- campaign_id: identificador de la campaña a la que está asociada la keyword.
- type: tipo de keyword “custom”. Próximamente, podrán ser también tipo “suggested”.
- term: el término de la keyword.
- match_type: el tipo de matcheo con el cual se utilizará la keyword. Valor posible: “phrase”. Próximamente habilitaremos valores “exact”y “broad”.
- is_negative: indica si la keyword es negativa, es decir la campaña no se imprime con la keyword. Próximamente estará habilitada, hoy is_negative solo puede ser false.
- cpc: costo por click máximo de la keyword.
Detalle de campaña
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_IDRespuesta:
{
"campaign_id": 1,
"name": "campaign meli 1",
"start_date": "2024-01-01T00:06:22.000Z",
"end_date": "2024-01-01T00:06:22.000Z",
"advertiser_id": 1234,
"campaign_type": "custom",
"status": "active",
"site_id": "MLA",
"official_store_id": 12345,
"destination_id": 12345,
"headline": "esto es un headline",
"budget": {
"amount": 1111111.32,
"currency": "ARS"
},
"cpc": 100.5,
"items": [
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
],
"keywords": [
{
"campaign_id": 1,
"keyword_id": 1,
"type": "custom",
"term": "auto",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]
}Consultar anuncios de una campaña custom
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/itemsResponse:
[
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
]Consultar keywords de campaña custom
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywordsRespuesta:
[
{
"campaign_id": 1,
"type": "custom",
"term": "auto",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]Métricas de campañas del anunciante
Parámetros obligatorios
date_from: fecha desde de la consulta en formato YYYY-MM-DD.
date_to: fecha hasta de la consulta en formato YYYY-MM-DD.
Parámetros opcionales
limit: por default 50.
offset: por default 0.
aggregation_type: tipo de agregado de la data a mostrar. Valores posibles: daily, total. Por defecto retorna ambos.
fields: campos de métricas específicos a consultar.
Filtros disponibles
status: estado de la campaña. Valores posibles: active, paused.
destination_id: id del destination de campaña.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&aggregation_type=dailyEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/12345678/brand_ads/campaigns/metrics?date_from=2024-07-01&date_to=2024-07-10&aggregation_type=dailyRespuesta:
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2024-01-08",
"site_id": "MLA",
"currency": "ARS",
"prints": 0,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
],
"summary": {
"site_id": "MLA",
"currency": "ARS",
"prints": 0,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
}Métricas por campaña y día
Parámetros obligatorios
date_from: fecha desde de la consulta en formato YYYY-MM-DD.
date_to: fecha hasta de la consulta en formato YYYY-MM-DD.
Parámetros opcionales
limit: por default 50.
offset: por default 0.
aggregation_type: tipo de agregado de la data a mostrar. Valores posibles: daily, total. Por defecto retorna ambos.
fields: campos de métricas específicos a consultar.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DDEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/101010/brand_ads/campaigns/123456/metrics?date_from=2024-07-01&date_to=2024-07-10Respuesta:
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2024-01-02",
"prints": 2026,
"site_id": "MLA",
"currency": "ARS",
"clicks": 20,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 3000.00,
"cpc": 150.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
],
"summary": {
"prints": 2026,
"clicks": 20,
"site_id": "MLA",
"currency": "ARS",
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 3000.00,
"cpc": 150.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"competitive": {
"lost_impression_share_by_budget": 0.7,
"lost_impression_share_by_ad_rank": 0.04,
"impression_share": 0.26,
"competitive_cpc": 175.0
}
}
}Métricas de keywords por campaña y días
Obtiene las métricas de keywords de cada día para una campaña específica.
Parámetros obligatorios
date_from: fecha desde de la consulta en formato YYYY-MM-DD.
date_to: fecha hasta de la consulta en formato YYYY-MM-DD.
Parámetros opcionales
limit: por default 50.
offset: por default 0.
aggregation_type: tipo de agregado de la data a mostrar. Valores posibles: daily, total. Por defecto retorna ambos.
fields: campos de métricas específicos a consultar.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywords/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DDEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/101010/brand_ads/campaigns/123456/keywords/metrics?date_from=2024-07-01&date_to=2024-07-10Respuesta:
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2024-01-08",
"keywords": [
{
"keyword": "cloruro magnesio",
"site_id": "MLA",
"currency": "ARS",
"prints": 2,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
]
}
],
"summary": [
{
"keyword": "cloruro magnesio",
"site_id": "MLA",
"currency": "ARS",
"prints": 2,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
]
}Glosario
prints (impresiones): es la cantidad de veces que se mostraron tus anuncios.
clicks: cantidad de veces que los usuarios hicieron clic en tus anuncios.
ctr (click-through rate): tasa de clics obtenidos sobre el total de impresiones.
cvr (conversion rate): tasa de conversión respecto a sus clics.
consumed_budget (inversión): cantidad de dinero efectivamente gastado para mostrar tus anuncios.
cpc (costo por clic): costo promedio que se paga por cada clic que recibieron los anuncios.
acos (advertising cost of sales): inversión ingreso/egreso, costo publicitario de ventas.
Las métricas pueden ser atribuidas:
event_time: métricas atribuidas por fecha de acción, se mostrarán asociadas a la fecha exacta en que la acción fue realizada (Ej: ventas).
touch_point: métricas atribuidas por fecha de visualización, se mostrarán asociadas a la fecha de clic o impresión visible que las generó.
- units_quantity (ventas): cantidad de veces que los usuarios realizaron una compra después de ver o hacer clic en los anuncios.
- units_amount (ingresos): valor total generado por las ventas atribuidas a tus anuncios.
- items_quantity: cantidad de ítems vendidos por atribuciones.
- ppv_conversions (vistas a páginas de producto): cantidad de vistas a las páginas de productos después de ver o hacer clic en tus anuncios.
- bookmark_conversions (bookmark): cantidad de items atribuibles que se marcaron como favoritos después de ver o hacer clic en tus anuncios.
- cart_conversions (carrito): cantidad de items atribuibles que se agregaron al carrito de compras después de ver o hacer clic en tus anuncios.
- checkout_conversions (checkout): cantidad de items atribuibles para los cuales se haya iniciado el proceso de compra después de ver o hacer clic en tus anuncios.
- leads_question_conversions: cantidad de potenciales clientes interesados en adquirir tu producto que preguntaron en tu publicación luego de hacer clic en tus anuncios.
- leads_im_conversions: cantidad de potenciales clientes interesados en adquirir tu producto que te contactaron por WhatsApp desde tu publicación luego de hacer clic en tus anuncios.
- eshop_conversions: cantidad de ventas atribuidas.
competitive: array con métricas de competitividad. Se muestran solo por nivel de campaña y reflejan su distribución de impresiones, es decir, son porcentajes de veces que se mostraron o no los anuncios en relación al 100% de veces que pudieron hacerlo. Se calculan con los datos de los últimos 7 días. Próximamente se podrá seleccionar el periodo. Las métricas pueden ser:
- lost_impression_share_by_budget (Pérdidas por presupuesto): porcentaje de pérdida, entendiendo como tal las impresiones potenciales que no se pudieron capitalizar por bajo presupuesto. Por ejemplo: si es 10, significa que la campaña perdió impresiones en un 10% de las veces en las que podría haberlas tenido, por no tener presupuesto suficiente. En estos casos, te recomendamos aumentar el presupuesto.
- lost_impression_share_by_ad_rank (Pérdidas por ranking): porcentaje de pérdida, entendiendo como tal las impresiones potenciales que no se pudieron capitalizar por bajo ranking. Por ejemplo, si el resultado es 30, la campaña perdió impresiones en un 30% de las veces en las que podría haberlas tenido, por no tener ad-rank suficiente.
El adrank se conforma por el Acos Target y el Quality Score (métrica interna, no es gestionable de forma directa). Para mejorar las impresiones ganadas por ranking, sugerimos centrar las acciones en los siguientes puntos:
Revisar el CPC máximo: lo recomendable es que te encuentres dentro del promedio de tu competencia para mejores resultados.
Verificar que la campaña esté segmentada en las palabras claves correctas: recomendamos tener diferentes campañas, así podés apuntar a palabras claves específicas en cada una.
Mejorar la calidad de publicación: la calidad de las fotografías, la descripción de tu producto e incluso las condiciones de envío pueden jugar un papel importante en tu ranking.
Cuidar la reputación: el servicio post-venta y la valoración del producto pueden diferenciarte al momento de competir. Conocé más sobre la API de Calidad de Publicaciones.
- impression_share (Impresiones ganadas): porcentaje de éxito, entendiendo como tal las impresiones efectivas, es decir, es el porcentaje de veces que la campaña ganó las subastas en que participó con esa palabra clave. Es la cantidad de impresiones obtenidas dividido la cantidad de impresiones estimadas/potenciales que podría haber tenido. Por ejemplo: si es 60%, significa que la campaña ganó y se imprimió en un 60% de las veces en las que podría haberlo hecho.
- competitive_cpc: es el CPC de la competencia.
Siguiente: Display Ads.