Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentação do
Brand Ads
Recommended Technical Flow
- Consult advertiser (advertiser id)
- Consult campaign, items campaings and keywords
- Consult metrics of advertiser, campaigns and keyword
Consult advertiser
Advertisers (advertiser_id) are those who invest a budget in creating and distributing advertising, with the aim of promoting their products or services. Consult the list of advertisers that a user has access to, based on the required product type.
Mandatory 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=BADS
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 nomenclature of Mercado Libre sites and their respective currencies.
advertiser_name: advertiser name.
account_name: account name.
Types of campaigns
Before consulting campaigns, we recommend that you know the types of campaigns. In addition, you can access campaign metrics from 2023-02-09.
- Automatic: automatic campaigns are managed by Mercado Ads. The campaign will be automatically executed for all items associated with the official_store_id of the destination_id sent and will create keywords, which cannot be edited or deleted, that is, Mercado Ads will manage the advertiser's inventory and assign the best keywords for their ads.
- Custom: Personalized campaigns are created and managed by the user, where the advertiser must provide a list of items (minimum 3, maximum 10) with which to configure their ad and the keywords (minimum 1, maximum 200) that are keywords. for searches in which you want to be printed. You can then edit and delete these keywords.
Search campaigns
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns
Response:
{
"paging": {
"total": 50,
"offset": 0,
"limit": 2
},
"campaigns": [
{
"campaign_id": 1,
"name": "campaign meli 1",
"start_date": "2024-01-01T00:06:22.000Z",
"end_date": "2024-01-01T00:06:22.000Z",
"advertiser_id": 1234,
"campaign_type": "custom",
"status": "active",
"site_id": "MLA",
"official_store_id": 12345,
"destination_id": 12345,
"headline": "this is a headline",
"budget": {
"amount": 1111111.32,
"currency": "ARS"
},
"cpc": 100.5,
"items": [
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
],
"keywords": [
{
"campaign_id": 1,
"type": "custom",
"term": "car",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]
}
]
}
Campaign detail
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID
Response:
{
"campaign_id": 1,
"name": "campaign meli 1",
"start_date": "2024-01-01T00:06:22.000Z",
"end_date": "2024-01-01T00:06:22.000Z",
"advertiser_id": 1234,
"campaign_type": "custom",
"status": "active",
"site_id": "MLA",
"official_store_id": 12345,
"destination_id": 12345,
"headline": "this is a headline",
"budget": {
"amount": 1111111.32,
"currency": "ARS"
},
"cpc": 100.5,
"items": [
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
],
"keywords": [
{
"campaign_id": 1,
"keyword_id": 1,
"type": "custom",
"term": "car",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]
}
Consult campaign ads
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/items
Response:
[
{
"campaign_id": 1,
"status": "active",
"item_id": "MLA1178375484"
}
]
Consult campaign keywords
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywords
Response:
[
{
"campaign_id": 1,
"type": "custom",
"term": "auto",
"match_type": "phrase",
"is_negative": false,
"cpc": 50.5
}
]
Advertiser campaigns metrics
Mandatory parameters
date_from: start date of the query in YYYY-MM-DD format.
date_to: end date of the query in YYYY-MM-DD format.
Optional parameters
limit: default is 50.
offset: default is 0.
aggregation_type: type of data aggregation to display. Possible values: daily, total. By default, it returns both.
fields: specific metrics fields to query.
Available filters
status: campaign status. Values: active, paused.
destination_id: destination id of the campaign.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&aggregation_type=daily
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/10101010/brand_ads/campaigns/metrics?date_from=2024-07-01&date_to=2024-07-10&aggregation_type=daily
Response:
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2024-01-08",
"site_id": "MLA",
"currency": "ARS",
"prints": 0,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
],
"summary": {
"site_id": "MLA",
"currency": "ARS",
"prints": 0,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
}
Campaign daily metrics
Mandatory parameters
date_from: start date of the query in YYYY-MM-DD format.
date_to: end date of the query in YYYY-MM-DD format.
Optional parameters
limit: default is 50.
offset: default is 0.
aggregation_type: type of data aggregation to show. Possible values: daily, total. By default, both are returned.
fields: specific metric fields to query.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/10100101/brand_ads/campaigns/123456/metrics?date_from=2024-07-01&date_to=2024-07-10
Response:
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2024-01-02",
"prints": 2026,
"site_id": "MLA",
"currency": "ARS",
"clicks": 20,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 3000.00,
"cpc": 150.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
],
"summary": {
"prints": 2026,
"clicks": 20,
"site_id": "MLA",
"currency": "ARS",
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 3000.00,
"cpc": 150.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"competitive": {
"lost_impression_share_by_budget": 0.7,
"lost_impression_share_by_ad_rank": 0.04,
"impression_share": 0.26,
"competitive_cpc": 175.0
}
}
}
Campaign keyword daily metrics
Get keyword metrics for each day for a specific campaign.
Mandatory parameters
date_from: start date of the query in YYYY-MM-DD format.
date_to: end date of the query in YYYY-MM-DD format.
Optional parameters
limit: default is 50.
offset: default is 0.
aggregation_type: type of data aggregation to show. Possible values: daily, total. By default, both are returned.
fields: specific metric fields to query.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywords/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/101010/brand_ads/campaigns/123456/keywords/metrics?date_from=2024-07-01&date_to=2024-07-10
Response:
{
"paging": {
"total": 1,
"offset": 0,
"limit": 90
},
"metrics": [
{
"date": "2024-01-08",
"keywords": [
{
"keyword": "cloruro magnesio",
"site_id": "MLA",
"currency": "ARS",
"prints": 2,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
]
}
],
"summary": [
{
"keyword": "cloruro magnesio",
"site_id": "MLA",
"currency": "ARS",
"prints": 2,
"clicks": 0,
"ctr": 0.00,
"cvr": 0.00,
"consumed_budget": 0.00,
"cpc": 0.00,
"acos": 0,
"event_time": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
},
"touch_point": {
"units_quantity": 0,
"units_amount": 0.00,
"items_quantity": 0,
"ppv_conversions": 0,
"bookmark_conversions": 0,
"cart_conversions": 0,
"checkout_conversions": 0,
"leads_question_conversions": 0,
"leads_im_conversions": 0,
"eshop_conversions": 0
}
}
]
}
Glossary
prints (impressions): the number of times your ads were displayed.
clicks: the number of times users clicked on your ads.
ctr (click-through rate): the rate of clicks obtained over the total impressions.
cvr (conversion rate): the conversion rate with respect to clicks.
consumed_budget (investment): the amount of money actually spent to display your ads.
cpc (cost per click): the average cost paid for each click your ads received.
acos (advertising cost of sales): investment income/expense, advertising sales cost.
Metrics can be attributed:
event_time: metrics attributed by action date, shown associated with the exact date the action was taken (e.g., sales).
touch_point: metrics attributed by viewing date, shown associated with the date of click or visible impression that generated them.
- units_quantity (sales): the number of times users made a purchase after viewing or clicking on the ads.
- units_amount (revenue): the total value generated by sales attributed to your ads.
- items_quantity: the number of items sold by attributions.
- ppv_conversions (product page views): the number of views to product pages after viewing or clicking on your ads.
- bookmark_conversions (bookmark): the number of attributable items marked as favorites after viewing or clicking on your ads.
- cart_conversions (cart): the number of attributable items added to the shopping cart after viewing or clicking on your ads.
- checkout_conversions (checkout): the number of attributable items for which the purchase process was initiated after viewing or clicking on your ads.
- leads_question_conversions: the number of potential customers interested in purchasing your product who asked questions in your listing after clicking on your ads.
- leads_im_conversions: the number of potential customers interested in purchasing your product who contacted you via WhatsApp from your listing after clicking on your ads.
- eshop_conversions: the number of attributed sales.
competitive: array with competitiveness metrics. They are shown only at the campaign level and reflect their impression distribution, i.e., they are percentages of times your ads were displayed or not in relation to 100% of times they could have been. They are calculated with data from the last 7 days. The period will be selectable soon. Metrics can be:
- lost_impression_share_by_budget (Losses due to budget): loss percentage, meaning potential impressions that were not capitalized due to low budget. For example: if it is 10, it means that the campaign lost impressions 10% of the times it could have had them due to insufficient budget. In these cases, we recommend increasing the budget.
- lost_impression_share_by_ad_rank (Losses due to ranking): loss percentage, meaning potential impressions that were not capitalized due to low ranking. For example, if the result is 30, the campaign lost impressions 30% of the times it could have had them due to insufficient ad-rank.
The ad rank consists of the Acos Target and the Quality Score (internal metric, not directly manageable). To improve impressions won by ranking, we suggest focusing on the following points:
Review the maximum CPC: it is recommended to be within the average of your competition for better results.
Verify that the campaign is targeted to the correct keywords: we recommend having different campaigns, so you can target specific keywords in each one.
Improve the quality of your listing: the quality of photos, product descriptions, and even shipping conditions can play an important role in your ranking.
Maintain your reputation: post-sales service and product ratings can differentiate you when competing. Learn more about the Publication Quality API.
- impression_share (Impressions won): success percentage, meaning effective impressions, i.e., the percentage of times the campaign won the auctions in which it participated with that keyword. It is the number of impressions obtained divided by the estimated/potential impressions it could have had. For example: if it is 60%, it means that the campaign won and was displayed 60% of the times it could have.
- competitive_cpc: the CPC of the competition.
Next: Display Ads.