Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentación
Display Ads
Campaign types and objectives
Campaign type | Objective | Key metrics |
---|---|---|
Programmatic | Awareness: increase the exposure of a brand or product among users of interest to you. | Scope and frequency. These metrics allow you to measure how many users you have reached with your ads and the number of times they have seen them in a certain period. With creative video available. |
Programmatic | Consideration: increases visits and user actions on a brand or product. | Clicks and VPP: these metrics allow you to measure how many times your ads were clicked and how many visits they generated to the product page. |
Programmatic | Conversion: increase sales of your brand's products with advertising. | Income and sales: these metrics allow you to quantify the sales generated after users view or click on your ads. |
Guaranteed | They are created and managed by the Mercado Libre operations team. | It allow to plan and purchase a certain number of impressions at a fixed CPM. |
Recommended Technical Flow
- Advertisers (advertiser id) for display
- Advertisers' campaigns
- Campaign metrics
Campaign Panel on Mercado Ads
![](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevSite/193700356621-image--108-.png)
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: PADS (Product Ads), 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": 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 it for the rest of the requests.
site_id: country identifier. Consult the sites of the Mercado Libre sites and their respective currencies.
advertiser_name: advertiser name.
account_name: account name.
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. Programmatic or Guaranteed.
status: campaign status.
site_id: country.
strategy: campaign objective. Coming soon.
:
Campaign metrics
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",
"site_id": "MLM",
"currency": "MXN",
"prints": 17961,
"clicks": 186,
"active_views": 0,
"completed_views": 0,
"reach": 10079,
"ctr": 0.01,
"consumed_budget": 57449.13,
"cpm": 3198.55,
"cpc": 308.87,
"average_frequency": 1148.98,
"event_time": {
"cpa_order": 1083.95,
"cpa_ppv": 135.81,
"roas": 10.03,
"units_quantity": 75,
"direct_amount": 576150,
"direct_item_quantity": 53,
"attribution_ppv": 423,
"attribution_add_to_cart": 26,
"attribution_bookmark": 33,
"attribution_checkout": 24,
"attribution_leads": 0,
"cpl": 0.0
},
"touch_point": {
"cpa_order": 1148.98,
"cpa_ppv": 125.16,
"roas": 12.36,
"units_quantity": 70,
"direct_amount": 710324,
"direct_item_quantity": 50,
"attribution_ppv": 459,
"attribution_add_to_cart": 26,
"attribution_bookmark": 35,
"attribution_checkout": 28,
"attribution_leads": 0,
"cpl": 0.0
}
}
],
"summary": {
"site_id": "MLM",
"currency": "MXN",
"prints": 170462,
"clicks": 2033,
"active_views": 0,
"completed_views": 0,
"reach": 48957,
"ctr": 0.01,
"consumed_budget": 605406.93,
"cpm": 3551.57,
"cpc": 297.79,
"average_frequency": 1509.74,
"event_time": {
"cpa_order": 1513.52,
"cpa_ppv": 128.59,
"roas": 9.48,
"units_quantity": 586,
"direct_amount": 5741691,
"direct_item_quantity": 400,
"attribution_ppv": 4708,
"attribution_add_to_cart": 263,
"attribution_bookmark": 375,
"attribution_checkout": 219,
"attribution_leads": 0,
"cpl": 0.0
},
"touch_point": {
"cpa_order": 1509.74,
"cpa_ppv": 125.66,
"roas": 9.49,
"units_quantity": 586,
"direct_amount": 5746421,
"direct_item_quantity": 401,
"attribution_ppv": 4818,
"attribution_add_to_cart": 270,
"attribution_bookmark": 352,
"attribution_checkout": 225,
"attribution_leads": 0,
"cpl": 0.0
}
}
}
Glossary
date: campaign date.
prints: impressions. It's the number of times your ads were shown.
clicks: number of times users clicked on your ads.
active_views: number of times users watched the first 6 seconds of your Social and Video ad.
completed_views: number of times users watched your entire Social and Video ad.
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.
- 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.
- attribution_leads: contacts generated by potential customers after they viewed or clicked on your ads.
- cpl: average cost of each lead based on investment.
Campaing Line items
The line item defines the purchase parameters of the ad: the user profile you want to reach, their geographic location, the device they are browsing from, among others. Each line item is associated with a single campaign and consumes its budget.
Optional parameter
sort_by: possible values: id, name, start_date, end_date.
sort_order: possible values: asc, 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/line_items?sort_by=start_date&sort_order=asc
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/123456/display/campaigns/987654/line_items?sort_by=start_date&sort_order=asc
Response:
{
"results": [
{
"line_item_id": 1,
"name": "Name_Line_Item_Test",
"start_date": "2022-01-12T17:00:00",
"end_date": "2022-01-31T23:59:00",
"campaing_id": 987654,
"type": "Social",
"status": "paused"
}
]
}
Response field
line_item_id: line item id.
name: line item name.
start_date: start date of the item line.
end_date: end of line item date.
type: line item type. Assigned creative agreement variable.
- Display: native image and text banner. Suitable for different Mercado Libre and Mercado Pago advertising spaces.
- Social: video in vertical format with lower banner. Available for Mercado Libre Clips spaces.
- Video: video in horizontal format. Available for streaming platforms integrated with Mercado Ads. This type of solo line item is enabled for campaigns with the objective Awareness.
status: line item status.
Line item creatives
Optional parameters
sort_by: possible values: id, name.
sort_order: possible values: asc, 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/line_items/$LINE_ITEM_ID/creatives?sort_by=start_date&sort_order=asc
Example:
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/999999/line_items/0000001/creatives?sort_by=start_date&sort_order=asc
Response:
{
"results": [
{
"creative_id": 123456,
"name": "Name_Creative_Test",
"status": "active",
"line_item_id": 0000001,
"campaign_id": 999999
}
]
}
Response fields
creative_id: id del creativo.
name: nombre del creativo.
status: estado del creativo. Puede ser: active.
line_item_id: line item id.
campaign_id: campaign id.
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. |
not_found | 404 | No line items found for campaign_id {campaign_id} |
not_found | 404 | No campaigns found for advertiser id {advertiser_id} Campaign not found for sent campaign_id. |