Documentation Mercado Libre

Check out all the necessary information about APIs Mercado Libre.
circulos azuis em degrade

Documentation

Last update 27/08/2024

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_search_target": 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_search_target: It is the ACOS (Advertising Cost of Sales) target defined for a campaign 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_search_target”: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_search_target”: 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_search_target”: 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_search_target”: 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_search_target”: 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