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

Product Ads

Important:
- Product Ads is enabled for Mercado Libre and Mercado Shops products.
- Soon, we will notify you of the deactivation date of the old version of Product Ads. Use the next Product Ads endpoints now.

With the following Product Ads endpoints, you can monitor campaigns, ads, and metrics. There are two modes of ad management in Product Ads.

  • Automatic: Product Ads selects listings with a good level of sales on Mercado Libre and displays them in the top positions of search results. You can manually add or remove listings from your campaign. When you start using Product Ads, you will use the automatic mode by default.
  • Customized: You'll be able to create multiple campaigns to group your ads, assign and set the budget and goal for each one. This is the ideal way to manage your ads because it allows you to have more control over your campaigns and make adjustments based on their performance.

Check advertiser

Advertisers (advertiser_id) are those who invest a budget for the creation and distribution of advertising, with the aim of promoting their products or services. Check the list of advertisers that a user has access to, according to the type of product required.


Required parameters

product_id: Product type. Available values: PADS (Product Ads), DISPLAY, BADS (Brand Ads).


Request:

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

Example:

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

Response:

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

Response fields

advertiser_id: advertiser identifier. You will use this for the rest of the requests.
site_id: country identifier. Check the nomenclature of Mercado Libre sites and their respective currencies.
advertiser_name: advertiser name.
account_name: account name.

Note:
In case you receive error 404 - No permissions found for user_id means that the user does not have the Product enabled. The user must access Mercado Libre > Mi perfil > Publicidad.

Ad Details

Request:

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

Response:

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

Campaign metrics

Optional parameters

limit: limit of items to display

offset: pagination attribute of the results, allows navigating through the pages of the list from 0 to the multiple of the total elements with the page limit

date_from: start date (YYYY-MM-DD). It is validated that it is present if metrics are requested

date_to: end date (YYYY-MM-DD). It is validated that it is present if metrics are requested

metrics: comma-separated list (e.g., clicks, prints). Indicates the fields that will be returned in the response. Possible values:

  • 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: aggregation by which the results will be presented. Default: sum

aggregation_type: type of aggregation in which the results will be presented. Default: campaign

metrics_summary: Request summarized metrics. Must be used in conjunction with metrics. Default: false.

Note:
- For all metrics endpoints, you can apply a date range of 90 days backward.
- The information for validating metrics is updated at 10:00 AM GMT-3.
- Only one aggregation_type can be requested at a time.

Available filters

To use the filters, you must follow the structure ?filters[filter name]= value.


campaign_ids: filter by campaign IDs separated by commas.

campaign_id: filter by campaign ID, get all items that have been in the campaign for the specified date range.

status: campaign status, separated by commas. Available values: active, paused, deleted.

channel: campaign channel. Can be marketplace or mshops.


Campaign Search and Metrics

Get all campaigns of an advertiser along with their corresponding metrics.

Example:

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

Response:

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

Daily campaign metrics

Example:

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

Response:

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

Summarized Campaign Metrics

Use the same endpoint to query campaign metrics by adding the parameter metrics_summary=true.

Example:

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

Response:

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

Campaign Detail and Metrics

Optional parameters

date_from: Start date (YYYY-MM-DD). Validation required if metrics are requested.

date_to: End date (YYYY-MM-DD). Validation required if metrics are requested.

metrics: Comma-separated list (e.g., clicks, prints) indicates the fields to be returned in the response. Available values:

  • 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: Aggregation for presenting the results. Default: sum.

aggregation_type: Aggregation type for presenting the results. Default: campaign.


Available filters

channel: Campaign channel. Can be marketplace or mshops.


Example:

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

Response:

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

Daily Campaign Metrics

Example:

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

Response:

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

Ads metrics

Optional parameters

limit: Limit of elements to display.


offset: Pagination attribute of the results, allows navigating through the pages of the list from 0 to the multiple of the total elements with the page limit.

date_from: Start date (YYYY-MM-DD). Validation required if metrics are requested.

date_to: End date (YYYY-MM-DD). Validation required if metrics are requested.

metrics: Comma-separated list (e.g., clicks, prints) indicates the fields to be returned in the response. Possible values:

  • 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: Sorting of the query, asc and desc.

sort_by: Name of the attribute by which the sorting will be performed.

aggregation: Aggregation for presenting the results. Default: sum.

aggregation_type: Aggregation type for presenting the results: daily, item. Default: item.

metrics_summary: Summarizes the metrics and should be used in combination with metrics. Default false.


Available filters

To use the filters, you must follow the structure ?filters[filter name]= value.


item_id: Ad ID. One or more, separated by comma.

statuses: Ad status. Available values: active, paused, hold, idle, delegated, revoked; typically filtered by active, paused, and idle.

  • hold: The item is disabled in advertising, usually because the item at the marketplace level is paused or out of stock.
  • idle: The item is available for advertising but is not in any advertising campaign.
  • delegated: Means that from the owner's perspective, the item is delegated to another advertiser. This means that although the owner (seller) may own the item, they no longer have authority to operate on it because it is "loaned out" to another advertiser.
  • revoked: Means that from the perspective of the advertiser to whom the items were loaned, this advertiser returned them to the owner, so they no longer have authority to operate on those items.

channel: Sales channel 'marketplace' (Mercado Libre) or 'mshops' (Mercado Shops).

price: Price.

buy_box_winner: The associated item is the Buy Box winner. Available value: true or false. Learn more about Catalog competition.

condition: Condition of the associated item.

current_level: Reputation of the associated item.

deferred_stock: Stock of the associated item.

domains: Domain of the associated item.

logistic_types: Logistic type of the associated item.

listing_types: Listing type of the associated item.

official_stores: Official store of the associated item.

recommended: The ad is recommended by Product Ads. According to our models, it performs well, and activating advertising for it will boost sales.

campaign_id: Get all ads that have been part of a campaign within a time period.

campaigns: List of campaigns separated by comma.

brand_value_id: Brand identifier.

brand_value_name: Brand name.


Ad Search and Metrics

Get all ads and their corresponding metrics.

Example:

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

Response:

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

Daily Ad Metrics

Example:

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

Response:

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

Summarized Ad Metrics

Example:

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

Response:

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

Ad Metrics

Optional parameters

date_from: Start date (YYYY-MM-DD). Validation required if metrics are requested.

date_to: End date (YYYY-MM-DD). Validation required if metrics are requested.

metrics: Comma-separated list (e.g., clicks, prints). Indicates the fields to be returned in the response. Possible values:

  • 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: Aggregation for presenting the results. Default: sum.

aggregation_type: Aggregation type for presenting the results: DAILY, item. Default: item.

channel: Item channel, mshops or marketplace. Default value: marketplace.


Request:

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

Response:

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

Daily Ad Metrics

Example:

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

Response:

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

Glossary

total: total number of records obtained.

offset: default value: 0.

limit: limit of elements in the campaign list. Default: 50.

results: results obtained.

id: identifier of the ad or campaign.

budget: daily average of the campaign's (monthly) budget, that is, if the budget is not consumed during the day, the remaining budget will be used in the following days until the end of the month.

last_updated: date of last campaign modification.

date_created: campaign creation date.

price: price of the associated item.

title: name of the publication.

has_discount: whether it has a discount. This value is identified based on the difference between the regular amount and the amount provided by Prices API.

catalog_listing: catalog publication.

logistic_type: logistics type for item shipping.

listing_type_id: identifier of the publication type.

domain_id: domain.

date_created: date of ad creation.

official_store_id: identifier of the official store.

buy_box_winner: buy box winner.

channel: campaign channel (marketplace or mshops).

campaign_id: campaign identifier.

condition: Item condition.

current_level: reputation.

deferred_stock: available product stock. An item with manufacturing_time (availability time) causes the ad not to be displayed; ads with immediate stock are prioritized.

thumbnail: link to the thumbnail image.

permalink: link to the publication.

brand_value_id: identifier of the brand associated with the item.

brand_value_name: name of the brand associated with the item.

status: status of the ad or campaign.

recommended: the ad is recommended.

metrics: Item or campaign metrics.

clicks: Campaign clicks.

prints: Number of impressions (times the ad is displayed).

sov: Sales by advertising percentage over total sales.

clicks: Campaign clicks.

ctr: Click-through rate.

cost: Campaign investment.

cpc: Cost per click.

acos: Advertising cost of sales percentage over revenue.


Sales without advertising

  • organic_units_quantity: number of units sold without advertising.
  • organic_units_amount: organic order sales amount.
  • organic_items_quantity: cantidad de ventas sin publicidad.

Sales with advertising

  • Direct sells
    • direct_items_quantity: amount of direct sales from advertising.
    • direct_units_quantity: number of units sold in direct sales.
    • direct_amount: sum of the value of direct sales obtained from your Product Ad, in local currency.
  • Indirect sales
    • indirect_items_quantity: quantity of indirect sales from advertising.
    • indirect_units_quantity: number of units sold in assisted sales.
    • indirect_amount: sum of the value of assisted sales obtained from your Product Ad, in local currency.

advertising_items_quantity: Quantity of sales by advertising.

cvr: Conversion rate.

roas: Return on advertising spend.

units_quantity: Total quantity of sales.

total_amount: Sum of the value of sales obtained from your Product Ad, in local currency.

impression_share: Percentage of times ads are shown considering all the times they could be shown.

top_impression_share: Number of auctions won in the top search positions among the number of auctions it could participate in.

lost_impression_share_by_budget: Percentage of times ads are not shown considering all the times they could be shown and that didn't happen because the budget is too low.

lost_impression_share_by_ad_rank: Percentage of times ads are not shown considering all the times they could be shown and that didn't happen because your rank is lower than other sellers.

acos_benchmark: Target ACOS (advertising cost of sales) used by ads with good results in impressions and sales.

picture_id: Item image ID at the MercadoLibre level.

acos_target: Advertising cost of sales (ACOS) target used by ads with good results in impressions and sales.

strategy: Campaign strategy type. It can be PROFITABILITY, INCREASE, or VISIBILITY.

acos_top_search_target: ACOS (advertising cost of sales) target set for a campaign to specifically bid for top search results. For other auctions, the bid will be considered the ACOS target. It must be higher than the campaign's ACOS target and lower than 500.