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 10/07/2024

Product Ads

Importante:
- A partir del 5 de agosto de 2024, el campo daily_budget pasará a ser budget. Consulta nuestro glosario y actualiza tu integración.
- 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.

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": 36,
      "site_id": "MLM"
    }
  ]
}

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.

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.

Nota:
Para todos los endpoints de métricas puedes aplicar el rango de fechas en caso de que se soliciten métricas. Solo se puede solicitar un aggregation_type a la vez.

metrics_summary: solicitas sumarizado de métricas. Debe usarse en conjunto con metrics. Por defecto, false.


Filtros disponibles

campaign_ids: filtro por id de campañas separado por comas.

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.

date_to: fecha hasta (YYYY-MM-DD). Se valida que esté presente si se solicitan campos.

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.

date_to: fecha hasta (YYYY-MM-DD). Validamos que esté presente si se solicitan campos.

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

items: Id del anuncio. Uno o más, separados por coma.

status: 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.

date_to: fecha hasta (YYYY-MM-DD). Validamos que esté presente si se solicitan campos.

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.

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.

direct_items_quantity: cantidad de ventas directas por publicidad.

indirect_items_quantity: cantidad de ventas indirectas por publicidad.

advertising_items_quantity: cantidad de ventas por publicidad.

cvr: tasa de conversión.

roas: retorno sobre el gasto publicitario.

direct_units_quantity: cantidad de unidades vendidas en ventas directas.

indirect_units_quantity: cantidad de unidades vendidas en ventas asistidas.

units_quantity: cantidad de ventas totales.

direct_amount: suma del valor de las ventas directas obtenidas de tu Product Ad, en moneda local.

indirect_amount: suma del valor de las ventas asistidas obtenidas de tu Product Ad, en moneda local.

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.