Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
Product Ads
Tipos de campaña y ACOS Objetivo
Cuando eliges una estrategia de campaña estás dando a la plataforma información acerca de cómo invertir tu presupuesto. Cada estrategia tiene un rango porcentual de ACOS Objetivo. Esta métrica le sirve al algoritmo para definir cuál será la puja y cómo invertir el dinero de tu presupuesto. Product Ads buscará siempre que pagues lo mínimo posible para ganarle a tu competencia. Por ejemplo, si el ACOS Objetivo de tu campaña es 10%, el algoritmo de Product Ads intentará que al invertir $1 puedas generar $10 de ingresos. O, en otras palabras, que para generar $10 gracias a tus anuncios, sólo tengas que invertir $1.
Tipo de campaña | Objetivo | Publicación recomendada |
---|---|---|
Profitability | Rentabilidad: la plataforma mostrará menos anuncios pero a usuarios con mayor probabilidad de que compren el producto anunciado. | Publicaciones más vendidas en Mercado Libre. |
Increase | Crecimiento: busca un equilibrio entre rentabilidad y visibilidad. Aquí buscarás gastar un valor intermedio para aparecer más veces, pero no tanto como para comprometer tus ganancias. | Productos de mediana rotación. Con un buen nivel de ventas en Mercado Libre, pero que no son los más vendidos. |
Visibility | Visibilidad: ideal para invertir más en publicidad a cambio de mostrar anuncios a la mayor cantidad posible de usuarios. | Nuevas publicaciones. |
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_ID
Ejemplo:
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=PADS
Respuesta:
{
"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.
Detalle de un anuncio
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/product_ads/items/$ITEM_ID
Respuesta:
{
"item_id": "MLM12345678",
"campaign_id": 0,
"price": 16999.0,
"title": "Pantalla Samsung Led Smart Tv De 65 Pulgadas 4k/uhd",
"status": "X",
"has_discount": false,
"catalog_listing": true,
"logistic_type": "default",
"listing_type_id": "gold_pro",
"domain_id": "MLM-TELEVISIONS",
"date_created": "2024-03-15T14:41:47Z",
"buy_box_winner": false,
"tags": [],
"channel": "marketplace",
"official_store_id": 111,
"brand_value_id": "223",
"brand_value_name": "Marca",
"condition": "new",
"current_level": "unknown",
"deferred_stock": false,
"picture_id": "ABCD_12345_XS",
"thumbnail": "http://http2.mlstatic.com/D_870627-1111.jpg",
"permalink": "https://articulo.mercadolibre.com.mx/MLM111111-2222-3333-4kuhd-_JM",
"recommended": false,
"metrics_summary": {
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}
Métricas de campañas
Parámetros opcionales
limit: límite de elementos a mostrar
offset: atributo de paginado de los resultados, permite recorrer las páginas de la lista desde el 0 hasta el múltiplo del total de elementos con el límite por página.
date_from: fecha desde (YYYY-MM-DD). Se valida que esté presente si se solicitan metrics.
date_to: fecha hasta (YYYY-MM-DD). Se valida que esté presente si se solicitan metrics.
metrics: lista separada por coma (Ej. clicks, prints). Indica los campos que serán retornados en la respuesta. Valores posibles:
- clicks, prints, ctr, cost, cost_usd, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, cvr, roas, sov, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount, total_amount
aggregation: agregación por la cual se presentarán los resultados. Por defecto, sum.
aggregation_type: Tipo de agregación en la cual se presentarán los resultados. Por defecto, campaign.
metrics_summary: solicitas sumarizado de métricas. Debe usarse en conjunto con metrics. Por defecto, false.
Filtros disponibles
Para utilizar los filtros debes seguir la estructura ?filters[nombre del filtro]= valor.
campaign_ids: filtro por id de campañas separado por comas.
campaign_id: filtro por id de una campaña, se obtienen todos los ítems que han estado en la campaña para el rango de fechas.
status: estado de las campañas, separado por comas. Valores disponibles: active, paused, deleted.
channel: canal de las campañas. Puede ser marketplace o mshops.
Search y métricas de campañas
Obtén todas las campañas de un anunciante y además sus métricas correspondientes.
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/campaigns?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount
Respuesta:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 1
},
"results": [
{
"id": 0,
"name": "Crecimiento A",
"status": "active",
"budget": 0.00,
"currency_id": "ARS",
"last_updated": "2024-04-08T16:09:13.000Z",
"date_created": "2024-04-08T16:09:13.000Z",
"acos_target": 99.10,
"strategy": "profitability",
"acos_top_search_target": 99.10,
"channel": "marketplace"
"metrics": {
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
}
}
]
}
Métricas diarias de campañas
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/campaigns?limit=2&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&aggregation_type=DAILY
Respuesta:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 2
},
"results": [
{
"date": "2024-01-01",
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
},
{
"date": "2024-01-01",
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
}
]
}
Métricas sumarizadas de campañas
Utiliza el mismo endpoint para consultar métricas de campañas adicionando el parámetro metrics_summary=true.
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/campaigns?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&metrics_summary=true
Respuesta:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 1
},
"results": [
{
"id": 0,
"name": "Crecimiento A",
"status": "active",
"budget": 0.00,
"currency_id": "ARS",
"last_updated": "2024-04-08T16:09:13.000Z",
"date_created": "2024-04-08T16:09:13.000Z",
"acos_target": 99.10,
"strategy": "profitability",
"acos_top_search_target": 99.10,
"channel": "marketplace"
"metrics": {
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
}
}
],
"metrics_summary":
{
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
}
}
Detalle y métricas de una campaña
Parámetros opcionales
date_from: fecha desde (YYYY-MM-DD). Se valida que esté presente si se solicitan campos metrics.
date_to: fecha hasta (YYYY-MM-DD). Se valida que esté presente si se solicitan campos metrics.
metrics: lista separada por coma (Ej clicks,prints) indica los campos que serán retornados en la respuesta. Valores disponibles:
- clicks, prints, ctr, cost, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, cvr, roas, sov, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount, total_amount, impression_share, top_impression_share, lost_impression_share_by_budget, lost_impression_share_by_ad_rank, acos_benchmark.
aggregation: agregación por la cual se presentarán los resultados. Default: sum.
aggregation_type: tipo de agregación en la cual se presentarán los resultados. Default: campaign.
Filtros disponibles
channel: canal de las campañas. Puede ser marketplace o mshops.
Ejemplo:
curl GET -H 'api-version: 2' -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads/campaigns/$CAMPAIGN_ID?date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount,impression_share,top_impression_share,lost_impression_share_by_budget,lost_impression_share_by_ad_rank,acos_benchmark
Respuesta:
{
"id": 0,
"name": "Crecimiento A",
"status": "active",
"budget": 0.00,
"currency_id": "ARS",
"last_updated": "2024-04-08T16:09:13.000Z",
"date_created": "2024-04-08T16:09:13.000Z",
"acos_target": 99.10,
"strategy": "profitability",
"acos_top_search_target": 99.10,
"channel": "marketplace"
"metrics": {
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
"impression_share": 0,
"top_impression_share": 0,
"lost_impression_share_by_budget": 0.01,
"lost_impression_share_by_ad_rank": 0.01,
"acos_benchmark": 123
}
}
Métricas diarias de una campaña
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/product_ads/campaigns/$CAMPAIGN_ID?date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount,impression_share,top_impression_share,lost_impression_share_by_budget,lost_impression_share_by_ad_rank,acos_benchmark&aggregation_type=DAILY
Respuesta:
{
[
{
"date": "2024-01-01",
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01,
"impression_share": 0,
"top_impression_share": 0,
"lost_impression_share_by_budget": 0.01,
"lost_impression_share_by_ad_rank": 0.01,
"acos_benchmark": 123
}
]
}
Métricas de anuncios
Parámetros opcionales
limit: límite de elementos a mostrar.
offset: atributo de paginado de los resultados, permite recorrer las páginas de la lista desde el 0 hasta el múltiplo del total de elementos con el límite por página.
date_from: fecha desde (YYYY-MM-DD). Validamos que esté presente si se solicitan campos metrics.
date_to: fecha hasta (YYYY-MM-DD). Validamos que esté presente si se solicitan campos metrics.
metrics: lista separada por coma (Ej clicks,prints) indica los campos que serán retornados en la respuesta. Valores posibles:
- clicks, prints, cost, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount, total_amount.
sort: ordenamiento de la consulta, asc y desc.
sort_by: nombre del atributo por el cual se va a realizar el ordenamiento.
aggregation: agregación por la cual se presentarán los resultados. Default: sum.
aggregation_type: tipo de agregación en la cual se presentarán los resultados: DAILY, item. Default: item.
metrics_summary: sumariza las métricas y debes usarlo en combinación con metrics. Default false.
Filtros disponibles
Para utilizar los filtros debes seguir la estructura ?filters[nombre del filtro]= valor.
item_id: Id del anuncio. Uno o más, separados por coma.
statuses: status de ads. Valores disponibles: active, paused, hold, idle, delegated, revoked por lo general se filtra por active, paused e idle.
- hold: el item está deshabilitado en publicidad esto resultado de que el item a nivel marketplace está pausado o sin stock
- idle: el item está disponible para tener publicidad pero no está en ninguna campaña de publicidad.
- delegated: significa que de cara al owner que consulta el item está delegado a otro advertiser. Es decir, si bien el owner (seller) puede ser el dueño del ítem, ya no tiene potestad para operar sobre él porque están "prestados" a otro advertiser.
- revocado: significa que de cara al advertiser al que le fueron prestado los items, este advertiser los devolvió al dueño por lo que ya no tiene potestad para operar sobre esos items.
channel: canal de venta 'marketplace' (Mercado Libre) o 'mshops' (Mercado Shops).
price: precio.
buy_box_winner: el ítem asociado es el ganador de Catálogo. Conoce más sobre Competencia en Catálogo.
condition: condición del ítem asociado.
current_level: reputación del ítem asociado.
deferred_stock: stock del ítem asociado.
domains: dominio del ítem asociado.
logistic_types: tipo de logística del ítem asociado.
listing_types: tipo de listado del ítem asociado.
official_stores: tienda oficial del ítem asociado.
recommended: el anuncio es recomendado por Product Ads. Según nuestros modelos, tiene buen rendimiento y si se le activa la publicidad, las ventas se verán potenciadas.
campaign_id: obtén todos los anuncios que ha tenido una campaña en un período de tiempo.
campaigns: listado de campañas separados por coma.
brand_value_id: identificador de marca.
brand_value_name: nombre de la marca.
Search y métricas de todos los anuncios
Obtén todos los anuncios y métricas correspondientes a estos.
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/items?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount
Respuesta:
{
"paging": {
"offset": 0,
"last_item_id": null,
"total": 387,
"limit": 1
},
"results": [
{
"item_id": "MLM12345678",
"campaign_id": 0,
"price": 16999.0,
"title": "Pantalla Samsung Led Smart Tv De 65 Pulgadas 4k/uhd",
"status": "active",
"has_discount": false,
"catalog_listing": true,
"logistic_type": "default",
"listing_type_id": "gold_pro",
"domain_id": "MLM-TELEVISIONS",
"date_created": "2024-03-15T14:41:47Z",
"buy_box_winner": false,
"tags": [],
"channel": "marketplace",
"official_store_id": 111,
"brand_value_id": "222",
"brand_value_name": "Marca",
"condition": "new",
"current_level": "unknown",
"deferred_stock": false,
"picture_id": "ABCD_12345_XS",
"thumbnail": "http://http2.mlstatic.com/D_870627-MLA111111_022024-I.jpg",
"permalink": "https://articulo.mercadolibre.com.mx/MLM-12345678-pulgadas-4kuhd-_JM",
"recommended": false,
"metrics": {
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}
]
}
Métricas diarias de anuncios
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/items?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&aggregation_type=DAILY
Respuesta:
{
"paging": {
"offset": 0,
"last_item_id": null,
"total": 387,
"limit": 1
},
"results": [
{
"date": "2023-01-01",
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
]
}
Métricas sumarizada de anuncios
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/product_ads/items?limit=1&offset=0&date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&metrics_summary=true
Respuesta:
{
"paging": {
"offset": 0,
"last_item_id": null,
"total": 387,
"limit": 1
},
"results": [
{
"item_id": "MLM2945612374",
"campaign_id": 0,
"price": 16999.0,
"title": "Pantalla Samsung Led Smart Tv De 65 Pulgadas 4k/uhd",
"status": "delegated",
"has_discount": false,
"catalog_listing": true,
"logistic_type": "default",
"listing_type_id": "gold_pro",
"domain_id": "MLM-TELEVISIONS",
"date_created": "2024-03-15T14:41:47Z",
"buy_box_winner": false,
"tags": [],
"channel": "marketplace",
"official_store_id": 111,
"brand_value_id": "222",
"brand_value_name": "Marca",
"condition": "new",
"current_level": "unknown",
"deferred_stock": false,
"picture_id": "ABCD_12345_XS",
"thumbnail": "http://http2.mlstatic.com/D_870627-MLA74798069591_022024-I.jpg",
"permalink": "https://articulo.mercadolibre.com.mx/MLM-2945696974-pantalla-samsung-led-smart-tv-de-65-pulgadas-4kuhd-_JM",
"recommended": false,
"metrics": {
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}
],
"metrics_summary": {
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}
Métricas de un anuncio
Parámetros opcionales
date_from: fecha desde (YYYY-MM-DD). Validamos que esté presente si se solicitan campos metrics.
date_to: fecha hasta (YYYY-MM-DD). Validamos que esté presente si se solicitan campos metrics.
metrics: lista separada por coma (Ej clicks, prints). Indica los campos que serán retornados en la respuesta. Valores posibles:
- clicks, prints, ctr, cost, cpc, acos, organic_units_quantity, organic_units_amount, organic_items_quantity, direct_items_quantity, indirect_items_quantity, advertising_items_quantity, cvr, roas, sov, direct_units_quantity, indirect_units_quantity, units_quantity, direct_amount, indirect_amount, total_amount.
aggregation: agregación por la cual se presentarán los resultados. Default: sum.
aggregation_type: tipo de agregación en la cual se presentarán los resultados: DAILY, item. Default: item.
channel: canal del ítem, mshops o marketplace. Valor por defecto: marketplace.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/product_ads/items/$ITEM_ID?date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount
Respuesta:
{
"item_id": "MLM2945612374",
"campaign_id": 0,
"price": 16999.0,
"title": "Pantalla Samsung Led Smart Tv De 65 Pulgadas 4k/uhd",
"status": "X",
"has_discount": false,
"catalog_listing": true,
"logistic_type": "default",
"listing_type_id": "gold_pro",
"domain_id": "MLM-TELEVISIONS",
"date_created": "2024-03-15T14:41:47Z",
"buy_box_winner": false,
"tags": [],
"channel": "marketplace",
"official_store_id": 111,
"brand_value_id": "222",
"brand_value_name": "Marca",
"condition": "new",
"current_level": "unknown",
"deferred_stock": false,
"picture_id": "ABCD_12345_XS",
"thumbnail": "http://http2.mlstatic.com/D_870627-MLA74798069591_022024-I.jpg",
"permalink": "https://articulo.mercadolibre.com.mx/MLM-2945696974-pantalla-samsung-led-smart-tv-de-65-pulgadas-4kuhd-_JM",
"recommended": false,
"metrics_summary": {
"clicks": 0,
"prints": 0,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
}
Métricas diarias de un anuncio
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/product_ads/items/$ITEM_ID?date_from=2024-01-01&date_to=2024-02-28&metrics=clicks,prints,ctr,cost,cpc,acos,organic_units_quantity,organic_units_amount,organic_items_quantity,direct_items_quantity,indirect_items_quantity,advertising_items_quantity,cvr,roas,sov,direct_units_quantity,indirect_units_quantity,units_quantity,direct_amount,indirect_amount,total_amount&aggregation_type=DAILY
Respuesta:
{
"results": [
{
"date": "2023-01-01",
"clicks": 0,
"prints": 0,
"ctr": 0.01,
"cost": 0.01,
"cpc": 0.01,
"acos": 0.01,
"organic_units_quantity": 0,
"organic_units_amount": 0,
"organic_items_quantity": 0,
"direct_items_quantity": 0,
"indirect_items_quantity": 0,
"advertising_items_quantity": 0,
"cvr": 0,
"roas": 0,
"sov": 0,
"direct_units_quantity": 0,
"indirect_units_quantity": 0,
"units_quantity": 0,
"direct_amount": 0.01,
"indirect_amount": 0.01,
"total_amount": 0.01
}
]
}
Glosario
total: total de registros obtenidos.
offset: valor por defecto: 0.
limit: límites de elementos en la lista de campañas. Por defecto: 50.
results: resultados obtenidos.
id: identificador del anuncio o campaña.
budget: promedio diario del presupuesto (mensual) de la campaña, es decir, si el presupuesto no queda consumido durante el día se usará el restante en los días siguientes hasta que finalice el mes.
last_updated: fecha de última modificación de la campaña.
date_created: fecha de creación de la campaña.
price: precio del artículo asociado.
title: nombre de la publicación.
has_discount: si cuenta con descuento. Este valor se identifica en base a la diferencia entre los campos regular amount y amount entregado por Prices API.
catalog_listing: es una publicación de catálogo.
logistic_type: tipo de logística para el envío del artículo.
listing_type_id: identificador del tipo de publicación.
domain_id: dominio.
date_created: fecha de creación del anuncio.
official_store_id: identificador de la tienda oficial.
buy_box_winner: es ganador de Catálogo.
channel: canal de la campaña (puede ser marketplace o mshops).
campaign_id: identificador de la campaña.
condition: condición del artículo.
current_level: reputación.
deferred_stock: stock de producto disponible. Un item con manufacturing_time (tiempo de disponibilidad) hace que el anuncio no se muestre, se priorizan entonces los anuncios que tengan stock inmediato.
thumbnail: enlace a la imagen miniatura.
permalink: enlace a la publicación.
brand_value_id: identificador de la marca asociada al ítem.
brand_value_name: nombre de la marca asociada al ítem.
status: estado del anuncio o campaña.
recommended: el anuncio es recomendado.
metrics: métricas del artículo o campaña.
clicks: clicks de la campaña.
prints: cantidad de impresiones (veces en las que se muestra el anuncio).
sov: porcentaje de ventas por publicidad sobre ventas totales.
clicks: clicks de la campaña.
ctr: tasa de clicks.
cost: inversión de la campaña.
cpc: costo por click.
acos: porcentaje de inversión en publicidad sobre los ingresos obtenidos.
Ventas sin publicidad
- organic_units_quantity: cantidad de unidades vendidas sin publicidad.
- organic_units_amount: monto de ventas de órdenes orgánicas.
- organic_items_quantity: cantidad de ventas sin publicidad.
Ventas con publicidad
- Ventas directas
- direct_items_quantity: cantidad de ventas directas por publicidad.
- direct_units_quantity: cantidad de unidades vendidas en ventas directas.
- direct_amount: suma del valor de las ventas directas obtenidas de tu Product Ad, en moneda local.
- Ventas indirectas
- indirect_items_quantity: cantidad de ventas indirectas por publicidad.
- indirect_units_quantity: cantidad de unidades vendidas en ventas asistidas.
- indirect_amount: suma del valor de las ventas asistidas obtenidas de tu Product Ad, en moneda local.
advertising_items_quantity: cantidad de ventas por publicidad.
cvr: tasa de conversión.
roas: retorno sobre el gasto publicitario.
units_quantity: cantidad de ventas totales.
total_amount: suma del valor de las ventas obtenidas de tu Product Ad, en moneda local.
impression_share: porcentaje de veces que se muestran los anuncios considerando todas las veces que pueden ser mostrados.
top_impression_share: cantidad de subastas ganadas en las primeras posiciones del search entre la cantidad de subastas en las que pudo participar.
lost_impression_share_by_budget: porcentaje de veces que no se muestran los anuncios considerando todas las veces que pudieran ser mostrados y que no sucedió porque el presupuesto es muy bajo.
lost_impression_share_by_ad_rank: porcentaje de veces que no se muestran los anuncios considerando todas las veces que pueden ser mostrados y que no sucedió porque tu rango es más bajo que otros vendedores.
acos_benchmark: el ACOS objetivo usado por anuncios con buenos resultados en impresiones y ventas.
picture_id: id de imagen del artículo a nivel MercadoLibre.
acos_target: costo publicitario de ventas (ACOS) target utilizado por anuncios con buenos resultados en impresiones y ventas.
strategy: tipo de estrategia de campaña. Puede ser PROFITABILITY, INCREASE y VISIBILITY.
acos_top_search_target: objetivo ACOS (costo publicitario de ventas) definido para una campaña con el fin de ofertar específicamente para los primeros resultados de búsqueda. Para otras subastas, se considerará la puja el ACOS target. Debe ser superior al ACOS target de la campaña e inferior a 500.