Mercado Ads

This tool enables you to create advertising campaigns to help you promote your listings in Mercado Libre and get more visits and sales. With advertising, you will be able to boost your listings performance and increase your sales. Learn more in https://publicidad.mercadolibre.com.ar/productAds

Contents

→Budget limits
→Campaigns
→Create a campaign
→Restrictions for a user to create campaigns
→Change a campaign
→Query a campaign
→Search campaigns by user
→Campaign metrics
→Direct sales and indirect sales
→Product Ads
→Query a Product Ad associated to a user's item
→Change a Product Ad status in a campaign
→Search Product Ad by user


Budget limits

If you wish to start working with Product Ads in Mercado Libre, the first thing you need to know, before designing your own campaign, is your user budget limit. Each user has a minimum and maximum advertising investment assigned. You can freely choose your daily investment within this range. Learn about your user budget limits in:

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": 10,
    "maximum": 60
  }
]

It is expressed in each site’s local currency. Your budget should be within that range. Limit values are valid budgets. A user limits can change overtime.


Campaigns

All your ads will be grouped within a campaign, and the budget will be allocated among all those ads in the campaign.

Create a campaign

The first thing you need to do is to add a campaign for a user.

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

BODY

{
  "budget": 20,
  "status": "active"|"paused",
}

Parameters: Budget: field required within your user budget limits.
Status: optional field with a default "active" value

Response:

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

Restrictions for a user to create campaigns

If there is pending documentation. A link will pop up for the user to complete the documentation. It applies to MLB, MLV and MCO.

Change a campaign

You can change these fields: status: budget

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID
BODY 
{
"status": "active"|"paused",
"budget":225
}

Query a campaign

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


{
    "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 campaigns by user

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


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

A campaign metrics within a date range, not exceeding 90 days, can be queried. 

curl -X  GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/metrics?date_from=$DATE_FROM&date_to=$DATE_TO
  • date_from: field required with “yyyy-mm-dd” format, for example 2018-08-01
  • date_to: field required with “yyyy-mm-dd” format, for example 2018-08-10
  • campaign_id: field required, campaign id

Response:

{  
   "clicks":1590,
   "impressions":1929487,
   "ctr":0.08,
   "cost":700.19,
   "cpc":0.44,
   "sold_quantity_direct":38,
   "sold_quantity_indirect":13,
   "sold_quantity_total":51,
   "amount_direct":9775,
   "amount_indirect":6815,
   "amount_total":16590,
   "advertising_fee":4.22
}

Response fields refer to all your campaign metrics:

  • impressions: number of impressions a campaign received in the site.
  • clicks: number of clicks a campaign had.
  • ctr: click through rate, expressed as a percentage, division between clicks and impressions.
  • cost: click total cost within the period in local currency.
  • cpc: each click average cost in local currency.
  • sold_quantity_direct: amount of direct sales.
  • sold_quantity_indirect: amount of indirect sales.
  • sold_quantity_total: total amount of sales.
  • amount_direct: Addition of direct sales from your Product Ads in local currency.
  • amount_indirect: Addition of indirect sales from your Product Ads in local currency.
  • amount_total: Addition of sales from your Product Ads in local currency.
  • advertising_fee: expressed as a percentage, division between advertising investment over income. cost / amount_total. A lower value means better performance.

Direct sales and indirect sales

A direct sales occurs when a user clicks on your Product Ad and buys that product. In contrast, an indirect sales occurs when a user clicks on your Product Ad and buys any other of your products.

Product Ads

Product Ad Metrics Using multiget, up to 50 Product Ads can be queried in the same request. A date range not exceeding 90 days should also be sent.

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads_2/campaigns/$CAMPAIGN_ID/ads/metrics?date_from=$DATE_FROM&date_to=$DATE_TO&ids=$ITEM_ID_1,$ITEM_ID_2
  • date_from: field required with “yyyy-mm-dd” format, for example 2018-08-01
  • date_to: field required with “yyyy-mm-dd” format, for example 2018-08-10
  • campaign_id: field required, campaign id
  • ids: field required, list of up to 50 item ids separated by coma, for example MLA1234, MLA4321

Response:

[  
   {  
      "id":"MLA740084255",
      "clicks":73,
      "impressions":160930,
      "ctr":0.05,
      "cost":32.85,
      "cpc":0.45,
      "sold_quantity_direct":19,
      "sold_quantity_indirect":0,
      "sold_quantity_total":19,
      "amount_direct":3610,
      "amount_indirect":0,
      "amount_total":3610,
      "advertising_fee":0.91
   }
]

Response fields refer to each pad metrics:

  • impressions: number of Product Ad impressions in the site.
  • clicks: number of clicks a Product Ad had.
  • ctr: click through rate, expressed as a percentage, division between clicks and impressions.
  • cost: click total cost within the period in local currency.
  • cpc: each click average cost in local currency.
  • sold_quantity_direct: amount of direct sales a Product Ad had.
  • sold_quantity_indirect: amount of indirect sales a Product Ad had.
  • sold_quantity_total: amount of total sales a Product Ad had.
  • amount_direct: Addition of direct sales from your Product Ads in local currency.
  • amount_indirect: Addition of indirect sales from your Product Ads in local currency.
  • amount_total: Addition of sales from your Product Ads in local currency.
  • advertising_fee: expressed as a percentage, division between advertising investment over income. cost / amount_total. A lower value means better performance.

Query a Product Ad associated to a user's item

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/advertising/product_ads/ads/$ITEM_ID
{
    "id": "MLA657316800",
    "campaign_id": 141072850,
    "user_id": 246460082,
    "site_id": "MLA",
    "cpc": 1.73,
    "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"
}

Change a Product Ad status in a campaign

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/product_ads/ads/$ITEM_ID
{
  "status": "paused" | "active"
}

Search Product Ad by user

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

Parameters:

user_id: required.
status: optional, it is a Product Ad status.
title: optional, it refers to the words included in the Product Ad title.
campaigns: optional, it gets a campaign id.
offset and limit: optional. The limit cannot exceed 100.

or register to recieve the latest news about our API