Display Ads

Tipos de campañas y objetivos

Flujo técnico recomendado

1. Anunciantes (advertiser id) de display
2. Campañas de anunciantes
3. Métricas de una campaña



Panel de campaña en Mercado Ads

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).

Parámetros opcionales

sort_by: ordena por atributo (advertiser_id, site_id). Default advertiser_id.

sort_order: orden (asc, desc). Default es desc.

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=DISPLAY

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"
        }
    ]
}

Glosario

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.

Consultar campañas de un anunciante

Parámetros opcionales

sort_by: ordena por atributo (id, name, start_date, end_date). Default es id.
sort_order: orden (asc, desc). Default es desc.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/61/display/campaigns?sort_by=start_date&sort_order=desc

Respuesta:

{
 "results": [
    {
      "id": 80,
      "name": "CONVERSION_ENERO2022_MLA",
      "start_date": "2022-01-12T17:00:00",
      "end_date": "2022-01-31T23:59:00",
      "advertiser_id": 61,
      "type": "GUARANTEED",
      "status": "paused",
      "site_id": "MLA"
    }
  ]
}

Campos de respuesta

id: id de campaña. Utiliza el id para consultar métricas de campañas.
name: nombre de la campaña.
start_date: fecha de inicio de la campaña.
end_date: fecha de finalización de la campaña.
advertiser_id: id del advertiser
type: tipo de la campaña: Programática o Garantizada.
status: estado de la campaña.
site_id: país.
strategy: objetivo de campaña. Próximamente disponible.

Consultar métricas de una campaña

Los resultados de este endpoint serán las métricas por día y un summary por el rango de fecha de la campaña. Puedes consultar hasta 90 días atrás, considerando como fecha inicial el día 1 de septiembre de 2022.

Parámetros obligatorios

date_from: fecha desde de la consulta en formato YYYY-MM-DD.
date_to: fecha hasta de la consulta en formato YYYY-MM-DD.

Parámetros opcionales

sort_by: ordena por atributo: id, name, start_date, end_date. Por default es id.
sort_order: orden ascendente (asc) o descendente (desc). Por default es desc.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/$CAMPAIGN_ID/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/61/display/campaigns/80/metrics?date_from=2024-04-01&date_to=2024-04-15

Respuesta:

{
  "metrics": [
    {
      "date": "2024-02-01",
      "site_id": "MLM",
      "currency": "MXN",
      "prints": 17961,
      "clicks": 186,
      "active_views": 0,
      "completed_views": 0,
      "reach": 10079,
      "ctr": 0.01,
      "consumed_budget": 57449.13,
      "cpm": 3198.55,
      "cpc": 308.87,
      "average_frequency": 1148.98,
      "event_time": {
        "cpa_order": 1083.95,
        "cpa_ppv": 135.81,
        "roas": 10.03,
        "units_quantity": 75,
        "direct_amount": 576150,
        "direct_item_quantity": 53,
        "attribution_ppv": 423,
        "attribution_add_to_cart": 26,
        "attribution_bookmark": 33,
        "attribution_checkout": 24,
        "attribution_leads": 0,
        "cpl": 0.0
      },
      "touch_point": {
        "cpa_order": 1148.98,
        "cpa_ppv": 125.16,
        "roas": 12.36,
        "units_quantity": 70,
        "direct_amount": 710324,
        "direct_item_quantity": 50,
        "attribution_ppv": 459,
        "attribution_add_to_cart": 26,
        "attribution_bookmark": 35,
        "attribution_checkout": 28,
        "attribution_leads": 0,
        "cpl": 0.0
      }
    }
  ],
  "summary": {
    "site_id": "MLM",
    "currency": "MXN",
    "prints": 170462,
    "clicks": 2033,
    "active_views": 0,
    "completed_views": 0,
    "reach": 48957,
    "ctr": 0.01,
    "consumed_budget": 605406.93,
    "cpm": 3551.57,
    "cpc": 297.79,
    "average_frequency": 1509.74,
    "event_time": {
      "cpa_order": 1513.52,
      "cpa_ppv": 128.59,
      "roas": 9.48,
      "units_quantity": 586,
      "direct_amount": 5741691,
      "direct_item_quantity": 400,
      "attribution_ppv": 4708,
      "attribution_add_to_cart": 263,
      "attribution_bookmark": 375,
      "attribution_checkout": 219,
      "attribution_leads": 0,
      "cpl": 0.0
    },
    "touch_point": {
      "cpa_order": 1509.74,
      "cpa_ppv": 125.66,
      "roas": 9.49,
      "units_quantity": 586,
      "direct_amount": 5746421,
      "direct_item_quantity": 401,
      "attribution_ppv": 4818,
      "attribution_add_to_cart": 270,
      "attribution_bookmark": 352,
      "attribution_checkout": 225,
      "attribution_leads": 0,
      "cpl": 0.0
    }
  }
}

Campos de respuesta

date: fecha de la campaña.
site_id: identificador del país. Consulta la nomenclatura de los sites de Mercado Libre y sus respectivas monedas.
currency: identificador de moneda.
prints: impresiones. Es la cantidad de veces que se mostraron tus anuncios.
clicks: cantidad de veces que los usuarios hicieron clic en tus anuncios.
active_views (vistas activas): cantidad de veces que los usuarios vieron los primeros 6 segundos de tu anuncio de Social y Video.
completed_views (vistas completas): cantidad de veces que los usuarios vieron tu anuncio completo de Social y Video.
reach: Alcance. Es la cantidad de usuarios únicos a los que se le mostraron tus anuncios.
ctr: Click-Through Rate. Tasa de clics obtenidos sobre el total de impresiones.
consumed_budget: Inversión: Es la cantidad de dinero efectivamente gastado para mostrar tus anuncios.
cpm: costo promedio que se paga por cada mil impresiones de los anuncios.
cpc: Costo por clic. Es el costo promedio que se paga por cada clic que recibieron los anuncios.
average_frequency: Frecuencia promedio. Promedio de la cantidad de veces que a un mismo usuario se le mostraron tus anuncios.

Las métricas de atribución tienen dos formas de ser presentadas:

Métricas atribuidas por Fecha de acción (event_time): las métricas se mostrarán asociadas a la fecha exacta en que la acción fue realizada (Ej: Ventas).
Métricas atribuidas por Fecha de visualización (touchpoint): las métricas se mostrarán asociadas a la fecha de clic o impresión visible a la que fueron atribuidas.

• cpa_order: (ventas): costo promedio para cada venta en función de la inversión.
• cpa_ppv: costo promedio de cada vista a la página de producto en función de la inversión.
• roas: retorno de dinero que se obtiene sobre la inversión.
• units_quantity: cantidad de unidades de tus productos que se han vendido entre todas las compras atribuidas a tus anuncios.
• direct_amount (ingresos): valor total de las ventas atribuidas a tus anuncios.
• direct_item_quantity: cantidad de veces que los usuarios realizaron una compra después de ver o hacer clic en tus anuncios.
• attribution_ppv (vistas a páginas de producto): cantidad de veces que los usuarios vieron tu página de producto después de ver o hacer clic en tus anuncios.
• attribution_add_to_cart: cantidad de veces que los usuarios agregaron al carrito de compra tus productos promocionados después de ver o hacer clic en tus anuncios.
• attribution_bookmark: contactos generados por los clientes potenciales después que vieron o hicieron clic en tus anuncios.
• attribution_checkout: cantidad de veces que los usuarios iniciaron un proceso de compra de tus productos promocionados después de ver o hacer clic en tus anuncios.
• attribution_leads: contactos generados por los clientes potenciales después que vieron o hicieron clic en tus anuncios.
• cpl: costo promedio de cada lead en función de la inversión.
Nota:
Hay 2 formas de un seller obtener contactos:
- Publicaciones de Vehículos, Inmuebles o Servicios (VIS): dejando una pregunta, llamada o whatsapp, le llega el lead al vendedor. Conoce más sobre nuestras APIS de Vehículos, Inmuebles and Servicios APIs.
- 2. Formularios: rellenando el formulario de contacto que llega al CRM del cliente. Por ejemplo: o form.



Line items de una campaña

El line item define los parámetros de compra del anuncio: el perfil de usuario a quien querés llegar, su ubicación geográfica, el dispositivo desde donde navega, entre otras. Cada line item está asociado a una única campaña y consume de su presupuesto.




Parámetros opcionales

sort_by: valores posibles: id, name, start_date, end_date.
sort_order: valores posibles: asc, desc.




Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1" 
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/$CAMPAIGN_ID/line_items?sort_by=start_date&sort_order=asc

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1" 
https://api.mercadolibre.com/advertising/advertisers/123456/display/campaigns/987654/line_items?sort_by=start_date&sort_order=asc

Respuesta:

{
 "results": [
    {
      "line_item_id": 1,
      "name": "Name_Line_Item_Test",
      "start_date": "2022-01-12T17:00:00",
      "end_date": "2022-01-31T23:59:00",
      "campaing_id": 987654,
      "type": "Social",
      "status": "paused"
    }
  ]
}

Campos de respuesta

line_item_id: id del line item.
name: nombre del line item.
start_date: fecha de inicio del line item.
end_date: fecha de fin del line item.
type: tipo de line item. Varían de acuerdo al creativo asignado.

• Display: banner nativo de imagen y texto. Apto para distintos espacios publicitarios de Mercado Libre y Mercado Pago
• Social: video en formato vertical con banner inferior. Disponible para los espacios de Clips de Mercado Libre.
• Video: video en formato horizontal. Disponible para las plataformas de streaming integradas con Mercado Ads. Este tipo de line item solo está habilitado para campañas con objetivo Awareness.

status: estado del line item.




Creativos de line item

Parámetros opcionales

sort_by: valores posibles: id, name.
sort_order: valores posibles: asc, desc.




Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1" 
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/$CAMPAIGN_ID/line_items/$LINE_ITEM_ID/creatives?sort_by=start_date&sort_order=asc

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1" 
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/999999/line_items/0000001/creatives?sort_by=start_date&sort_order=asc

Respuesta:

{
    "results": [
        {
            "creative_id": 123456,
            "name": "Name_Creative_Test",
            "status": "active",
            "line_item_id": 0000001,
            "campaign_id": 999999
        }
    ]
}

Campos de respuesta

creative_id: id del creativo.
name: nombre del creativo.
status: estado del creativo. Puede ser: active.


Nota:
Al momento de crear un nuevo creativo, su estado será "En revisión". Es decir, antes que un creativo comience a mostrarse, Mercado Libre debe confirmar que cumpla los lineamientos, políticas, y que no tenga errores. Al terminar la verificación, el creativo puede cambiar de estado a "aprobado" o "rechazado".

line_item_id: id del line item.
campaign_id: id de la campaña.




Errores

Error	Status	Mensaje
bad_request	400	The parameter {paramKey} is required.
not_found	404	No campaigns found for advertiser id {advertiser_id} Campaign not found for sent campaign_id.
not_found	404	No line items found for campaign_id {campaign_id}
not_found	404	No creatives found for line_item_id {line_item_id}