Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Última atualização em 17/05/2024
Product Ads
This API will let you create advertising campaigns to promote ads (publications with advertising) in Mercado Libre in order to get more visits and sales. Through Mercado Ads you will be able to boost performance and increase sales.
Budget-limits
Before setting up a campaign, check the budget limits. Each user is assigned a minimum and maximum advertising budget. You can freely choose your daily investment within this rate.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/budgets/limits?campaign_type=defaultResponse:
{
"campaign_type": "default",
"minimum": 100,
"maximum": 50000,
"maximum_percentage": 30,
"minimum_percentage": 0.5,
"recommended_minimum": 500
}- campaign_type: campaign type
- minimum: minimum amount of advertising budget.
- maximum: maximum amount of advertising budget.
- maximum_percentage: maximum percentage.
- minimum_percentage: minimum percentage.
- recommended_minimum: recommended minimum.
Create a campaign
All ads must be grouped in a campaign, whose budget will be distributed among all the ads within it.
Parameters
- Budget: (required) must be within your user's budget limits.
- Status: (optional) is active by default.
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns
{
"budget": 20,
"status": "active"|"paused",
}Respomse:
{
"id": 223493019,
"name": "Campanha Principal",
"user_id": 348252660,
"type": "default",
"status": "active",
"budget": 225,
"last_updated": "2018-08-23T18:31:11.897Z",
"date_created": "2018-08-23T18:31:11.897Z"
}Modify a campaign
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID
{
"status": "active"|"paused",
"budget":225
}Consult a campaing
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_IDExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/223493019Response:
{
"id": 223493019,
"name": "Campanha Principal",
"user_id": 348252660,
"type": "default",
"status": "active",
"budget": 225,
"last_updated": "2018-08-23T18:56:33.000Z",
"date_created": "2018-08-23T04:00:00.000Z"
}Search for a campaign by user
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=$USER_IDExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=123456Response:
{
"paging":{
"total":1,
"offset":0,
"limit":10
},
"results":[
{
"id":223703005,
"name":"Campanha Principal",
"user_id":301254033,
"type":"default",
"status":"active",
"budget":225.0,
"last_updated":"2018-08-24T04:00:00.000Z",
"date_created":"2018-08-24T04:00:00.000Z"
}
]
}Campaign metrics
You can consult campaign metrics with a date rate that does not exceed 90 days.
Required parameters
- date_from: formatted aaaa-mm-dd, example 2018-08-01
- date_to: formatted aaaa-mm-dd, example 2018-08-10
- campaign_id: id of the campaign.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/metrics?date_from=AAAA-MM-DD&date_to=AAAA-MM-DDResponse:
{
"id": 289823066,
"clicks": 4315,
"impressions": 532218,
"ctr": 0.81,
"cost": 26200.179999999993,
"cpc": 6.07,
"sold_quantity_direct": 237,
"sold_quantity_indirect": 84,
"sold_quantity_total": 321,
"amount_direct": 182859.14,
"amount_indirect": 74808.53,
"amount_total": 257667.67,
"advertising_fee": 10.17,
"share": 10.89,
"organic_sold_items_quantity": 2424,
"sold_items_quantity_direct": 200,
"sold_items_quantity_indirect": 77,
"sold_items_conversion": 277
}Response fields
- id: campaign id.
- clicks: how many clicks the campaign received.
- impressions: number of impressions on the site that the campaign received.
- ctr: click through rate, expressed as a percentage, the division between clicks and impressions.
- cost: total cost of clicks for the period, in local currency.
- cpc: the average cost of each click, in local currency.
- sold_quantity_direct: amount of direct sales.
- sold_quantity_indirect: number of assisted sales.
- sold_quantity_total: total amount of sales.
- amount_direct: sum of the value of direct sales obtained through your Product Ads, in local currency. You have a direct sale when a user clicks on your Product Ad and buys that product.
- amount_indirect: sum of the value of assisted sales obtained through your Product Ads, in local currency. You have an assisted sale when a user clicks on your Product Ad and buys another of your products.
- amount_total: sum of the value of the sales obtained through your Product Ads, in local currency.
- advertising_fee: expressed as a percentage, the division between advertising investment on the revenue obtained, cost / amount_total. A lower value implies a better performance. share: percentage of sales through advertising over total sales.
- organic_sold_items_quantity: amount of sales without advertising.
- sold_items_quantity_direct: amount of direct sales by advertising.
- sold_items_quantity_indirect: quantity of indirect sales per advertising.
- sold_items_conversion: quantity of sales through advertising.
Ad metrics
You can consult in the same request, implementing multiget up to 50 Product Ads. A date range not exceeding 90 days must also be sent.
Parâmetros
- date_from: required field, formatted yyyy-mm-dd, example 2018-08-01.
- date_to: required field, formatted yyyy-mm-dd, example 2018-08-10.
- campaign_id: required field, campaign id.
- ids: required field, list of up to 50 comma separated item ids, example MLA1234, MLA4321.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/ads/metrics?date_from=AAAA-MM-DD&date_to=AAAA-MM-DD&ids=$ITEM_ID_1,$ITEM_ID_2Response:
[{
"id": "MLA1275028260",
"clicks": 0,
"impressions": 0,
"cost": 0.0,
"cost_usd": 0.0,
"cpc": 0.0,
"cpc_usd": 0.0,
"ctr": 0.0,
"sold_quantity_direct": 0,
"sold_quantity_indirect": 0,
"sold_quantity_total": 0,
"amount_direct": 0.0,
"amount_indirect": 0.0,
"amount_total": 0.0,
"amount_direct_usd": 0.0,
"amount_indirect_usd": 0.0,
"amount_total_usd": 0.0,
"advertising_fee": 0.0,
"organic_orders_quantity": 0,
"share": 0.0,
"organic_sold_items_quantity": 0,
"sold_items_quantity_direct": 0,
"sold_items_quantity_indirect": 0,
"sold_items_conversion": 0
}]Response fields
- id: campaign id.
- impressions: number of impressions the Product Ad received on the site.
- clicks: number of clicks the Product Ad received.
- ctr: click through rate, expressed as a percentage, the division between clicks and impressions.
- cost: the total cost of clicks for the period, in local currency.
- cpc: the average cost of each click, in local currency.
- sold_quantity_direct: quantity of units sold in direct sales.
- sold_quantity_indirect: quantity of units sold in assisted sales.
- sold_quantity_total: quantity of units sold by advertising.
- amount_direct: sum of the direct sales value obtained from your Product Ad, in local currency.
- amount_indirect: sum of the value of the assisted sales obtained from your Product Ad, in local currency.
- amount_total: sum of the value of the sales obtained from your Product Ad, in local currency.
- amount_total: a lower value implies a better performance.
- advertising_fee: expressed as a percentage, the division between advertising investment and revenue earned.
- organic_orders_quantity: quantity of units sold without advertising.
- share: percentage of sales through advertising over total sales.
- organic_sold_items_quantity: amount of sales without advertising.
- sold_items_quantity_direct: amount of direct sales by advertising.
- sold_items_quantity_indirect: quantity of indirect sales per advertising.
- sold_items_conversion: quantity of sales through advertising.
Consult ad associated to an item
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/{item_id}Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/{item_id}Response:
{
"id": "MLA657316800",
"campaign_id": 141072850,
"user_id": 246460082,
"site_id": "MLA",
"status": "active",
"title": "Item de Teste",
"price": 200,
"currency_id": "ARS",
"permalink": "http://articulo.mercadolibre.com.ar/MLA-657316800-item-de-testeo_JM"
"thumbnail": "http://mla-s2-p.mlstatic.com/471325-MLA25424154856_032017-I.jpg",
"picture_id": "471325-MLA25424154856_032017",
"date_created": "2017-03-10T02:27:32.325+0000",
"last_updated": "2017-03-10T02:27:32.325+0000"
}Edit ad status
Request:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads/ads/$ITEM_ID
{
"status": "paused" | "active"
}Buscar anúncios por usuários
Parameters
- user_id: required.
- status: optional, Product Ads status.
- title: optional, these are words included in the Product Ad title.
- campaigns: optional, receives a campaign id.
- offset y limit: optional. The limit cannot be greater than 100.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLESearch +10,000 ads per user
For those users with searches of more than 10,000 ads, they will have a new way to query.
1. Perform the first search as usual:
Required parameters
- user_id: iuser id, type long.
- site_id: user's country site, type string.
- limit: limit of results per search, type integer.
Optional parameter
channel: channel of the item (marketplace/mshops) - default is marketplace, type string.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLEResponse:
{
"results": [
{
"id": "MLA000000000",
"campaign_id": 10000000,
"user_id": 10000000,
"site_id": "MLA",
"cpc": 0.01,
"status": "active",
"title": "Description",
"price": 100.45,
"currency_id": "USD",
"permalink": "https://articulo.mercadolibre.com.ar/test.jpg",
"thumbnail": "http://mla-s2-p.mlstatic.com/test.jpg",
"picture_id": "ABCD_12345_ZYX",
"channel": "marketplace",
"date_created": "2022-05-07T21:11:05.000-04:00",
"last_updated": "2022-11-22T11:22:20.000-04:00"
}
],
"paging": {
"offset": 0,
"last_item_id": "MLA000000001",
"total": 12,
"limit": 1
}
}
Response fields
Contains the number of items defined by limit.
- total: total number of elements owned by the user.
- limit: number of items per search page.
- last_item_id: last item_id of the list that will serve for the next request and start displaying the next items depending on the specified limit.
2. Identify the last_item_id (last item_id in the list) that will serve for the next petition.
3. Perform the second search with the last item in the list as the pivot element for the following results page. For this search you should not send the offset parameter, since sending it next to the last_item_id will produce an error.
Required parameters
- user_id: user id, type long.
- site_id: user's country site, type string.
- limit: limit of results per search, type integer.
- last_item_id: last item in the list that will serve as a pivot element for the next page of results. If not set, it will return to the beginning of the whole list. Type string.
Optional parameters
channel: item channel (marketplace/stores) - Default is marketplace, type string.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$USER_ID&status=$STATUS&offset=$OFFSET&limit=$LIMIT&campaigns=$CAMPAIGN_ID&title=$TITLE&last_item_id=$LAST_ITEM_ID