Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Product Ads
Recommended technical flow
- Consult advertiser
- Campaigns
- Create campaign
- Modify campaign
- Ads
- Ad details
- Modify an ad and up to 10,000
- Metrics
- Campaign metrics
- Ad metrics
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: PADS (Product 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=PADSResponse:
{
"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": 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.
Create campaign
When creating a campaign, you must send all the campaign-specific parameters:
- name: campaign name. Allows for quicker identification of grouped ads.
- status: campaign status. Can be: active or paused.
- budget: average daily budget of the campaign will vary daily. This will increase sales opportunities and make the investment more efficient. It is the maximum amount charged per day for clicks on ads.
- strategy: type of campaign strategy. Can be:
- profitability: with the Profitability strategy, the platform will show fewer ads but to users with a higher probability of buying the advertised product. This strategy is recommended for product listings that already have many sales on Mercado Libre.
- increase: with the Growth strategy, a balance between profitability and visibility is sought. Here you will aim to spend an intermediate amount to appear more often, but not so much as to compromise your profits. It is suggested for products with a good level of sales on Mercado Libre, but not your top-selling products ("medium-turnover products").
- visibility: with the Visibility strategy, you will seek to invest more in advertising in exchange for showing ads to as many users as possible. It is recommended for new listings.
- channel: campaign channel. Can be marketplace (Mercado Libre marketplace) or mshops (drives traffic to the online store on Mercado Shops). Default is marketplace.
- acos_target: advertising cost of sales (ACOS Target), it is the percentage of the campaign/ad cost in relation to the income obtained. It helps the Product Ads algorithm to define how to invest your budget. For each strategy, Mercado Libre provides a reference for ACOS Target. It should be higher than 3 and lower than 500.
What is the daily limit that my campaign can consume? It can be up to double (100%) of your original budget, using the balance that you did not consume in previous days. If your daily budget is $1,000, we will invest a maximum of $2,000 if you have $1,000 left over from previous days. This optimizes the investment and in the end you will never pay more than your budget limit.
What happens if I change my budget during the month? We restart the calculation and take into account the new value. In your billing we will consider the budgets that the campaign had for 30 days. Example: At the beginning of the month you set a budget of $1,000 and on the 21st you changed it to $500. At the end of the month you will pay a maximum of $25,000 ($1,000 x 20 days + $500x the remaining days of the month).
What happens if I pause my campaign in the middle of the month? You will no longer consume the budget you set for the campaign. In your monthly billing you will only see the consumption of the days it was active.
Example:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/marketplace/advertising/advertisers/$ADVERTISER_ID/product_ads/campaigns
{
"name": "Main Campaign",
"status": "active",
"budget": 25,
"strategy": "profitability",
"channel": "marketplace",
"acos_target": 15,
"acos_top_search_target": 30
}Response:
{
"id": 11111111,
"name": "Main Campaign",
"status": "active",
"budget": 25,
"currency_id": "ARS",
"last_updated": "2024-03-04T15:00:41.568Z",
"date_created": "2024-03-04T15:00:41.569Z",
"strategy": "profitability",
"channel": "marketplace",
"acos_target": 15,
"acos_top_search_target": 30
}Modify campaign
When updating a campaign, you must send at least one of the parameters you want to update.
Example:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/marketplace/advertising/product_ads/campaigns/$CAMPAIGN_ID
{
"name": "test campaign",
"budget": 20,
"status": "active",
"acos_target": 15,
"acos_top_search_target": 30,
"strategy": "visibility"
}Response:
{
"id": 123456,
"name": "test_campaign",
"status": "active",
"budget": 20,
"currency_id": "ARS",
"last_updated": "2024-02-26T15:56:32.395Z",
"date_created": "2024-02-26T15:56:32.395Z",
"strategy": "visibility",
"acos_target": 15,
"acos_top_search_target": 30
"channel": "marketplace"
}Response fields
id: Campaign ID.
name: Campaign name.
status: Campaign status.
budget: Daily campaign budget. If the Ads Manager is using all of the daily budget allocated to a campaign, the campaign probably has the capacity to consume more budget and continue showing ads, but it is not doing so because the budget is not sufficient.
currency_id: Currency of the daily campaign budget. By default, it is calculated based on the site.
acos_target: Advertising Cost of Sales (ACOS) target. It is the percentage of the campaign/ad cost in relation to the income obtained. Must be higher than 3 and lower than 500.
acos_top_search_target (ACOS target): for the top search results. Must be higher than the campaign's ACOS target and lower than 500.
strategy: type of campaign strategy. Can be profitability, increase, and visibility.
channel: campaign channel. Can be marketplace and mshops. Default is marketplace.
last_updated: date of the last campaign modification.
date_created: campaign creation date.
Ad details
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/marketplace/advertising/product_ads/items/$ITEM_IDResponse:
{
"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
}
}Modify Ad
To modify an ad, you can send one or both parameters within the update:
- status: update only the status of the ad (between active and paused) or
- campaign_id: update only the campaign it belongs to. If the ad does not have campaigns and is added to a campaign, it will be active by default. If the ad is removed from a campaign, it will be in idle status (the item is available for advertising but not in any advertising campaign).
Mandatory parameters
channel: channel where the item is published (marketplace or mshops). Default: marketplace.
Example:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'-H 'api-version: 2'
https://api.mercadolibre.com/marketplace/advertising/product_ads/items/$ITEM_ID?channel=marketplace
{
"status": "active",
"campaign_id": 1234567
}Response:
{
"item_id": "MLB123",
"status": "active",
"campaign_id": 1234567,
"title": "Item title",
"permalink": "https://articulo.mercadolibre.com.ar/test.jpg",
"thumbnail": "http://mla-s2-p.mlstatic.com/test.jpg",
"picture_id": "ABCD_12345_ZYX",
"date_created": "2024-02-26T20:07:07.002Z",
"last_updated": "2024-02-26T20:07:07.002Z",
"channel": "string",
"advertiser_id": 0
}Modify up to 10.000 ads
To modify up to 10,000 items, the first 50 items sent will be updated synchronously and the impacted items will be returned. The remaining items, i.e., from 51 to 10,000, will be processed asynchronously and will respond with http 200. This does not mean that the item will have been moved at that time, but that it will be processed in the background with eventual consistency.
Example:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/marketplace/advertising/advertisers/$ADVERTISER_ID/product_ads/items?channel=marketplace
{
"target": ["MLA123", "MLA124", "MLA125"],
"payload": {
"status": "active",
"campaign_id": 1234556
}
}Response:
{
"results": [
{
"item_id": "MLB123",
"status": "active",
"campaign_id": 1234567,
"title": "Item title 1",
"permalink": "https://articulo.mercadolibre.com.ar/test.jpg",
"thumbnail": "http://mla-s2-p.mlstatic.com/test.jpg",
"picture_id": "ABCD_12345_ZYX1",
"date_created": "2024-02-26T20:07:07.002Z",
"last_updated": "2024-02-26T20:07:07.002Z",
"channel": "marketplace",
"advertiser_id": 123
},
{
"item_id": "MLB124",
"status": "active",
"campaign_id": 1234567,
"title": "Item title 2",
"permalink": "https://articulo.mercadolibre.com.ar/test.jpg",
"thumbnail": "http://mla-s2-p.mlstatic.com/test1.jpg",
"picture_id": "ABCD_12345_ZYX2",
"date_created": "2024-02-26T20:07:07.002Z",
"last_updated": "2024-02-26T20:07:07.002Z",
"channel": "marketplace",
"advertiser_id": 123
},
{
"item_id": "MLB125",
"status": "active",
"campaign_id": 1234567,
"title": "Item title 3",
"permalink": "https://articulo.mercadolibre.com.ar/test.jpg",
"thumbnail": "http://mla-s2-p.mlstatic.com/test2.jpg",
"picture_id": "ABCD_12345_ZYX3",
"date_created": "2024-02-26T20:07:07.002Z",
"last_updated": "2024-02-26T20:07:07.002Z",
"channel": "marketplace",
"advertiser_id": 123
}
]
}item_id: id of the item at Mercado Libre level.
status: status of the item within Product Ads.
campaign_id: id of the campaign to which the item belongs.
title: title of the item.
thumbnail: thumbnail of the item.
permalink: permalink of the item.
picture_id: picture id of the item.
channel: sales channel to which the item belongs within Product Ads.
advertiser_id: advertiser to which the item belongs within Product Ads.
last_updated: date of last update of the item within Product Ads.
date_created: date of creation of the item within Product Ads.
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.
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/marketplace/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_amountResponse:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 1
},
"results": [
{
"id": 0,
"name": "Crecimiento A",
"status": "active",
"budget": 0.00,
"currency_id": "ARS",name
"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/marketplace/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=DAILYResponse:
{
"results": [
{
"clicks": 43,
"prints": 5676,
"cost": 35.0,
"cpc": 0.81,
"direct_amount": 149.05,
"indirect_amount": 149.05,
"total_amount": 298.1,
"direct_units_quantity": 1,
"indirect_units_quantity": 1,
"units_quantity": 2,
"direct_items_quantity": 1,
"indirect_items_quantity": 1,
"advertising_items_quantity": 2,
"organic_units_quantity": 12,
"organic_items_quantity": 9,
"acos": 11.74,
"organic_units_amount": 1260.0,
"sov": 18.18,
"ctr": 0.76,
"cvr": 4.65,
"roas": 851.71,
"date": "2024-08-01"
},
{
"clicks": 54,
"prints": 7484,
"cost": 33.36,
"cpc": 0.62,
"direct_amount": 310.88,
"indirect_amount": 175.47,
"total_amount": 486.35,
"direct_units_quantity": 2,
"indirect_units_quantity": 1,
"units_quantity": 3,
"direct_items_quantity": 2,
"indirect_items_quantity": 1,
"advertising_items_quantity": 3,
"organic_units_quantity": 12,
"organic_items_quantity": 9,
"acos": 6.86,
"organic_units_amount": 963.0,
"sov": 25.0,
"ctr": 0.72,
"cvr": 5.56,
"roas": 1457.88,
"date": "2024-08-02"
},
...
}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/marketplace/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=trueResponse:
{
"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/marketplace/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_benchmarkResponse:
{
"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/marketplace/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=DAILYResponse:
{
[
{
"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 values: 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.
Ads 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/marketplace/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_amountResponse:
{
"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 ads metrics
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/marketplace/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=DAILYResponse:
{
"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 ads metrics
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/marketplace/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=trueResponse:
{
"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
}
}Ads 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/marketplace/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_amountResponse:
{
"item_id": "MLB19901111111",
"campaign_id": 34858222,
"price": 160.9,
"price_usd": 0.0,
"title": "Kit 20 Pares Futebol",
"status": "active",
"has_discount": false,
"catalog_listing": false,
"logistic_type": "fulfillment",
"listing_type_id": "gold_pro",
"domain_id": "MLB-FOOTBALL_SOCKS",
"date_created": "2021-08-25T12:17:33Z",
"buy_box_winner": false,
"tags": [
"sll"
],
"channel": "marketplace",
"brand_value_id": "4220111",
"brand_value_name": "Sports",
"condition": "new",
"current_level": "green",
"deferred_stock": false,
"thumbnail": "http://http2.mlstatic.com/D_726420-MLB7411165_022024-I.jpg",
"permalink": "https://produto.mercadolivre.com.br/MLB-111-kit-20-pares-meio-preto-futebol-adulto-atacado-37-44-_JM",
"recommended": true,
"image_quality": "good_quality_thumbnail",
"metrics": {
"clicks": 282,
"prints": 38255,
"cost": 310.77,
"cpc": 1.1,
"direct_amount": 2787.73,
"indirect_amount": 134.88,
"total_amount": 2922.61,
"direct_units_quantity": 19,
"indirect_units_quantity": 1,
"units_quantity": 20,
"direct_items_quantity": 19,
"indirect_items_quantity": 1,
"advertising_items_quantity": 20,
"organic_units_quantity": 21,
"organic_items_quantity": 21,
"acos": 10.63,
"organic_units_amount": 3001.0,
"sov": 48.78,
"ctr": 0.74,
"cvr": 7.09,
"roas": 940.44
}
}Daily Ad Metrics
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/marketplace/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=DAILYResponse:
{
"results": [
{
"clicks": 7,
"prints": 307,
"cost": 8.26,
"cpc": 1.18,
"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": 1,
"organic_items_quantity": 1,
"acos": 0.0,
"organic_units_amount": 137.0,
"sov": 0.0,
"ctr": 2.28,
"cvr": 0.0,
"roas": 0.0,
"date": "2024-01-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.