Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
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: 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": 36,
"site_id": "MLM"
}
]
}
Search campaigns by advertiser
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
}
]
}
]
}
Consult campaign by advertiser
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 items of a campaign
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"
}
]
Query campaign items
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"
}
]
Query 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.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/metrics
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
}
}
}
Response fields
prints (impressions): the number of times your ads were displayed.
clicks: number of times users clicked on your ads.
ctr (click-through rate): the ratio of clicks to impressions.
cvr (conversion rate): the ratio of conversions to clicks.
consumed_budget (investment): the amount of money spent to display your ads.
cpc (cost per click): the average cost paid for each click received on the ads.
acos (advertising cost of sales): the ratio of advertising spend to attributed sales.
event_time: metrics attributed by action date, shown associated with the exact date the action was taken (e.g., sales).
units_quantity (sales): the number of times users made a purchase after viewing or clicking on your ads.
units_amount (revenue): the total value generated by sales attributed to your ads.
items_quantity: the quantity 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: the number of attributable items marked as favorites after viewing or clicking on your ads.
cart_conversions: the number of attributable items added to the shopping cart after viewing or clicking on your ads.
checkout_conversions: 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.
touch_point: metrics attributed by view 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 quantity 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: the number of attributable items marked as favorites after viewing or clicking on your ads.
- cart_conversions: the number of attributable items added to the shopping cart after viewing or clicking on your ads.
- checkout_conversions: 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.
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
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/metrics
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
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
}
}
]
}
Next: Display Ads.