Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 03/05/2024

Brand Ads

This functionality aims to enhance advertisers' ability to understand and optimize the performance of their advertising campaigns. It provides relevant and updated information in an automated manner, enabling advertisers to efficiently integrate data for analysis and comparison.

Positioning
For a Brand Ads ad to appear in position 0 of search results, the configured keywords must match a user's search. To determine which ad is shown, Brand Ads uses a bidding system where each advertiser sets:

  • the keyword they want to link with their ad
  • the maximum CPC they are willing to pay

The Brand Ads algorithm evaluates ads competing for the same space (i.e., sharing keywords) based on a series of criteria and assigns them a score, called Ad-Score, measuring the ad's conversion probability. This score is then taken into account along with the maximum CPC to create a ranking (Ad Rank) that determines the auction winner.

Recommended Technical Flow

  1. Consult advertiser (advertiser id)
  2. Consult campaign, items campaings and keywords
  3. Consult metrics of advertiser, campaigns and keyword

Consult Advertiser

Advertisers (advertiser_id) are those who invest a budget in creating and distributing advertising, with the aim of promoting their products or services. Consult the list of advertisers that a user has access to, based on the required product type.


Mandatory parameters

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

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

Response:

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

Search campaigns by advertiser

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns

Response:

{
  "paging": {
    "total": 50,
    "offset": 0,
    "limit": 2
  },
  "campaigns": [
    {
      "campaign_id": 1,
      "name": "campaign meli 1",
      "start_date": "2024-01-01T00:06:22.000Z",
      "end_date": "2024-01-01T00:06:22.000Z",
      "advertiser_id": 1234,
      "campaign_type": "custom",
      "status": "active",
      "site_id": "MLA",
      "official_store_id": 12345,
      "destination_id": 12345,
      "headline": "this is a headline",
      "budget": {
        "amount": 1111111.32,
        "currency": "ARS"
      },
      "cpc": 100.5,
      "items": [
        {
          "campaign_id": 1,
          "status": "active",
          "item_id": "MLA1178375484"
        }
      ],
      "keywords": [
        {
          "campaign_id": 1,
          "type": "custom",
          "term": "car",
          "match_type": "phrase",
          "is_negative": false,
          "cpc": 50.5
        }
      ]
    }
  ]
}

Consult campaign by advertiser

Request:

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

Response:

{
      "campaign_id": 1,
      "name": "campaign meli 1",
      "start_date": "2024-01-01T00:06:22.000Z",
      "end_date": "2024-01-01T00:06:22.000Z",
      "advertiser_id": 1234,
      "campaign_type": "custom",
      "status": "active",
      "site_id": "MLA",
      "official_store_id": 12345,
      "destination_id": 12345,
      "headline": "this is a headline",
      "budget": {
        "amount": 1111111.32,
        "currency": "ARS"
      },
      "cpc": 100.5,
      "items": [
        {
          "campaign_id": 1,
          "status": "active",
          "item_id": "MLA1178375484"
        }
      ],
      "keywords": [
        {
          "campaign_id": 1,
          "keyword_id": 1,
          "type": "custom",
          "term": "car",
          "match_type": "phrase",
          "is_negative": false,
          "cpc": 50.5
        }
      ]
    }

Consult items of a campaign

Request:

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

Response:

[
  {
    "campaign_id": 1,
    "status": "active",
    "item_id": "MLA1178375484"
  }
]

Query campaign items

Request:

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

Response:

[
  {
    "campaign_id": 1,
    "status": "active",
    "item_id": "MLA1178375484"
  }
]

Query campaign keywords

Request:

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

Response:

[
  {
    "campaign_id": 1,
    "type": "custom",
    "term": "auto",
    "match_type": "phrase",
    "is_negative": false,
    "cpc": 50.5
  }
]

Advertiser campaigns metrics

Mandatory parameters

date_from: start date of the query in YYYY-MM-DD format.
date_to: end date of the query in YYYY-MM-DD format.


Optional parameters

limit: default is 50.
offset: default is 0.
aggregation_type: type of data aggregation to display. Possible values: daily, total. By default, it returns both.
fields: specific metrics fields to query.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/metrics

Response:

{
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 90
    },
    "metrics": [
        {
            "date": "2024-01-08",
            "site_id": "MLA",
            "currency": "ARS",
            "prints": 0,
            "clicks": 0,
            "ctr": 0.00,
            "cvr": 0.00,
            "consumed_budget": 0.00,
            "cpc": 0.00,
            "acos": 0,
            "event_time": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            },
            "touch_point": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            }
        }
    ],
    "summary": {
        "site_id": "MLA",
        "currency": "ARS",
        "prints": 0,
        "clicks": 0,
        "ctr": 0.00,
        "cvr": 0.00,
        "consumed_budget": 0.00,
        "cpc": 0.00,
        "acos": 0,
        "event_time": {
            "units_quantity": 0,
            "units_amount": 0.00,
            "items_quantity": 0,
            "ppv_conversions": 0,
            "bookmark_conversions": 0,
            "cart_conversions": 0,
            "checkout_conversions": 0,
            "leads_question_conversions": 0,
            "leads_im_conversions": 0,
            "eshop_conversions": 0
        },
        "touch_point": {
            "units_quantity": 0,
            "units_amount": 0.00,
            "items_quantity": 0,
            "ppv_conversions": 0,
            "bookmark_conversions": 0,
            "cart_conversions": 0,
            "checkout_conversions": 0,
            "leads_question_conversions": 0,
            "leads_im_conversions": 0,
            "eshop_conversions": 0
        }
    }
}

Response fields

prints (impressions): the number of times your ads were displayed.
clicks: number of times users clicked on your ads.
ctr (click-through rate): the ratio of clicks to impressions.
cvr (conversion rate): the ratio of conversions to clicks.
consumed_budget (investment): the amount of money spent to display your ads.
cpc (cost per click): the average cost paid for each click received on the ads.
acos (advertising cost of sales): the ratio of advertising spend to attributed sales.
event_time: metrics attributed by action date, shown associated with the exact date the action was taken (e.g., sales).
units_quantity (sales): the number of times users made a purchase after viewing or clicking on your ads.
units_amount (revenue): the total value generated by sales attributed to your ads.
items_quantity: the quantity of items sold by attributions.
ppv_conversions (product page views): the number of views to product pages after viewing or clicking on your ads.
bookmark_conversions: the number of attributable items marked as favorites after viewing or clicking on your ads.
cart_conversions: the number of attributable items added to the shopping cart after viewing or clicking on your ads.
checkout_conversions: the number of attributable items for which the purchase process was initiated after viewing or clicking on your ads.
leads_question_conversions: the number of potential customers interested in purchasing your product who asked questions in your listing after clicking on your ads.
leads_im_conversions: the number of potential customers interested in purchasing your product who contacted you via WhatsApp from your listing after clicking on your ads.
eshop_conversions: the number of attributed sales.
touch_point: metrics attributed by view date, shown associated with the date of click or visible impression that generated them.

  • units_quantity: (sales) the number of times users made a purchase after viewing or clicking on the ads.
  • units_amount: (revenue) the total value generated by sales attributed to your ads.
  • items_quantity: the quantity of items sold by attributions.
  • ppv_conversions: (product page views) the number of views to product pages after viewing or clicking on your ads.
  • bookmark_conversions: the number of attributable items marked as favorites after viewing or clicking on your ads.
  • cart_conversions: the number of attributable items added to the shopping cart after viewing or clicking on your ads.
  • checkout_conversions: the number of attributable items for which the purchase process was initiated after viewing or clicking on your ads.
  • leads_question_conversions: the number of potential customers interested in purchasing your product who asked questions in your listing after clicking on your ads.
  • leads_im_conversions: the number of potential customers interested in purchasing your product who contacted you via WhatsApp from your listing after clicking on your ads.
  • eshop_conversions: the number of attributed sales.

Campaign Daily Metrics

Mandatory parameters

date_from: start date of the query in YYYY-MM-DD format.
date_to: end date of the query in YYYY-MM-DD format.


Optional parameters

limit: default is 50.
offset: default is 0.
aggregation_type: type of data aggregation to show. Possible values: daily, total. By default, both are returned.
fields: specific metric fields to query.


Request:

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

Example:

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

Response:

{
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 90
    },
    "metrics": [
        {
            "date": "2024-01-02",
            "prints": 2026,
            "site_id": "MLA",
            "currency": "ARS",
            "clicks": 20,
            "ctr": 0.00,
            "cvr": 0.00,
            "consumed_budget": 3000.00,
            "cpc": 150.00,
            "acos": 0,
            "event_time": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            },
            "touch_point": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            }
        }
    ],
    "summary": {
        "prints": 2026,
        "clicks": 20,
        "site_id": "MLA",
        "currency": "ARS",
        "ctr": 0.00,
        "cvr": 0.00,
        "consumed_budget": 3000.00,
        "cpc": 150.00,
        "acos": 0,
        "event_time": {
            "units_quantity": 0,
            "units_amount": 0.00,
            "items_quantity": 0,
            "ppv_conversions": 0,
            "bookmark_conversions": 0,
            "cart_conversions": 0,
            "checkout_conversions": 0,
            "leads_question_conversions": 0,
            "leads_im_conversions": 0,
            "eshop_conversions": 0
        },
        "touch_point": {
            "units_quantity": 0,
            "units_amount": 0.00,
            "items_quantity": 0,
            "ppv_conversions": 0,
            "bookmark_conversions": 0,
            "cart_conversions": 0,
            "checkout_conversions": 0,
            "leads_question_conversions": 0,
            "leads_im_conversions": 0,
            "eshop_conversions": 0
        },
        "competitive": {
            "lost_impression_share_by_budget": 0.7,
            "lost_impression_share_by_ad_rank": 0.04,
            "impression_share": 0.26,
            "competitive_cpc": 175.0
        }
    }
}

Campaign Keyword Daily Metrics

Get keyword metrics for each day for a specific campaign.


Mandatory parameters

date_from: start date of the query in YYYY-MM-DD format.
date_to: end date of the query in YYYY-MM-DD format.


Optional parameters

limit: default is 50.
offset: default is 0.
aggregation_type: type of data aggregation to show. Possible values: daily, total. By default, both are returned.
fields: specific metric fields to query.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/$CAMPAIGN_ID/keywords/metrics

Response:

{
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 90
    },
    "metrics": [
        {
            "date": "2024-01-08",
            "keywords": [
                {
                    "keyword": "cloruro magnesio",
                    "site_id": "MLA",
                     "currency": "ARS",
                    "prints": 2,
                    "clicks": 0,
                    "ctr": 0.00,
                    "cvr": 0.00,
                    "consumed_budget": 0.00,
                    "cpc": 0.00,
                    "acos": 0,
                    "event_time": {
                        "units_quantity": 0,
                        "units_amount": 0.00,
                        "items_quantity": 0,
                        "ppv_conversions": 0,
                        "bookmark_conversions": 0,
                        "cart_conversions": 0,
                        "checkout_conversions": 0,
                        "leads_question_conversions": 0,
                        "leads_im_conversions": 0,
                        "eshop_conversions": 0
                    },
                    "touch_point": {
                        "units_quantity": 0,
                        "units_amount": 0.00,
                        "items_quantity": 0,
                        "ppv_conversions": 0,
                        "bookmark_conversions": 0,
                        "cart_conversions": 0,
                        "checkout_conversions": 0,
                        "leads_question_conversions": 0,
                        "leads_im_conversions": 0,
                        "eshop_conversions": 0
                    }
                }
            ]
        }
    ],
    "summary": [
        {
            "keyword": "cloruro magnesio",
            "site_id": "MLA",
            "currency": "ARS",
            "prints": 2,
            "clicks": 0,
            "ctr": 0.00,
            "cvr": 0.00,
            "consumed_budget": 0.00,
            "cpc": 0.00,
            "acos": 0,
            "event_time": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            },
            "touch_point": {
                "units_quantity": 0,
                "units_amount": 0.00,
                "items_quantity": 0,
                "ppv_conversions": 0,
                "bookmark_conversions": 0,
                "cart_conversions": 0,
                "checkout_conversions": 0,
                "leads_question_conversions": 0,
                "leads_im_conversions": 0,
                "eshop_conversions": 0
            }
        }
    ]
}

Next: Display Ads.