• API Docs
  • Guía para publicidad
  • Product Ads
Última actualización 15/03/2023

Mercado Ads

Nota:
Esta funcionalidad está disponible solo para integradores autorizados.

Esta API te permite crear campañas de publicidad para promocionar anuncios (publicaciones con publicidad) en Mercado Libre con el fin de obtener más visitas y ventas. A través de Mercado Ads lograrás potenciar el rendimiento e incrementar ventas.


Límites de presupuesto

Antes de armar una campaña, conoce los límites de presupuesto. Cada usuario tiene asignado una inversión mínima y máxima en publicidad. Puedes elegir libremente tu inversión diaria dentro de este rango.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/budgets/limits?campaign_type=default

Respuesta:

{
       "campaign_type": "default",
       "minimum": 100,
       "maximum": 50000,
       "maximum_percentage": 30,
       "minimum_percentage": 0.5,
       "recommended_minimum": 500
   }
  • campaign_type: tipo de campaña.
  • minimum: monto mínimo de inversión publicitaria.
  • maximum: monto máximo de inversión publicitaria.
  • maximum_percentage: máximo porcentaje.
  • minimum_percentage: mínimo porcentaje.
  • recommended_minimum: mínimo recomendado.
Nota:
Los valores están expresados en la moneda local. El presupuesto deberá estar dentro de ese rango. Los valores de los límites son presupuestos válidos. Los límites pueden cambiar a lo largo del tiempo.

Crear una campaña

Todos los anuncios deben estar agrupados en una campaña, cuyo presupuesto será repartido entre todos los anuncios que estén dentro de ella.


Parámetros

  • Budget: (obligatorio) debe estar dentro de los límites de presupuesto de tu usuario.
  • Status: (opcional) tiene valor active por defecto.
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns
{
  "budget": 20,
  "status": "active"|"paused",
}

Respuesta:

{
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "type": "default",
    "status": "active",
    "budget": 225,
    "last_updated": "2018-08-23T18:31:11.897Z",
    "date_created": "2018-08-23T18:31:11.897Z"
}

Modificar una campaña

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID
{
  "status": "active"|"paused",
  "budget":225
}

Consultar una campaña

Llamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID

Ejemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/223493019

Respuesta:

{
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "type": "default",
    "status": "active",
    "budget": 225,
    "last_updated": "2018-08-23T18:56:33.000Z",
    "date_created": "2018-08-23T04:00:00.000Z"
}

Buscar campañas por usuario

Llamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=$USER_ID

Ejemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=123456

Respuesta:

{  
   "paging":{  
      "total":1,
      "offset":0,
      "limit":10
   },
   "results":[  
      {  
         "id":223703005,
         "name":"Campanha Principal",
         "user_id":301254033,
         "type":"default",
         "status":"active",
         "budget":225.0,
         "last_updated":"2018-08-24T04:00:00.000Z",
         "date_created":"2018-08-24T04:00:00.000Z"
      }
   ]
}

Métricas de campaña

Puedes consultar métricas de una campaña con un rango de fechas que no supere los 90 días.


Parámetros obligatorios

  • date_from: con formato aaaa-mm-dd, ejemplo 2018-08-01
  • date_to: con formato aaaa-mm-dd, ejemplo 2018-08-10
  • campaign_id: id de la campaña

Llamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/metrics?date_from=AAAA-MM-DD&date_to=AAAA-MM-DD

Respuesta:

{  
   "clicks":1590,
   "impressions":1929487,
   "ctr":0.08,
   "cost":700.19,
   "cpc":0.44,
   "sold_quantity_direct":38,
   "sold_quantity_indirect":13,
   "sold_quantity_total":51,
   "amount_direct":9775,
   "amount_indirect":6815,
   "amount_total":16590,
   "advertising_fee":4.22
}

Campos de respuesta

  • impressions: cantidad de impresiones en el sitio que recibió la campaña.
  • clicks: cantidad de clicks que recibió la campaña.
  • ctr: click through rate, expresado en porcentaje, la división entre clicks e impressions.
  • cost: es el costo total de clicks del período, en moneda local.
  • cpc: el costo promedio de cada click, en moneda local.
  • sold_quantity_direct: cantidad de ventas directas.
  • sold_quantity_indirect: cantidad de ventas asistidas.
  • sold_quantity_total: cantidad de ventas en total.
  • amount_direct: suma del valor de las ventas directas obtenidas a través de tus Product Ads, en moneda local. Tienes una venta directa cuando un usuario hace clic en tu Product Ad y compra ese producto.
  • amount_indirect: suma del valor de las ventas asistidas obtenidas a través de tus Product Ads, en moneda local. Tienes una venta asistida cuando un usuario hace clic en tu Product Ad y compra otro de tus productos.
  • amount_total: suma del valor de las ventas obtenidas a través de tus Product Ads, en moneda local.
  • advertising_fee: expresado en porcentaje, la división entre inversión en publicidad sobre los ingresos obtenidos. cost / amount_total. Un valor más bajo implica un mejor rendimiento.

Métricas de anuncios

Puedes consultar en un mismo request, implementando multiget hasta 50 Product Ads. También se deberá enviar un rango de fechas que no supere los 90 días.


Parámetros

  • date_from: campo requerido, con formato aaaa-mm-dd, ejemplo 2018-08-01.
  • date_to: campo requerido, con formato aaaa-mm-dd, ejemplo 2018-08-10.
  • campaign_id: campo requerido, id de la campaña.
  • ids: campo requerido, lista de hasta 50 item ids separados por coma, ejemplo MLA1234, MLA4321.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/ads/metrics?date_from=AAAA-MM-DD&date_to=AAAA-MM-DD&ids=$ITEM_ID_1,$ITEM_ID_2

Respuesta:

[  
   {  
      "id":"MLA740084255",
      "clicks":73,
      "impressions":160930,
      "ctr":0.05,
      "cost":32.85,
      "cpc":0.45,
      "sold_quantity_direct":19,
      "sold_quantity_indirect":0,
      "sold_quantity_total":19,
      "amount_direct":3610,
      "amount_indirect":0,
      "amount_total":3610,
      "advertising_fee":0.91
   }
]

Campos de la respuesta

  • impressions: cantidad de impresiones en el sitio que tuvo el Product Ad.
  • clicks: cantidad de clicks que recibió el Product Ad.
  • ctr: click through rate, expresado en porcentaje, la división entre clicks e impressions.
  • cost: es el costo total de clicks del período, en moneda local.
  • cpc: el costo promedio de cada click, en moneda local.
  • sold_quantity_direct: cantidad de ventas directas que tuvo el Product Ad.
  • sold_quantity_indirect: cantidad de ventas asistidas que tuvo el Product Ad.
  • sold_quantity_total: cantidad de ventas en total que tuvo el Product Ad.
  • amount_direct: suma del valor de las ventas directas obtenidas de tu Product Ad, en moneda local.
  • amount_indirect: suma del valor de las ventas asistidas obtenidas de tu Product Ad, en moneda local.
  • amount_total: suma del valor de las ventas obtenidas de tu Product Ad, en moneda local.
  • advertising_fee: expresado en porcentaje, la división entre inversión en publicidad sobre los ingresos obtenidos.
  • amount_total: un valor más bajo implica un mejor rendimiento.


    Consultar anuncio asociado a un ítem

    Llamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/{item_id}

    Ejemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/{item_id}

    Respuesta:

    {
    "id": "MLA657316800",
    "campaign_id": 141072850,
    "user_id": 246460082,
    "site_id": "MLA",
    "cpc": 1.73,
    "status": "active",
    "title": "Item de Teste",
    "price": 200,
    "currency_id": "ARS",
    "permalink": "http://articulo.mercadolibre.com.ar/MLA-657316800-item-de-testeo_JM"
    "thumbnail": "http://mla-s2-p.mlstatic.com/471325-MLA25424154856_032017-I.jpg",
    "picture_id": "471325-MLA25424154856_032017",
    "date_created": "2017-03-10T02:27:32.325+0000",
    "last_updated": "2017-03-10T02:27:32.325+0000"
}

    Editar estado de anuncio

    Llamada:

    curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads/ads/$ITEM_ID
{
  "status": "paused" | "active"
}

    Buscar anuncios por usuarios

    Parámetros

    • user_id: requerido.
    • status: opcional, es el status de los Product Ads.
    • title: opcional, son palabras incluidas en el título del Product Ad.
    • campaigns: opcional, recibe un campaign id.
    • offset y limit: opcionales. El limit no podrá ser mayor a 100.

    Llamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE

    Buscar +10.000 anuncios por usuario

    Para aquellos usuarios con búsquedas de más 10.000 anuncios tendrán una nueva forma de consultar.


    1. Realizar la primer búsqueda normalmente:


    Parámetros obligatorios

    • user_id: id del usuario, tipo long.
    • site_id: sitio del país del usuario, tipo string.
    • limit: límite de resultados por búsqueda, tipo integer.

    Parámetro opcional

    channel: canal del ítem (marketplace/mshops) – Por defecto es marketplace, tipo string.


    Llamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE

    Respuesta:

    {
  "paging": {
      "offset": 0,
      "total": 100,
      "limit": 1,
      "last_item_id": "MLA1234567890"
  },
  "results": [
      {
          "item_id": "MLA1234567890",
          "user_id": 123456789,
          "campaign_id": 0,
          "price": 471.71,
          "title": "Example title",
          "status": "I",
          "has_discount": false,
          "catalog_listing": false,
          "logistic_type": "cross_docking",
          "listing_type_id": "gold_pro",
          "domain_id": "MLM-DOMAIN",
          "date_created": "2022-07-01T17:19:02.000-04:00",
          "price_usd": 23.68,
          "sales_quantity": 0,
          "sold_quantity": 0,
          "official_store_id": null,
          "cpc": null,
          "cpc_usd": null,
          "currency_id": null,
          "buy_box_winner": false,
          "previous_campaigns": [],
          "channel": "marketplace",
          "advertiser_id": null,
          "brand_value_id": null,
         "brand_value_name": null
      }
  ]
}

    Campos de respuesta

    Contiene la cantidad de ítems definida por limit.

    • total: total de elementos que posee el usuario.
    • limit: cantidad de elementos por página de búsqueda.
    • last_item_id: último item_id de la lista que servirá para la próxima petición y comenzar a mostrar los siguientes elementos dependiendo del limit especificado.

    2. Identificar el last_item_id (último item_id de la lista) que servirá para la próxima petición.


    3. Hacer la segunda búsqueda con el último ítem de la lista como elemento pivote para la siguiente página de resultados. Para esta búsqueda no debes enviar el parámetro offset, dado que si se envía junto al last_item_id, se producirá un error.


    Parámetros obligatorios

    • user_id: id del usuario, tipo long.
    • site_id: sitio del país del usuario, tipo string.
    • limit: límite de resultados por búsqueda, tipo integer.
    • last_item_id: último ítem de la lista que servirá como elemento pivote para la siguiente página de resultados. Si no se coloca, volverá al comienzo de todo el listado. Tipo string.

    Parámetro opcional

    channel: Canal del ítem (marketplace/mshops) – Por defecto es marketplace, tipo string.


    Llamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE&last_item_id=$LAST_ITEM_ID