Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 30/08/2024

Brand Ads

Importante:
Brand Ads is an exclusive advertising solution for brands that have an Official Store in Mercado Libre. It is enabled for Mercado Libre products and MLA Vehicles (Argentina). Coming soon:
- MLB (Brazil), MLM (Mexico) and MCO (Colombia) vehicles and
- Properties from MLA (Argentina) and MLC (Chile)

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: PADS (Product Ads), 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": 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 nomenclature of Mercado Libre sites and their respective currencies.
advertiser_name: advertiser name.
account_name: account name.

Note:
In case you receive error 404 - No permissions found for user_id means that the user does not have the Product enabled. The user must access Mercado Libre > Mi perfil > Publicidad.

Types of campaigns

Before consulting campaigns, we recommend that you know the types of campaigns. In addition, you can access campaign metrics from 2023-02-09.

  • Automatic: automatic campaigns are managed by Mercado Ads. The campaign will be automatically executed for all items associated with the official_store_id of the destination_id sent and will create keywords, which cannot be edited or deleted, that is, Mercado Ads will manage the advertiser's inventory and assign the best keywords for their ads.
  • Custom: Personalized campaigns are created and managed by the user, where the advertiser must provide a list of items (minimum 3, maximum 10) with which to configure their ad and the keywords (minimum 1, maximum 200) that are keywords. for searches in which you want to be printed. You can then edit and delete these keywords.
Note:
To consult the items and keywords of an automatic campaign you must use the metrics endpoints. Otherwise you will receive an empty http 200.

Search campaigns

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
        }
      ]
    }
  ]
}

Campaign detail

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 campaign ads

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

Consult 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.


Available filters

status: campaign status. Values: active, paused.
destination_id: destination id of the campaign.


Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/$ADVERTISER_ID/brand_ads/campaigns/metrics?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD&aggregation_type=daily

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/10101010/brand_ads/campaigns/metrics?date_from=2024-07-01&date_to=2024-07-10&aggregation_type=daily

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

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/10100101/brand_ads/campaigns/123456/metrics?date_from=2024-07-01&date_to=2024-07-10

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/advertising/advertisers/101010/brand_ads/campaigns/123456/keywords/metrics?date_from=2024-07-01&date_to=2024-07-10

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
            }
        }
    ]
}

Glossary

prints (impressions): the number of times your ads were displayed.
clicks: the number of times users clicked on your ads.
ctr (click-through rate): the rate of clicks obtained over the total impressions.
cvr (conversion rate): the conversion rate with respect to clicks.
consumed_budget (investment): the amount of money actually spent to display your ads.
cpc (cost per click): the average cost paid for each click your ads received.
acos (advertising cost of sales): investment income/expense, advertising sales cost.


Metrics can be attributed:
event_time: metrics attributed by action date, shown associated with the exact date the action was taken (e.g., sales).
touch_point: metrics attributed by viewing 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 number 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 (bookmark): the number of attributable items marked as favorites after viewing or clicking on your ads.
  • cart_conversions (cart): the number of attributable items added to the shopping cart after viewing or clicking on your ads.
  • checkout_conversions (checkout): 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.

competitive: array with competitiveness metrics. They are shown only at the campaign level and reflect their impression distribution, i.e., they are percentages of times your ads were displayed or not in relation to 100% of times they could have been. They are calculated with data from the last 7 days. The period will be selectable soon. Metrics can be:

  • lost_impression_share_by_budget (Losses due to budget): loss percentage, meaning potential impressions that were not capitalized due to low budget. For example: if it is 10, it means that the campaign lost impressions 10% of the times it could have had them due to insufficient budget. In these cases, we recommend increasing the budget.
  • lost_impression_share_by_ad_rank (Losses due to ranking): loss percentage, meaning potential impressions that were not capitalized due to low ranking. For example, if the result is 30, the campaign lost impressions 30% of the times it could have had them due to insufficient ad-rank.

The ad rank consists of the Acos Target and the Quality Score (internal metric, not directly manageable). To improve impressions won by ranking, we suggest focusing on the following points:

  • Review the maximum CPC: it is recommended to be within the average of your competition for better results.

  • Verify that the campaign is targeted to the correct keywords: we recommend having different campaigns, so you can target specific keywords in each one.

  • Improve the quality of your listing: the quality of photos, product descriptions, and even shipping conditions can play an important role in your ranking.

  • Maintain your reputation: post-sales service and product ratings can differentiate you when competing. Learn more about the Publication Quality API.

  • impression_share (Impressions won): success percentage, meaning effective impressions, i.e., the percentage of times the campaign won the auctions in which it participated with that keyword. It is the number of impressions obtained divided by the estimated/potential impressions it could have had. For example: if it is 60%, it means that the campaign won and was displayed 60% of the times it could have.
  • competitive_cpc: the CPC of the competition.

Next: Display Ads.