Mercado 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=default

Response:

{
       "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_ID

Example:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/223493019

Response:

{
    "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_ID

Example:

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/search?user_id=123456

Response:

{  
   "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-DD

Response:

{
  "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_2

Response:

[{
	"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=$TITLE

Search +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=$TITLE

Response:

{
   "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