Display Ads

Campaign types and objectives

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: PADS (Product Ads), 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": 000,
            "site_id": "MLB",
            "advertiser_name": "Advertiser AAA",
            "account_name": "MLB - XZY"
        },
        {
            "advertiser_id": 111,
            "site_id": "MLM",
            "advertiser_name": "Advertiser BBB",
            "account_name": "MLM - XYZ"
        },
        {
            "advertiser_id": 222,
            "site_id": "MLA",
            "advertiser_name": "Advertiser CCC",
            "account_name": "MLA - XYZ"
        },
        {
            "advertiser_id": 333,
            "site_id": "MLC",
            "advertiser_name": "Advertiser DDD",
            "account_name": "MLC - XYZ"
        }
    ]
}

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.
advertiser_name: advertiser name.
account_name: account name.

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. Programmatic or Guaranteed.
status: campaign status.
site_id: country.
strategy: campaign objective. Coming soon.
:

Campaign metrics

The results of this endpoint will be the metrics per day and a summary for the campaign date range. You can consult up to 90 days ago, considering September 1, 2022 as the initial date.

Mandatory parameters

date_from: date since of the query in format YYYY-MM-DD.
date_to: date until query in format YYYY-MM-DD.

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.

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?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD

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?date_from=2024-04-01&date_to=2024-04-15

Response:

{
  "metrics": [
    {
      "date": "2024-02-01",
      "site_id": "MLM",
      "currency": "MXN",
      "prints": 17961,
      "clicks": 186,
      "active_views": 0,
      "completed_views": 0,
      "reach": 10079,
      "ctr": 0.01,
      "consumed_budget": 57449.13,
      "cpm": 3198.55,
      "cpc": 308.87,
      "average_frequency": 1148.98,
      "event_time": {
        "cpa_order": 1083.95,
        "cpa_ppv": 135.81,
        "roas": 10.03,
        "units_quantity": 75,
        "direct_amount": 576150,
        "direct_item_quantity": 53,
        "attribution_ppv": 423,
        "attribution_add_to_cart": 26,
        "attribution_bookmark": 33,
        "attribution_checkout": 24,
        "attribution_leads": 0,
        "cpl": 0.0
      },
      "touch_point": {
        "cpa_order": 1148.98,
        "cpa_ppv": 125.16,
        "roas": 12.36,
        "units_quantity": 70,
        "direct_amount": 710324,
        "direct_item_quantity": 50,
        "attribution_ppv": 459,
        "attribution_add_to_cart": 26,
        "attribution_bookmark": 35,
        "attribution_checkout": 28,
        "attribution_leads": 0,
        "cpl": 0.0
      }
    }
  ],
  "summary": {
    "site_id": "MLM",
    "currency": "MXN",
    "prints": 170462,
    "clicks": 2033,
    "active_views": 0,
    "completed_views": 0,
    "reach": 48957,
    "ctr": 0.01,
    "consumed_budget": 605406.93,
    "cpm": 3551.57,
    "cpc": 297.79,
    "average_frequency": 1509.74,
    "event_time": {
      "cpa_order": 1513.52,
      "cpa_ppv": 128.59,
      "roas": 9.48,
      "units_quantity": 586,
      "direct_amount": 5741691,
      "direct_item_quantity": 400,
      "attribution_ppv": 4708,
      "attribution_add_to_cart": 263,
      "attribution_bookmark": 375,
      "attribution_checkout": 219,
      "attribution_leads": 0,
      "cpl": 0.0
    },
    "touch_point": {
      "cpa_order": 1509.74,
      "cpa_ppv": 125.66,
      "roas": 9.49,
      "units_quantity": 586,
      "direct_amount": 5746421,
      "direct_item_quantity": 401,
      "attribution_ppv": 4818,
      "attribution_add_to_cart": 270,
      "attribution_bookmark": 352,
      "attribution_checkout": 225,
      "attribution_leads": 0,
      "cpl": 0.0
    }
  }
}

Glossary

date: campaign date.
prints: impressions. It's the number of times your ads were shown.
clicks: number of times users clicked on your ads.
active_views: number of times users watched the first 6 seconds of your Social and Video ad.
completed_views: number of times users watched your entire Social and Video ad.
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.
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.
• attribution_leads: contacts generated by potential customers after they viewed or clicked on your ads.
• cpl: average cost of each lead based on investment.
Note:
There are 2 ways for a seller to get contacts:
- Publications of Vehicles, Properties or Services (VIS): by leaving a question, call or WhatsApp, the lead reaches the seller. Learn more about our Vehicles, Properties and Services APIs.
- 2. Landings with forms: completing the contact form that reaches the client's CRM. For example: launch form.

Campaing Line items

The line item defines the purchase parameters of the ad: the user profile you want to reach, their geographic location, the device they are browsing from, among others. Each line item is associated with a single campaign and consumes its budget.

Optional parameter

sort_by: possible values: id, name, start_date, end_date.
sort_order: possible values: asc, 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/$CAMPAIGN_ID/line_items?sort_by=start_date&sort_order=asc

Example:

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

Response:

{
 "results": [
    {
      "line_item_id": 1,
      "name": "Name_Line_Item_Test",
      "start_date": "2022-01-12T17:00:00",
      "end_date": "2022-01-31T23:59:00",
      "campaing_id": 987654,
      "type": "Social",
      "status": "paused"
    }
  ]
}

Response field

line_item_id: line item id.
name: line item name.
start_date: start date of the item line.
end_date: end of line item date.
type: line item type. Assigned creative agreement variable.

• Display: native image and text banner. Suitable for different Mercado Libre and Mercado Pago advertising spaces.
• Social: video in vertical format with lower banner. Available for Mercado Libre Clips spaces.
• Video: video in horizontal format. Available for streaming platforms integrated with Mercado Ads. This type of solo line item is enabled for campaigns with the objective Awareness.

status: line item status.

Line item creatives

Optional parameters

sort_by: possible values: id, name.
sort_order: possible values: asc, 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/$CAMPAIGN_ID/line_items/$LINE_ITEM_ID/creatives?sort_by=start_date&sort_order=asc

Example:

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/999999/line_items/0000001/creatives?sort_by=start_date&sort_order=asc

Response:

{
    "results": [
        {
            "creative_id": 123456,
            "name": "Name_Creative_Test",
            "status": "active",
            "line_item_id": 0000001,
            "campaign_id": 999999
        }
    ]
}

Response fields

creative_id: id del creativo.
name: nombre del creativo.
status: estado del creativo. Puede ser: active.

line_item_id: line item id.
campaign_id: campaign id.

Errors