Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
Display Ads
Recommended Technical Flow
- Advertisers (advertiser id) for display
- Advertisers' campaigns
- Campaign metrics
Campaign Panel on Mercado Ads
Consult 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.
Mandatory parameters
product_id: product type. Available values: DISPLAY, BADS (Brand Ads)
Optional parameters
sort_by: sorts by attribute (advertiser_id, site_id). Default advertiser_id.
sort_order: order (asc, desc). Default is desc.
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=DISPLAY
Response:
{
"advertisers": [
{
"advertiser_id": 36,
"site_id": "MLM"
}
]
}
Response fields
Advertiser_id: advertiser identifier. You will use it for the rest of the requests.
Site_id: country identifier. Consult the sites of the Mercado Libre sites and their respective currencies.
Consult advertiser campaigns
Optional parameters
sort_by: sorts by attribute (id, name, start_date, end_date). Default is id.
sort_order: order (asc, desc). Default is desc.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/61/display/campaigns?sort_by=start_date&sort_order=desc
Response:
{
"results": [
{
"id": 80,
"name": "CONVERSION_ENERO2022_MLA",
"start_date": "2022-01-12T17:00:00",
"end_date": "2022-01-31T23:59:00",
"advertiser_id": 61,
"type": "GUARANTEED",
"status": "paused",
"site_id": "MLA"
}
]
}
Response fields
id: campaign id. Use the id to consult campaign metrics.
name: campaign name.
start_date: campaign start date.
end_date: campaign end date.
advertiser_id: advertiser id
type: campaign type.
status: campaign status.
site_id: country.
Campaign metrics query
The results of this endpoint will be the metrics per day and a summary for the campaign date range. You can consult up to 90 days ago, considering September 1, 2022 as the initial date.
Mandatory parameters
date_from: date since of the query in format YYYY-MM-DD.
date_to: date until query in format YYYY-MM-DD.
Optional parameters
sort_by: order by attribute: id, name, start_date, end_date. Default is id.
sort_order: order ascending (asc) and descending (desc). Default is desc.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/$CAMPAIGN_ID/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/61/display/campaigns/80/metrics?date_from=2024-04-01&date_to=2024-04-15
Response:
{
"metrics":[
{
"date":"2024-02-01",
"prints":17961,
"clicks":186,
"reach":10079,
"ctr":0.01,
"consumed_budget":57449.13,
"cpm":3198.55,
"cpc":308.87,
"average_frequency":1.78,
"event_time":{
"cpa_order":1083.95,
"cpa_ppv":135.81,
"roas":10.03,
"units_quantity":159,
"direct_amount":50,
"direct_item_quantity":75,
"attribution_ppv":423,
"attribution_add_to_cart":26,
"attribution_bookmark":33,
"attribution_checkout":24
},
"touch_point":{
"cpa_order":1148.98,
"cpa_ppv":125.16,
"roas":12.36,
"units_quantity":50,
"direct_amount":7103.24,
"direct_item_quantity":70,
"attribution_ppv":459,
"attribution_add_to_cart":26,
"attribution_bookmark":35,
"attribution_checkout":28
}
}
],
"summary":{
"prints":170462,
"clicks":2033,
"reach":48957,
"ctr":0.01,
"cpm":3551.57,
"cpc":297.79,
"average_frequency":3.48,
"event_time":{
"cpa_order":1513.52,
"cpa_ppv":128.59,
"roas":9.48,
"attribution_order":400,
"direct_amount":5741691.0,
"direct_item_quantity":586,
"attribution_ppv":4708,
"attribution_add_to_cart":263,
"attribution_bookmark":375,
"attribution_checkout":219
},
"touch_point":{
"cpa_order":1509.74,
"cpa_ppv":125.66,
"roas":9.49,
"attribution_order":401,
"direct_amount":5746421.0,
"direct_item_quantity":586,
"attribution_ppv":4818,
"attribution_add_to_cart":270,
"attribution_bookmark":352,
"attribution_checkout":225
}
}
}
Response fields
date: campaign date.
prints: impressions. It's the number of times your ads were shown.
clicks: number of times users clicked on your ads.
reach: Reach. It's the number of unique users who saw your ads.
ctr: Click-Through Rate. Clicks received as a percentage of total impressions.
consumed_budget: Investment: It's the amount of money actually spent to show your ads.
cpm: average cost paid for each thousand impressions of the ads.
cpc: Cost per Click. It's the average cost paid for each click received on the ads.
average_frequency: Average frequency. Average number of times your ads were shown to the same user.
Attribution metrics have two ways of being presented:
Event Time Attribution Metrics (event_time): metrics will be shown associated with the exact date the action was taken (e.g., Sales).
Touchpoint Attribution Metrics (touch_point): metrics will be shown associated with the date of the click or visible impression to which they were attributed.
- cpa_order: average cost of each sale based on investment.
- cpa_ppv: average cost of each product page view based on investment.
- roas: return on advertising spend.
- atribution_order:
- units_quantity: quantity of units of your products sold across all purchases attributed to your ads.
- direct_amount (revenue): total value of sales attributed to your ads.
- direct_item_quantity: number of times users made a purchase after viewing or clicking on your ads.
- attribution_ppv (product page views): number of times users visited your product page after viewing or clicking on your ads.
- attribution_add_to_cart: number of times users added your promoted products to the shopping cart after viewing or clicking on your ads.
- attribution_bookmark: number of times users bookmarked your promoted products after viewing or clicking on your ads.
- attribution_checkout: number of times users initiated a purchase process of your promoted products after viewing or clicking on your ads.
Errors
Error | Status | Message |
---|---|---|
bad_request | 400 | The parameter {paramKey} is required. |
not_found | 404 | No campaigns found for advertiser id {advertiser_id} Campaign not found for sent campaign_id. |