Developers

Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.

Last update 11/12/2023

Campaigns, Ads and Metrics

The following APIs allow you to get information about campaigns, users, update advertising and get a lot of types of metrics to integrate the Mercado Ads solution.

Get seller’s reputation

Mercado Ads is available only for sellers with yellow or green reputation. So, you can check the seller reputation with the /users API. See more How does Reputation work.

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/global/users/seller_reputation

Response:

{
    "user_id": 1234,
    "site_id": "CBT",
    "seller_reputation": [
        {
            "user_id": 5678,
            "site_id": "MLM",
            "logistic_type": "remote",
            "seller_reputation": {
                "level_id": "5_green",
                "power_seller_status": "gold",
                "transactions": {
                    "canceled": 81,
                    "completed": 601,
                    "period": "historic",
                    "ratings": {
                        "negative": 0.04,
                        "neutral": 0.02,
                        "positive": 0.94
                    },
                    "total": 682
                },
                "metrics": {
                    "sales": {
                        "period": "60 days",
                        "completed": 219
                    },
                    "claims": {
                        "period": "60 days",
                        "rate": 0.0166,
                        "value": 4
                    },
                    "delayed_handling_time": {
                        "period": "60 days",
                        "rate": 0.0877,
                        "value": 20
                    },
                    "cancellations": {
                        "period": "60 days",
                        "rate": 0,
                        "value": 1
                    }
                }
            }
        },
        {
            "user_id": 33355,
            "site_id": "MLC",
            "logistic_type": "remote",
            "seller_reputation": {
                "level_id": null,
                "power_seller_status": null,
                "transactions": {
                    "canceled": 3,
                    "completed": 6,
                    "period": "historic",
                    "ratings": {
                        "negative": 0.09,
                        "neutral": 0.03,
                        "positive": 0.88
                    },
                    "total": 9
                },
                "metrics": {
                    "sales": {
                        "period": "365 days",
                        "completed": 6
                    },
                    "claims": {
                        "period": "365 days",
                        "rate": 0,
                        "value": 1
                    },
                    "delayed_handling_time": {
                        "period": "365 days",
                        "rate": 0,
                        "value": 7
                    },
                    "cancellations": {
                        "period": "365 days",
                        "rate": 0,
                        "value": 0
                    }
                }
            }
        },
        {
            "user_id": 123123,
            "site_id": "MLB",
            "logistic_type": "remote",
            "seller_reputation": {
                "level_id": null,
                "power_seller_status": null,
                "transactions": {
                    "canceled": 2,
                    "completed": 7,
                    "period": "historic",
                    "ratings": {
                        "negative": 0.31,
                        "neutral": 0,
                        "positive": 0.69
                    },
                    "total": 9
                },
                "metrics": {
                    "sales": {
                        "period": "365 days",
                        "completed": 7
                    },
                    "claims": {
                        "period": "365 days",
                        "rate": 0,
                        "value": 0
                    },
                    "delayed_handling_time": {
                        "period": "365 days",
                        "rate": 0,
                        "value": 1
                    },
                    "cancellations": {
                        "period": "365 days",
                        "rate": 0,
                        "value": 1
                    }
                }
            }
        },
        {
            "user_id": 678768,
            "site_id": "MCO",
            "logistic_type": "remote",
            "seller_reputation": {
                "level_id": null,
                "power_seller_status": null,
                "transactions": {
                    "canceled": 5,
                    "completed": 4,
                    "period": "historic",
                    "ratings": {
                        "negative": 1,
                        "neutral": 0,
                        "positive": 0
                    },
                    "total": 9
                },
                "metrics": {
                    "sales": {
                        "period": "365 days",
                        "completed": 4
                    },
                    "claims": {
                        "period": "365 days",
                        "rate": 0,
                        "value": 0
                    },
                    "delayed_handling_time": {
                        "period": "365 days",
                        "rate": 0,
                        "value": 1
                    },
                    "cancellations": {
                        "period": "365 days",
                        "rate": 0.5555,
                        "value": 5
                    }
                }
            }
        }
    ]
}

Get user campaigns

To get information about campaigns from users, please send the marketplace user_id as param.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/users/$USER_ID/campaigns

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/users/348252660/campaigns

Response:

{
    "campaigns": [{
        "id": 223493019,
        "name": "Campanha Principal",
        "user_id": 348252660,
        "status": "active",
        "daily_budget": 225,
        "acos_target": 15.0,
        "strategy": "visibility"
        "last_update": "2018-08-23T18:31:11.897Z",
        "creation_date": "2018-08-23T18:31:11.897Z",
        “acos_top_modifier”: 30
    },
   [...]
]
}

Response fields

id: campaign id.
name: campaign name. You can give a name, assign a daily budget and manage it according to your goals.
user_id: marketplace user with this campaign
status: campaign status. It can be: active or paused.

daily_budget: daily money amount to campaign. Value expressed in USD.
acos_target: ACOS is the advertising cost of sales. The ACOS target is the percentage of the cost of the campaign/advertisement in relation to the revenue obtained. It is a key data to understand the return on your advertising investment. For example, if your ACOS is 10%, it means that you invest $10 for every $100 that you generate from sales with advertisement.

strategy: type of strategy campaign. It can be: profitability, increase or visibility.

If you are looking for Profitability: you are going to improve your return on investment. This is recommended to boost your best-selling products.

With the objective of Growth: we can increase the exposure of your medium-notation products with medium levels of profitability.

And if we are looking for Visibility: we will get the best positions, promoting new products or competitive categories. This way we will achieve greater visibility over profitability.

last_update: last date update of the campaign. The time zone is GMT -3.
creation_date: creation date of the campaign. The time zone is GMT -3.
acos_top_modifier: It is the percentage of adjustment applied to the campaign’s ACOS target in order to bid specifically for the top search results.

Get campaign details

To get information about a campaign, send the campaign_id as a param achieved with the previous endpoint.

Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/campaigns/223493019

Response:

{
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "status": "active",
    "daily_budget": 225,
    "acos_target": 15.0,
    "strategy": "visibility"
    "last_update": "2018-08-23T18:31:11.897Z",
    "creation_date": "2018-08-23T18:31:11.897Z"
    ,
      “acos_top_modifier”:30
}

Create a new campaign

Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/campaigns -d 
{
    "name": "Campanha Principal",
    "user_id": 348252660,
    "daily_budget": 225,
    "acos_target": 15.0,
    "strategy": "visibility"
    "channel": "marketplace"
    ,
    “acos_top_modifier”: 30
}

Response:


 {
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "status": "active",
    "daily_budget": 225,
    "acos_target": 15.0,
    "strategy": "visibility"
    "last_update": "2018-08-23T18:31:11.897Z"
    "creation_date": "2018-08-23T18:31:11.897Z"
    “acos_top_modifier”: 30
}

Update campaign

To update a campaign you have to send the name, budget, strategy, acos_target and status attributes.

Request:

curl -X PUT -H Content-Type:application/json 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/campaigns/$CAMPAIGN_ID -d
{
    "name": "Campanha Principal",
    "daily_budget": 225,
    "acos_target": 15.0,
    "strategy": "visibility"
    "status" : "paused",
    “acos_top_modifier”: 30
}

Response:

{
    "id": 223493019,
    "name": "Campanha Principal",
    "user_id": 348252660,
    "status": "paused",
    "daily_budget": 225,
    "acos_target": 15.0,
    "strategy": "visibility"
    "last_update": "2018-08-23T18:31:11.897Z",
    "creation_date": "2018-08-23T18:31:11.897Z",
    “acos_top_modifier”: 30
}

Get item ads

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/ads/$ITEM_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/ads/MLM951330214

Response:

{
  "ads": [
    {
      "item_id": "MLM951330214",
      "campaign_id": 316572243,
      "user_id": 726488718,
      "site_id": "MLM",
      "status": "active",
      "title": "Item de Test", 
      "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",
      "creation_date": "2017-03-10T02:27:32.325+0000",
      "last_update": "2017-03-10T02:27:32.325+0000",
      "channel": "marketplace"
    }
  ]
}

Update specific ad

It will include the new status for the updated ad.

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/ads/$ITEM_ID?channel=marketplace -d
{
    "status": "active"
}

Response:

{
      "item_id": "MLM951330214",
      "campaign_id": 141072850,
      "user_id": 246460082,
      "site_id": "MLM",
      "status": "active",
      "title": "Item de Test", 
      "permalink": "http://articulo.mercadolibre.com.ar/MLM-657316800-item-de-testeo_JM",
      "thumbnail": "http://mla-s2-p.mlstatic.com/471325-MLM25424154856_032017-I.jpg",
      "picture_id": "471325-MLA25424154856_032017",
      "creation_date": "2017-03-10T02:27:32.325+0000",
      "last_update": "2017-03-10T02:27:32.325+0000",
      "channel": "marketplace"
}

Move ads to campaigns

If you want to move ads from one campaign to another, by default the ads keep their status. If the items (ads) have status paused and you want to move them with status active to another campaign, use the optional field "activate_all": true / false in the body.

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/ads/move -d
{
    "user_id": 615162762,
    "campaign_id": 321129959,
    "items": [
        "MCO834185796"
    ]
}

Response: status code 200.

Notes:

- This movement is asynchronous, so it will respond 200 immediately, but that does not mean that the item will have moved at that moment, but rather that it will be processed in the background with Eventual Consistency.
- You can only manage items with status active at the Mercado Libre.

Example moving ads with status active

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/ads/move -d
{
    "user_id": 615162762,
    "campaign_id": 321129959,
    "items": ["MCO834185796"]
    "activate_all":true
}

Get ads metrics

The date_from and date_to are mandatory parameter to define the start and end date for metrics search.

Mandatory parameter

Limit (numeric): limit of results that receives at most the value 1000.

Offset (numeric)

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/campaigns/$CAMPAIGN_ID/ads/metrics?date_from=$YYYY-MM-DD&date_to=$YYYY-MM-DD&offset=$OFFSET&limit=$LIMIT

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_ads/campaigns/$CAMPAIGN_ID/ads/metrics?date_from=2022-04-22&date_to=2022-04-29&offset=0&limit=2

Response:

{
    "paging": {
        "total": 29,
        "offset": 0,
        "limit": 2
    },
    "ads": [
        {
            "clicks": 0,
            "impressions": 0,
            "ctr": 0.0,
            "cost": 0.0,
            "cpc": 0.0,
            "acos": 0.0,
            "item_id": "MLC1030509956",
            "sold_quantity_direct": 0,
            "sold_quantity_indirect": 0,
            "sold_quantity_total": 0,
            "amount_direct": 0.0,
            "amount_indirect": 0.0,
            "amount_total": 0.0
        },
        {
            "clicks": 0,
            "impressions": 0,
            "ctr": 0.0,
            "cost": 0.0,
            "cpc": 0.0,
            "acos": 0.0,
            "item_id": "MLC1046469327",
            "sold_quantity_direct": 0,
            "sold_quantity_indirect": 0,
            "sold_quantity_total": 0,
            "amount_direct": 0.0,
            "amount_indirect": 0.0,
            "amount_total": 0.0
        }
    ]
}

Response fields

clicks: ad clicks quantity in this time period.
impressions: the times quantity your ads are shown with Mercado Ads on Mercado Libre pages in this time period.
ctr: Click Through Rate. Ad clicks quantity in relation with ad impressions quantity.
cos: The total cost generated by the clicks received in your Mercado Ads.
cpc: cost per click, it is the average of the ad.
sold_quantity_direct: Direct sale when a user clicks on your ad and buys that product.
sold_quantity_indirect: Assisted sale when a user clicks on your ad and buys another one of your products.
sold_quantity_total: sold_quantity_direct + sold_quantity_indirect.
amount_direct: Amount for direct sales.
amount_indirect: Amount for indirect sales

Get campaign metrics

As the previous endpoint, the date_from and date_to are mandatory parameter to define the start and end date for metrics search.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/advertising/product_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/marketplace/advertising/product_ads/campaigns/223493019/metrics?date_from=2022-06-13&date_to=2022-06-18

Response:

[
   {
  "days": [
{
	"date": "2022-08-01",
	"clicks": 5,
	"impressions": 564,
	"ctr": 0.89,
	"cost": 1.16,
	"cpc": 0.23,
	"acos": 0.0,
	"impression_share": 0.0,
	"lost_impression_share_by_budget": 0.0,
	"lost_impression_share_by_ad_rank": 0.0,
	"acos_benchmark": 0,
	"sold_quantity_direct": 0,
	"sold_quantity_indirect": 0,
	"sold_quantity_total": 0,
	"amount_direct": 0.0,
	"amount_indirect": 0.0,
	"amount_total": 0.0
}
 {...}
 ]
}

Response fields

impression_share: percentage of times that your ads are shown considering the all times that your ads can be shown. Impressions seller wins.
lost_impression_share_by_budget: percentage of times that your ads are not shown considering the all times that your ads can be shown and you lose because your budget is too low.
lost_impression_share_by_ad_rank: percentage of times that your ads are not shown considering the all times that your ads can be shown and you lose because your rank is lower than other sellers.
acos_benchmark: Acos target used by ads with good results in impressions and sales.

Errors

Error Code	Details	Solution
400	Bad Request: Any wrong information in input data	Service body will provide information about any wrong data in the provided input parameters. (Url params, Query params, Body, etc)
401	Unauthorized: Failed authentication	Send request with a valid login token.
404	Not found: Any request with a wrong path	Send request with a correct path.
429	Client Error: The user has sent too many requests in a given amount of time.	Reduce requests throughput.	-
5xx	Internal Server Error	Please, contact Support