Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Product Ads
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_IDExample:
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": 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.
Ad Details
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'api-version: 2'
https://api.mercadolibre.com/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
}
}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/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",
"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=DAILYResponse:
{
"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=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/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/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 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_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 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=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 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=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
}
}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_amountResponse:
{
"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=DAILYResponse:
{
"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.