Product Ads – Mercado Libre Advertising

This tool enables you to create advertising campaigns to help you promote your listings in Mercado Libre and get more visits and sales. If you are a new seller or if you are launching a new product, you will be able to make your first sales faster. If you are an experienced seller, you will be able to boost your listings’ performance and increase your sales.

Learn more in https://publicidad.mercadolibre.com.ar/productAds

Contents

Plans

If you wish to start working with Product Ads in Mercado Libre, the first thing you need to know, before designing your own campaigns, is the plans available in your country. Each plan will determine your maximum investment in advertising. The highest the plan, the more visits you will have, but you will pay a lower cost per click (CPC), and reach out more buyers.
To know which plans are available in your site:

curl -X GET https://api.mercadolibre.com/advertising/product_ads/plans?site_id=$site_id

Example:

curl -X GET https://api.mercadolibre.com/advertising/product_ads/plans?site_id=MLA
 
[
 {
   "id": 108,
   "site_id": "MLA",
   "name": "Avanzado",
   "daily_budget": 340
 }
]

The daily_budget field defines the maximum fixed budget a seller will pay per day. This amount varies by plan. It is expressed in each site’s local currency.

If necessary, you can also query the plan by its relevant ID.

curl -X GET https://api.mercadolibre.com/advertising/product_ads/plans/$plan_id

Example:

curl -X GET https://api.mercadolibre.com/advertising/product_ads/plans/108


{
   "id": 108,
   "site_id": "MLA",
   "name": "Avanzado",
   "daily_budget": 340
 }

Campaigns

All your ads will be grouped into campaigns. Each campaign will have an associated plan, and its budget will be shared by every ad within the campaign.
You can create as many campaigns as desired.

Create a campaign

The first thing you need to do is to add a campaign for a user. You can create two types of campaigns:



DEFAULT: It will always be the first campaign you have created. You cannot assign it a name nor create more than one campaign of this type. For Spanish-speaking sites, the name will be “Campaña General” [General Campaign]. In MLB it changes to “Campanha Geral”.

curl -X POST https://api.mercadolibre.com/advertising/product_ads/campaigns?access_token=$access_token
 
{
   "plan_id": 109,
   "sync_new_listings": "enabled|disabled", 
   "group_id": "ML|MS|OS_1234,
   "status": "active|paused"
}

Parameters

  • plan_id: it is the only mandatory field for a successful POST.
  • sync_new_listings: the default value is “enabled”. So, every time the user makes a post, the listing will automatically turn into an Ad Product. If the value is set to disabled, every item will have to be manually added.
  • group_id: this field defines the inventory considered to know which user’s listings should be taken into account for advertising purposes. The values represent Mercado Libre, Mercado Shops and the Official Store with their relevant ID.
  • status: by default a campaign is created as active.

When the campaign has no active listings, the status will automatically change to “hold”. No budget is consumed in this status. The special feature is that a user cannot change the status. The system will automatically set this status when every listing within the campaign is closed. Is this status final? No. When you add a new listing, the status will change to paused. To activate the listing, a PUT with active status should be manually called.


CUSTOM: This refers to campaigns specifically focused on certain products, specially when a seller has a broad catalog to leverage his/her investment. The creation of several custom campaigns enables to increase the daily budget.
Custom campaigns have their own name to identify them. Sync is disabled since it will be necessary to indicate which ads are part of this type of campaigns.

 curl -X POST https://api.mercadolibre.com/advertising/product_ads/campaigns?access_token=token
 
{
"plan_id": 109,
“name”: “example_campaign”,   
"group_id": "ML|MS|OS_1234, 
"status": "active|paused"
}

Response

{
       "id": 29412881,
       "name": "aName",
       "user_id": 38957177,
       "plan_id": 109,
       "type": "default|custom",
       "sync_new_listings": "enabled|disabled",
       "group_id": "ML|MS|OS_1234,
       "status": "active|paused",
       "date_created": "2017-01-10T18:23:55-04:00",
       "last_updated": "2017-01-10T18:23:55-04:00"
   }

Restrictions for a user to create campaigns

  • If the user has no items listed, he/she cannot create campaigns.
  • If the user’s reputation in the site is red or orange. This situation cannot be reserved unless the user’s lights change.
  • New user without experience in the site. In the sites where Mercado Pago is active, the user will be requested to make a one-time minimum charge. This charge will be reimbursed with the invoice.
  • Pending documentation. A link will pop up for the user to complete the documentation. It applies to MLB, MLV and MCO.

Change a campaign

In case of a default campaign, the following fields can be changed:

  • plan_id
  • status
  • sync_new_listings

In case of a custom campaign, the following fields can be changed:

  • plan_id
  • status
  • name

Example:

curl -X PUT https://api.mercadolibre.com/advertising/product_ads/campaigns/$camp_id?access_token=token
 
{
   “plan_id”: 108,
  "status": "active|paused",
}

Query a campaignr

curl -X GET https://api.mercadolibre.com/advertising/product_ads/campaigns/camp_id?access_token=token
 
{
       "id": 29412881,
       "name": "aName",
       "user_id": 38957177,
       "plan_id": 109,
       "type": "default|custom",
       "sync_new_listings": "enabled|disabled",
       "group_id": "ML|MS|OS_1234,
       "status": "active|paused|hold",
       "date_created": "2017-01-10T18:23:55-04:00",
       "last_updated": "2017-01-10T18:23:55-04:00"
   }

Search campaigns by user

curl -X GET https://api.mercadolibre.com/advertising/product_ads/campaigns/search?user_id=1&offset=0&limit=10&access_token=token
 
{
 
   "paging": {
       "total":1,
       "offset":1,
       "limit":10
   }

   "results": [
       {
           "id": 29412881,
           "name": "aName",
           "user_id": 38957177,
           "plan_id": 109,
           "sync_new_listings": "enabled|disabled",
           "group_id": "ML|MS|OS_1234,
           "status": "active|paused",
           "type": "custom",
           "date_created": "2017-01-10T18:23:55-04:00",
           "last_updated": "2017-01-10T18:23:55-04:00"
       }
   ],

}

Campaign metrics

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

Example:

curl -X GET https://api.mercadolibre.com/advertising/product_ads/campaigns/id_campaign/metrics?date_from=2017-01-01&date_to=2017-02-01&access_token=$token

date_from and date_to parameters are mandatory.

Response:

{
 "impressions": 3,
 "clicks": 2,
 "ctr": 0.66, //ratio is a percentage between impressions and clicks.
 "cost": 3 //click total cost within the period in local currency. 
}

Parameters

  • impressions: number of of the Product Ad impressions in the site.
  • clicks: number of clicks the Product Ad had.
  • ctr: percentage between impressions and clicks.
  • cost: click total cost within the period in local currency.

Product Ads

Query a Product Ad associated to a user’s item

curl -X GET https://api.mercadolibre.com/advertising/product_ads/ads/item_id?access_token=$access_token
 
{
   "id": "MLA657316800",
   "campaign_id": 141072850,
   "user_id": 246460082,
   "site_id": "MLA",
   "cpc": 1.73,
   "status": "active",
   "title": "Item de Testeo",
   "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 the campaign Product Ad

A Product Ad cannot be the same in two campaigns at the same time. In other words, if a user has a default and a custom campaign, the item should be removed from the former in order to be part of the latter. It may also happen that once in the custom campaign the item is forwarded to the default campaign, and so it returns to its place of origin.

The item always belongs to the default campaign at first. When it is sent to a custom campaign, the status will always be active, and it can then be turned to paused.

When a Product Ad is moved from one campaign to another, the relevant metrics will be associated to the new campaign. For example, if a Product Ad had 10 visits in the default campaign and it is moved to a custom campaign, counts will be reset. However, these metrics are saved. If a Product Ad returns to its original campaign, it will continue having the same metrics it had before being moved.

Assign a Product Ad to a campaign

curl -X PUT https://api.mercadolibre.com/advertising/product_ads/ads/$item_id
 
{
 "campaign_id": 22222222
}

Change a Product Ad status in a campaign

curl -X PUT https://api.mercadolibre.com/advertising/product_ads/ads/$item_id?access_token=token
 
{
 "status": "paused" | “active” 
}

Search Product Ad by user

curl -X GET https://api.mercadolibre.com/advertising/product_ads/ads/search?user_id=$user_id&status=$status&offset=$offset&limit=$limit&campaigns=$campaign_id,$campaign_id&title=$title&access_token=$access_token

Parameters

  • user_id: required.
  • status: optional, it is the Product Ad status.
  • title: optional, it refers to the words included in the Product Ad title.
  • campaigns: optional, it works as a multiget that receives several IDs, separated by coma.
  • offset y limit: optional. The limit cannot exceed 100.

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.

Example:

curl -X GET https://api.mercadolibre.com/advertising/product_ads/campaigns/$campaign_id/ads/metrics?ids=MLA12345678,MLA12344321,MLA87654321&date_from=2017-01-01&date_to=2017-02-01&access_token=$access_token
 
[
   {
       "item_id":MLA12345678,
       "clicks": 2,
       "impressions": 3,
       "ctr": 0.6666,
       "cost": 3.0
   }
  {
       "item_id":MLA12344321,
       "clicks": 2,
       "impressions": 3,
       "ctr": 0.6666,
       "cost": 3.0
   }

]

Groups

All campaigns are associated to a group. This grouping enables you to understand if the campaign consists of items from Mercado Libre, Mercado Shops or Official Stores.

These are the conventions used to define the groups:

  • ML: Mercado Libre
  • MS: Mercado Shops
  • OS_: Official Store

Get a particular Group from a user

curl -X GET https://api.mercadolibre.com/advertising/product_ads/groups/$group_id?access_token=$access_token
 
{
  "id": "ML",
  "name": "Mercado Libre",
  "campaigns": {
    "active": 4,
    "paused": 3,
    "hold": 3
  }
}

Parameters

  • id: it identifies the group.
  • name: it represents the group name.
  • campaigns: it includes the number of campaigns in their different statuses; namely, active, paused and hold.

Get all the Groups from a user

curl -X GET https://api.mercadolibre.com/advertising/product_ads/groups?access_token=$access_token
  
[
  {
    "id": "ML",
    "name": "Mercado Libre",
    "campaigns": {
      "active": 1,
      "paused": 2,
      "hold": 3
    }
  },
  {
    
    "id": "OS_456",
    "name": "Official Store",
    "campaigns": {
      "active": 1,
      "paused": 0,
      "hold": 3
    }
  },
  {
    
    "id": "MS",
    "name": "Mercado Shops",
    "campaigns": {
      "active": 3,
      "paused": 0,
      "hold": 4
    }
  }
]

Please rate this