Display Ads

Recommended Technical Flow

1. Advertisers (advertiser id) for display
2. Advertisers' campaigns
3. Campaign metrics



Campaign Panel on Mercado Ads

Consult advertiser

Advertisers (advertiser_id) are those who invest a budget for the creation and distribution of advertising, with the aim of promoting their products or services. Check the list of advertisers that a user has access to, according to the type of product required.

Mandatory parameters

product_id: product type. Available values: DISPLAY, BADS (Brand Ads)

Optional parameters

sort_by: sorts by attribute (advertiser_id, site_id). Default advertiser_id.

sort_order: order (asc, desc). Default is desc.

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=DISPLAY

Response:

{
  "advertisers": [
    {
      "advertiser_id": 36,
      "site_id": "MLM"
    }
  ]
}

Response fields

Advertiser_id: advertiser identifier. You will use it for the rest of the requests.
Site_id: country identifier. Consult the sites of the Mercado Libre sites and their respective currencies.

Consult advertiser campaigns

Optional parameters

sort_by: sorts by attribute (id, name, start_date, end_date). Default is id.
sort_order: order (asc, desc). Default is desc.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/61/display/campaigns?sort_by=start_date&sort_order=desc

Response:

{
 "results": [
    {
      "id": 80,
      "name": "CONVERSION_ENERO2022_MLA",
      "start_date": "2022-01-12T17:00:00",
      "end_date": "2022-01-31T23:59:00",
      "advertiser_id": 61,
      "type": "GUARANTEED",
      "status": "paused",
      "site_id": "MLA"
    }
  ]
}

Response fields

id: campaign id. Use the id to consult campaign metrics.
name: campaign name.
start_date: campaign start date.
end_date: campaign end date.
advertiser_id: advertiser id
type: campaign type.
status: campaign status.
site_id: country.

Campaign metrics query

The results of this endpoint will be the metrics per day and a summary for the campaign date range.

Optional parameters

sort_by: order by attribute: id, name, start_date, end_date. Default is id.
sort_order: order ascending (asc) and descending (desc). Default is desc.
fields: daily, summary. Default is summary.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/display/campaigns/$CAMPAIGN_ID/metrics

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Api-Version: 1"
https://api.mercadolibre.com/advertising/advertisers/61/display/campaigns/80/metrics

Response:

{
  "metrics":[
    {
      "date":"2024-02-01",
      "prints":17961,
      "clicks":186,
      "reach":10079,
      "ctr":0.01,
      "consumed_budget":57449.13,
      "cpm":3198.55,
      "cpc":308.87,
      "cpa":1148.98,
      "roas":12.36,
      "average_frequency":1.78,
      "event_time":{
        "cpa_order":1083.95,
        "cpa_ppv":135.81,
        "roas":10.03,
        "units_quantity":53.0,
        "direct_amount":576150.0,
        "direct_item_quantity":75.0,
        "attribution_ppv":423.0,
        "attribution_add_to_cart":26.0,
        "attribution_bookmark":33.0,
        "attribution_checkout":24.0
      },
      "touch_point":{
        "cpa_order":1148.98,
        "cpa_ppv":125.16,
        "roas":12.36,
        "units_quantity":50.0,
        "direct_amount":710324.0,
        "direct_item_quantity":70.0,
        "attribution_ppv":459.0,
        "attribution_add_to_cart":26.0,
        "attribution_bookmark":35.0,
        "attribution_checkout":28.0
      }
    }
  ],
  "summary":{
    "prints":170462,
    "clicks":2033,
    "reach":48957,
    "ctr":0.01,
    "cpm":3551.57,
    "cpc":297.79,
    "cpa":1509.74,
    "roas":9.49,
    "average_frequency":3.48,
    "event_time":{
      "cpa_order":1513.52,
      "cpa_ppv":128.59,
      "roas":9.48,
      "attribution_order":400.0,
      "direct_amount":5741691.0,
      "direct_item_quantity":586.0,
      "attribution_ppv":4708.0,
      "attribution_add_to_cart":263.0,
      "attribution_bookmark":375.0,
      "attribution_checkout":219.0
    },
    "touch_point":{
      "cpa_order":1509.74,
      "cpa_ppv":125.66,
      "roas":9.49,
      "attribution_order":401.0,
      "direct_amount":5746421.0,
      "direct_item_quantity":586.0,
      "attribution_ppv":4818.0,
      "attribution_add_to_cart":270.0,
      "attribution_bookmark":352.0,
      "attribution_checkout":225.0
    }
  }
}

Response fields

date: campaign date.
site: campaign country. Consult the sites of the Mercado Libre sites and their respective currencies.
currency: local currency.
prints: impressions. It's the number of times your ads were shown.
clicks: number of times users clicked on your ads.
reach: Reach. It's the number of unique users who saw your ads.
ctr: Click-Through Rate. Clicks received as a percentage of total impressions.
consumed_budget: Investment: It's the amount of money actually spent to show your ads.
cpm: average cost paid for each thousand impressions of the ads.
cpc: Cost per Click. It's the average cost paid for each click received on the ads.
roas: Return on Advertising Spend.
average_frequency: Average frequency. Average number of times your ads were shown to the same user.

Attribution metrics have two ways of being presented:

Event Time Attribution Metrics (event_time): metrics will be shown associated with the exact date the action was taken (e.g., Sales).
Touchpoint Attribution Metrics (touch_point): metrics will be shown associated with the date of the click or visible impression to which they were attributed.

• cpa_order: average cost of each sale based on investment.
• cpa_ppv: average cost of each product page view based on investment.
• roas: return on advertising spend.
• units_quantity: quantity of units of your products sold across all purchases attributed to your ads.
• direct_amount (revenue): total value of sales attributed to your ads.
• direct_item_quantity: number of times users made a purchase after viewing or clicking on your ads.
• attribution_ppv (product page views): number of times users visited your product page after viewing or clicking on your ads.
• attribution_add_to_cart: number of times users added your promoted products to the shopping cart after viewing or clicking on your ads.
• attribution_bookmark: number of times users bookmarked your promoted products after viewing or clicking on your ads.
• attribution_checkout: number of times users initiated a purchase process of your promoted products after viewing or clicking on your ads.

Errors

Error	Status	Message
bad_request	400	The parameter {paramKey} is required.
not_found	404	No campaigns found for advertiser id {advertiser_id} Campaign not found for sent campaign_id.