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 19/09/2024

Product Ads

Importante:
- Product Ads está habilitado para productos de Mercado Libre y Mercado Shops.
- Próximamente desactivaremos la versión antigua de Product Ads. Comienza a utilizar los siguientes endpoints.

Con los siguientes endpoints de Product Ads puedes monitorear campañas, anuncios y métricas. Existen dos modalidades de gestión de anuncios en Product Ads.

  • Automático: Product Ads elige las publicaciones con un buen nivel de ventas en Mercado Libre y las muestra en las primeras ubicaciones de los resultados de búsqueda. Puedes agregar o quitar publicaciones de tu campaña en forma manual. Cuando empiezas a usar Product Ads utilizarás el modo automático por defecto.
  • Personalizado: podrás crear múltiples campañas para agrupar tus anuncios, asignar y configurar el presupuesto y el objetivo de cada una. Este es el modo ideal para gestionar tus anuncios, porque te permite tener más control sobre tus campañas y hacer ajustes en base a su desempeño.

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

Importante:
Para usar Product Ads, un usuario debe:
- Tener reputación amarilla o superior.
- Que hayan transcurrido por lo menos 15 días desde el registro en Mercado Libre.
- Tener un mínimo de ventas en Mercado Libre (1 para empresas, 10 para individuos).
- No tener ninguna factura vencida en Mercado Libre.

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.

Nota:
En caso de recibir el error 404 - No permissions found for user_id significa que el usuario no tiene habilitado el Producto. El usuario deberá acceder a Mercado Libre > Mi perfil > Publicidad.

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.

Nota:
- Para todos los endpoints de métricas puedes aplicar el rango de fechas de 90 días hacia atras.
- La información para validar las métricas se actualiza a las 10:00 hrs GMT-3.
- Solo se puede solicitar un aggregation_type a la vez.

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.