Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 18/02/2026

Product Ads

Com os seguintes endpoints do Product Ads você pode monitorar campanhas, anúncios e métricas. Existem duas modalidades de gestão de anúncios no Product Ads.

  • Automático: Product Ads escolhe as publicações com um bom nível de vendas no Mercado Livre e as mostra nas primeiras posições dos resultados de busca. Você pode adicionar ou remover publicações de sua campanha manualmente. Quando você começa a usar Product Ads, utilizará o modo automático por padrão.
  • Personalizado: você poderá criar múltiplas campanhas para agrupar seus anúncios, atribuir e configurar o orçamento e o objetivo de cada uma. Este é o modo ideal para gerenciar seus anúncios, porque permite ter mais controle sobre suas campanhas e fazer ajustes com base em seu desempenho.

Importante:
Informamos que, após o período de transição finalizado Setembro de 2025, os endpoints legados de Product Ads listados abaixo serão permanentemente desativados em 26 de fevereiro de 2026.

A partir desta data, chamadas a estes recursos retornarão erro (404 Not Found). Se a sua aplicação ainda utiliza algum destes endpoints, adapte imediatamente o seu desenvolvimento para evitar interrupções no serviço. Apenas os endpoints publicados na documentação de Product Ads são suportados.

Endpoints que serão descontinuados:
  • GET /advertising/product_ads/items/$ITEM_ID
  • GET /advertising/$ADVERTISER_SITE_ID/product_ads/items/$ITEM_ID
  • GET /advertising/advertisers/$ADVERTISER_ID/product_ads/items
  • GET /advertising/$ADVERTISER_SITE_ID/advertisers/$ADVERTISER_ID/product_ads/items/search
  • GET /advertising/product_ads/campaigns/$CAMPAIGN_ID
  • GET /advertising/advertisers/$ADVERTISER_ID/product_ads/campaigns
  • GET /advertising/product_ads/campaigns/$CAMPAIGN_ID/metrics
  • GET /advertising/product_ads_2/campaigns/$CAMPAIGN_ID/metrics
  • GET /advertising/product_ads/campaigns/$CAMPAIGN_ID/ads/metrics
  • GET /advertising/product_ads_2/campaigns/$CAMPAIGN_ID/ads/metrics
  • GET /advertising/product_ads/ads/search

Consultar anunciante

Importante:
Para usar Product Ads, um usuário deve:
- Ter reputação amarela ou superior.
- Que tenham transcorrido pelo menos 15 dias desde o registro no Mercado Livre.
- Ter um mínimo de vendas no Mercado Livre (1 para empresas, 10 para pessoas físicas).
- Não ter nenhuma fatura vencida no Mercado Livre.

Os anunciantes (advertiser_id) são aqueles que investem um orçamento para a criação e distribuição de anúncios publicitários, com o objetivo de promover seus produtos ou serviços. Consulte a lista de anunciantes que tem acesso a um usuário, segundo o tipo de produto que se requer.


Parâmetros obrigatórios:

  • product_id: tipo de produto. Valores disponíveis: PADS (Product Ads), DISPLAY, BADS (Brand Ads).

Chamada:

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

Exemplo:

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

Resposta:

{
    "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 resposta:

Nota:
Em caso de receber o erro 404 - No permissions found for user_id significa que o usuário não tem habilitado o Produto. O usuário deverá acessar Mercado Livre > Meu perfil > Publicidade.

Exemplo de erro:

{
    "status": 404,
    "error": "not_found",
    "description": "No permissions found for user_id 1167130000"
}

Detalhe de um anúncio

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/product_ads/ads/$ITEM_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/MLM/product_ads/ads/MLM12345678

Resposta:

{
  "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 campanhas

Importante:
A partir de Janeiro de 2026, as respostas das consultas de métricas de campanhas passam a incluir o campo "roas_target".

Para melhorar a análise de desempenho, o sistema agora prioriza o ROAS em vez do ACOS. O ROAS foca no retorno direto do investimento, indicando quanto o vendedor ganha por cada unidade monetária investida em publicidade. As campanhas que anteriormente utilizavam o ACOS Objetivo foram migradas automaticamente para o valor equivalente em ROAS Objetivo.

O campo acos_target continuará visível até 30 de Março de 2026 como uma métrica opcional para facilitar a adaptação e comparação, já que o roas_target é agora o indicador padrão de performance.Sendo calculado automaticamente com base no ROAS enviado e na seguinte fórmula: ACOS = (1/ROAS) X 100.

Endpoints impactados:
O novo campo roas_target passa a ser retornado nos seguintes endpoints:
  • Pesquisa e métricas de todas as campanhas
  • Detalhes e métricas de uma campanha
  • Métricas sumarizadas de campanhas

Parâmetros opcionais:

  • limit: limite de elementos a mostrar.
  • offset: atributo de paginação dos resultados, permite percorrer as páginas da lista desde o 0 até o múltiplo do total de elementos com o limite por página.
  • date_from: data desde (YYYY-MM-DD). Validamos que esteja presente se forem solicitadas métricas.
  • date_to: data até (YYYY-MM-DD). Validamos que esteja presente se forem solicitadas métricas.
  • metrics: lista separada por vírgula (Ex. clicks, prints). Indica os campos que serão retornados na resposta. Valores possíveis:
    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: agregação pela qual se apresentarão os resultados. Por padrão, sum.
  • aggregation_type: Tipo de agregação na qual se apresentarão os resultados. Por padrão, campaign.
  • metrics_summary: solicita resumo de métricas. Deve ser usado em conjunto com metrics. Por padrão, false.
Nota:
- Para todos os endpoints de métricas você pode aplicar o intervalo de datas de 90 dias para trás.
- A informação para validar as métricas é atualizada às 10:00h GMT-3.
- Só se pode solicitar um aggregation_type por vez.

Filtros disponíveis

Para utilizar os filtros você deve seguir a estrutura ?filters[nome do filtro]= valor.


campaign_ids: filtro por id de campanhas separado por vírgulas.

campaign_id: filtro por id de uma campanha, obtém-se todos os itens que estiveram na campanha para o intervalo de datas.

status: estado das campanhas, separado por vírgulas. Valores disponíveis: active, paused.


Pesquisa e métricas de todas as campanhas

Obtenha todas as campanhas de um anunciante e também suas métricas correspondentes.


Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' 
https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/advertisers/$ADVERTISER_ID/product_ads/campaigns/search?limit=1&offset=0&date_from=2025-06-01&date_to=2025-07-20&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

Exemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' 
https://api.mercadolibre.com/advertising/MLA/advertisers/882927/product_ads/campaigns/search?limit=1&offset=0&date_from=2025-12-01&date_to=2025-12-30&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

Resposta:

{
    "paging": {
        "offset": 0,
        "total": 15,
        "limit": 1
    },
    "results": [
        {
            "id": 355189450,
            "name": "Campaña",
            "status": "active",
            "last_updated": "2025-11-25T21:12:59.000Z",
            "date_created": "2025-11-25T21:12:59.000Z",
            "strategy": "VISIBILITY",
            "acos_target": 50.0,
            "acos_top_search_target": 0.0,
            "roas_target": 2.0,
            "channel": "marketplace",
            "advertiser_id": 882927,
            "salesforce_event_id": 14,
            "budget": 900.0,
            "automatic_budget": false,
            "metrics": {
                "clicks": 0,
                "prints": 0,
                "cost": 0.0,
                "cpc": 0.0,
                "ctr": 0.0,
                "direct_amount": 0.0,
                "indirect_amount": 0.0,
                "total_amount": 0.0,
                "direct_units_quantity": 0,
                "indirect_units_quantity": 0,
                "units_quantity": 0,
                "direct_items_quantity": 0,
                "indirect_items_quantity": 0,
                "advertising_items_quantity": 0,
                "organic_units_quantity": 0,
                "organic_units_amount": 0.0,
                "organic_items_quantity": 0,
                "acos": 0.0,
                "cvr": 0.0,
                "roas": 0.0,
                "sov": 0.0
            }
        }
    ]
}

Métricas diárias de campanhas

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/advertisers/$ADVERTISER_ID/product_ads/campaigns/search?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

Resposta:

{
   "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 campanhas

Utilize o mesmo endpoint para consultar métricas de campanhas adicionando o parâmetro metrics_summary=true.


Exemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' 
https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/advertisers/$ADVERTISER_ID/product_ads/campaigns/search??limit=1&offset=0&date_from=2025-12-01&date_to=2025-12-30&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

Resposta:

{
    "paging": {
        "offset": 0,
        "total": 15,
        "limit": 1
    },
    "results": [
        {
            "id": 355189450,
            "name": "Campaña",
            "status": "active",
            "last_updated": "2025-11-25T21:12:59.000Z",
            "date_created": "2025-11-25T21:12:59.000Z",
            "strategy": "VISIBILITY",
            "acos_target": 50.0,
            "acos_top_search_target": 0.0,
            "roas_target": 2.0,
            "channel": "marketplace",
            "advertiser_id": 882927,
            "salesforce_event_id": 14,
            "budget": 900.0,
            "automatic_budget": false,
            "metrics": {
                "clicks": 0,
                "prints": 0,
                "cost": 0.0,
                "cpc": 0.0,
                "ctr": 0.0,
                "direct_amount": 0.0,
                "indirect_amount": 0.0,
                "total_amount": 0.0,
                "direct_units_quantity": 0,
                "indirect_units_quantity": 0,
                "units_quantity": 0,
                "direct_items_quantity": 0,
                "indirect_items_quantity": 0,
                "advertising_items_quantity": 0,
                "organic_units_quantity": 0,
                "organic_units_amount": 0.0,
                "organic_items_quantity": 0,
                "acos": 0.0,
                "cvr": 0.0,
                "roas": 0.0,
                "sov": 0.0
            }
        }
    ],
    "metrics_summary": {
        "clicks": 0,
        "prints": 0,
        "cost": 0.0,
        "cpc": 0.0,
        "ctr": 0.0,
        "direct_amount": 0.0,
        "indirect_amount": 0.0,
        "total_amount": 0.0,
        "direct_units_quantity": 0,
        "indirect_units_quantity": 0,
        "units_quantity": 0,
        "direct_items_quantity": 0,
        "indirect_items_quantity": 0,
        "advertising_items_quantity": 0,
        "organic_units_quantity": 0,
        "organic_units_amount": 0.0,
        "organic_items_quantity": 0,
        "acos": 0.0,
        "cvr": 0.0,
        "roas": 0.0,
        "sov": 0.0
    }
}

Detalhes e métricas de uma campanha

Parâmetros opcionais:

  • date_from: data desde (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos de métricas.
  • date_to: data até (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos de métricas.
  • metrics: lista separada por vírgula (Ex clicks,prints) indica os campos que serão retornados na resposta. Valores possíveis:
    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: agregação pela qual se apresentarão os resultados. Padrão: sum.
  • aggregation_type: tipo de agregação na qual se apresentarão os resultados. Padrão: campaign.

Exemplo:

curl GET -H 'api-version: 2' -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/product_ads/campaigns/$CAMPAIGN_ID?date_from=2025-12-01&date_to=2025-12-30&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

Resposta:

{
    "id": 355189450,
    "name": "Campaña",
    "status": "active",
    "last_updated": "2025-11-25T21:12:59.000Z",
    "date_created": "2025-11-25T21:12:59.000Z",
    "strategy": "VISIBILITY",
    "acos_target": 50.0,
    "acos_top_search_target": 0.0,
    "roas_target": 2.0,
    "channel": "marketplace",
    "budget": 900.0,
    "currency_id": "ARS",
    "metrics": {
        "clicks": 0,
        "prints": 0,
        "cost": 0.0,
        "cpc": 0.0,
        "ctr": 0.0,
        "direct_amount": 0.0,
        "indirect_amount": 0.0,
        "total_amount": 0.0,
        "direct_units_quantity": 0,
        "indirect_units_quantity": 0,
        "units_quantity": 0,
        "direct_items_quantity": 0,
        "indirect_items_quantity": 0,
        "advertising_items_quantity": 0,
        "organic_units_quantity": 0,
        "organic_units_amount": 0.0,
        "organic_items_quantity": 0,
        "acos": 0.0,
        "cvr": 0.0,
        "roas": 0.0,
        "sov": 0.0,
        "impression_share": 0.0,
        "top_impression_share": 0.0,
        "lost_impression_share_by_budget": 0.0,
        "lost_impression_share_by_ad_rank": 0.0,
        "acos_benchmark": 0.0
    }
}

Métricas diárias de uma campanha

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/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

Resposta:

[
   {
       "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 anúncios

Parâmetros opcionais:

  • limit: limite de elementos a mostrar.
  • offset: atributo de paginação dos resultados, permite percorrer as páginas da lista desde o 0 até o múltiplo do total de elementos com o limite por página.
  • date_from: data desde (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos de métricas.
  • date_to: data até (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos de métricas.
  • metrics: lista separada por vírgula (Ex clicks,prints) indica os campos que serão retornados na resposta. Valores possíveis:
    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: ordenação da consulta, asc e desc.
  • sort_by: nome do atributo pelo qual se realizará a ordenação.
  • aggregation: agregação pela qual se apresentarão os resultados. Padrão: sum.
  • aggregation_type: tipo de agregação na qual se apresentarão os resultados: DAILY, item. Padrão: item.
  • metrics_summary: resume as métricas e deve usá-lo em combinação com metrics. Padrão false.

Filtros disponíveis

Para utilizar os filtros você deve seguir a estrutura ?filters[nome do filtro]= valor.


item_id: Id do anúncio. Um ou mais, separados por vírgula.

statuses: status de ads. Valores disponíveis: active, paused, hold, idle, delegated, revoked. Geralmente filtra-se por active, paused e idle.

  • hold: o item está desabilitado em publicidade, resultado de que o item a nível marketplace está pausado ou sem estoque
  • idle: o item está disponível para ter publicidade mas não está em nenhuma campanha de publicidade.
  • delegated: significa que do ponto de vista do owner que consulta, o item está delegado a outro advertiser. Ou seja, embora o owner (seller) possa ser o dono do item, já não tem poder para operar sobre ele porque estão "emprestados" a outro advertiser.
  • revoked: significa que do ponto de vista do advertiser ao qual foram emprestados os itens, este advertiser os devolveu ao dono, portanto já não tem poder para operar sobre esses itens.

price: preço.

buy_box_winner: o item associado é o ganhador do Catálogo. Saiba mais sobre Competência em Catálogo.

condition: condição do item associado.

current_level: reputação do item associado.

deferred_stock: estoque do item associado.

domains: domínio do item associado.

logistic_types: tipo de logística do item associado.

listing_types: tipo de listagem do item associado.

official_stores: loja oficial do item associado.

recommended: o anúncio é recomendado pelo Product Ads. Segundo nossos modelos, tem bom rendimento e se for ativada a publicidade, as vendas serão potencializadas.

campaign_id: obtenha todos os anúncios que uma campanha teve em um período de tempo.

campaigns: lista de campanhas separados por vírgula.

brand_value_id: identificador de marca.

brand_value_name: nome da marca.


Busca e métricas de todos os anúncios

Obtenha todos os anúncios e métricas correspondentes a estes.


Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/advertisers/$ADVERTISER_ID/product_ads/ads/search?limit=1&offset=0&date_from=2024-02-01&date_to=2024-03-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

Exemplo:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/MLM/advertisers/35300/product_ads/ads/search?limit=1&offset=0&date_from=2024-02-01&date_to=2024-03-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

Resposta:

{
   "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 diárias de anúncios

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/advertisers/$ADVERTISER_ID/product_ads/ads/search?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

Resposta:

{
   "paging": {
       "offset": 0,
       "last_item_id": null,
       "total": 387,
       "limit": 1
   },
   "results": [
       {
           "date": "2024-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 resumidas de anúncios

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/advertisers/$ADVERTISER_ID/product_ads/ads/search?limit=1&offset=0&date_from=2024-02-01&date_to=2024-03-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

Resposta:

{
   "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 um anúncio

Parâmetros opcionais:

  • date_from: data desde (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos de métricas.
  • date_to: data até (YYYY-MM-DD). Validamos que esteja presente se forem solicitados campos de métricas.
  • metrics: lista separada por vírgula (Ex clicks, prints). Indica os campos que serão retornados na resposta. Valores possíveis:
    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: agregação pela qual se apresentarão os resultados. Padrão: sum.
  • aggregation_type: tipo de agregação na qual se apresentarão os resultados: DAILY, item. Padrão: item.

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/product_ads/ads/$ITEM_ID?date_from=2024-02-01&date_to=2024-03-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

Resposta:

{
  "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 diárias de um anúncio

Chamada:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2' https://api.mercadolibre.com/advertising/$ADVERTISER_SITE_ID/product_ads/ads/$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

Resposta:

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

Glossário

advertiser_site_id: site do advertiser.

total: total de registros obtidos.

offset: valor padrão: 0.

limit: limites de elementos na lista de campanhas. Por padrão: 50.

results: resultados obtidos.

id: identificador do anúncio ou campanha.

budget: média diária do orçamento (mensal) da campanha, ou seja, se o orçamento não for consumido durante o dia, será usado o restante nos dias seguintes até que termine o mês.

last_updated: data da última modificação da campanha.

date_created: data de criação da campanha.

price: preço do artigo associado.

title: nome da publicação.

has_discount: se tem desconto. Este valor é identificado com base na diferença entre os campos regular amount e amount entregue por Prices API.

catalog_listing: é uma publicação de catálogo.

logistic_type: tipo de logística para o envio do artigo.

listing_type_id: identificador do tipo de publicação.

domain_id: domínio.

date_created: data de criação do anúncio.

official_store_id: identificador da loja oficial.

buy_box_winner: é ganhador do Catálogo.

channel: canal da campanha (marketplace).

campaign_id: identificador da campanha.

condition: condição do artigo.

current_level: reputação.

deferred_stock: estoque de produto disponível. Um item com manufacturing_time (tempo de disponibilidade) faz com que o anúncio não seja mostrado, priorizando-se então os anúncios que tenham estoque imediato.

thumbnail: link para a imagem miniatura.

permalink: link para a publicação.

brand_value_id: identificador da marca associada ao item.

brand_value_name: nome da marca associada ao item.

status: estado do anúncio ou campanha.

recommended: o anúncio é recomendado.

metrics: métricas do artigo ou campanha.

clicks: cliques da campanha.

prints: quantidade de impressões (vezes em que o anúncio é mostrado).

sov: porcentagem de vendas por publicidade sobre vendas totais.

clicks: cliques da campanha.

ctr: taxa de cliques.

cost: investimento da campanha.

cpc: custo por clique.

acos: porcentagem de investimento em publicidade sobre as receitas obtidas.


Vendas sem publicidade

  • organic_units_quantity: quantidade de unidades vendidas sem publicidade.
  • organic_units_amount: montante de vendas de pedidos orgânicos.
  • organic_items_quantity: quantidade de vendas sem publicidade.

Vendas com publicidade

  • Vendas diretas
    • direct_items_quantity: quantidade de vendas diretas por publicidade.
    • direct_units_quantity: quantidade de unidades vendidas em vendas diretas.
    • direct_amount: soma do valor das vendas diretas obtidas do seu Product Ad, em moeda local.
  • Vendas indiretas
    • indirect_items_quantity: quantidade de vendas indiretas por publicidade.
    • indirect_units_quantity: quantidade de unidades vendidas em vendas assistidas.
    • indirect_amount: soma do valor das vendas assistidas obtidas do seu Product Ad, em moeda local.

advertising_items_quantity: quantidade de vendas por publicidade.
cvr: taxa de conversão.
roas: retorno sobre o gasto publicitário.
units_quantity: quantidade de vendas totais.
total_amount: soma do valor das vendas obtidas do seu Product Ad, em moeda local.
impression_share: porcentagem de vezes que os anúncios são mostrados considerando todas as vezes que podem ser mostrados.
top_impression_share: quantidade de leilões ganhos nas primeiras posições da busca entre a quantidade de leilões nos quais pôde participar.
lost_impression_share_by_budget: porcentagem de vezes que os anúncios não são mostrados considerando todas as vezes que poderiam ser mostrados e que não aconteceu porque o orçamento é muito baixo.
lost_impression_share_by_ad_rank: porcentagem de vezes que os anúncios não são mostrados considerando todas as vezes que podem ser mostrados e que não aconteceu porque seu ranking é mais baixo que outros vendedores.
acos_benchmark: o ACOS objetivo usado por anúncios com bons resultados em impressões e vendas.
picture_id: id de imagem do artigo a nível Mercado Livre.
acos_target: custo publicitário de vendas (ACOS) target utilizado por anúncios com bons resultados em impressões e vendas.
strategy: tipo de estratégia de campanha. Pode ser PROFITABILITY, INCREASE e VISIBILITY.
roas_target: Retorno sobre o investimento publicitário (ROAS Objetivo). É a receita gerada pela campanha/anúncio por cada unidade monetária investida em publicidade (receitas atribuíveis / gasto publicitário). Deve ser maior ou igual a 1x e inferior ou igual a 35x.

Como interpreto a relação entre o ROAS que defino e meus resultados?


ROAS Objetivo baixo: Busca gerar mais vendas e ter maior alcance, embora a rentabilidade por cada venda seja menor.


ROAS Objetivo alto: Busca maior rentabilidade por cada venda, embora isso signifique que seus anúncios sejam menos competitivos e gerem um volume de vendas e receitas totais mais baixo.