Documentation Mercado Libre
Check out all the necessary information about APIs Mercado Libre.
Documentation
Last update 26/02/2024
Deals
Get campaigns details
To see the details of a campaign, you should send the marketplace user_id as well as the deal_id you wish to query.
Request:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$PROMOTION_ID?promotion_type=DEAL&user_id=$USER_ID
--header 'version: v2' \
--header 'X-Client-Id: \
--header 'X-Caller-Id: \
Example:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13757022?promotion_type=DEAL&user_id=1317418851' --header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \
Response:
{
"id": "P-MLM13757022",
"type": "DEAL",
"status": "started",
"start_date": "2024-01-29T06:00:00Z",
"finish_date": "2024-02-12T06:00:00Z",
"deadline_date": "2024-02-11T06:00:00Z",
"name": "Ano nuevo chino"
}Status
Find below the different traditional campaign statuses:
| Status | Description |
|---|---|
| pending | Promotion approved but not yet started. |
| started | Active promotion. |
| finished | Finished promotion. |
Check Campaign Items
To get all the items included in a campaign, you should send the marketplace useer_id and the deal_id.
Request:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$PROMOTION_ID?/items?user_id=$USER_ID
--header 'version: v2' \
--header 'X-Client-Id: \
--header 'X-Caller-Id: \
Example:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET
'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13757022/items?user_id=1317418851' \
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \Response:
{
"results": [
{
"id": "MLM2760672650",
"status": "candidate",
"price": 35,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 10.5
},
{
"id": "MLM2199514002",
"status": "candidate",
"price": 70,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 21
},
{
"id": "MLM2184798066",
"status": "candidate",
"price": 30,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 9
},
{
"id": "MLM2184785146",
"status": "candidate",
"price": 20,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 6
},
{
"id": "MLM2184694464",
"status": "candidate",
"price": 100,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 30
},
{
"id": "MLM2184694462",
"status": "candidate",
"price": 90,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 27
},
{
"id": "MLM2184629206",
"status": "candidate",
"price": 110,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 33
},
{
"id": "MLM2184629204",
"status": "candidate",
"price": 32,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 9.6
},
{
"id": "MLM2184616078",
"status": "candidate",
"price": 130,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 39
},
{
"id": "MLM2183927324",
"status": "candidate",
"price": 700,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 210
},
{
"id": "MLM2183927322",
"status": "candidate",
"price": 50,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 15
},
{
"id": "MLM2183693560",
"status": "started",
"price": 65.8,
"original_price": 70,
"currency_id": "USD"
},
{
"id": "MLM2172266146",
"status": "candidate",
"price": 12,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 3.6
},
{
"id": "MLM2132031350",
"status": "candidate",
"price": 12,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 3.6
},
{
"id": "MLM2132031328",
"status": "candidate",
"price": 12,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 3.6
},
{
"id": "MLM2131927804",
"status": "candidate",
"price": 60,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 18
},
{
"id": "MLM1991842995",
"status": "candidate",
"price": 12,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 3.6
},
{
"id": "MLM1886904585",
"status": "candidate",
"price": 12,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 3.6
},
{
"id": "MLM1886904569",
"status": "candidate",
"price": 25,
"original_price": 0,
"currency_id": "USD",
"min_discounted_price": 7.5
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 19,
"searchAfter": ""
}
}Item status
The table below shows the possible item status in this type of campaign.
| Status | Description |
|---|---|
| candidate | Item eligible for deal. |
| pending | Item sent to deal but not started. |
| started | Item with deal already started. |
| finished | Item deleted from campaign |
Submit an item to a campaign"
For applying to a campaign you should send the item_id and desired price as well as the marketplace user_id of the country in which you want to participate in.
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d
{
"promotion_id": "DEAL",
"deal_price": "$DEAL_PRICE",
"promotion_type": "$PROMOTION_TYPE",
}
https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_IDThe fields regular_price and deal_price should be in US dollars.
Example:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X POST
'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2760672650?user_id=1317418851' \
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \
--data '{
"promotion_id": "P-MLM13757022",
"deal_price": 15,
"promotion_type": "DEAL"
}Response:
{
"price": 15,
"original_price": 35,
"currency_id": "USD"
}The fields price and original_price are in US dollars.
Parameters
- deal_price: items price in the promotion.
- top_deal_price: item price for best buyers, with Mercado Puntos level 3 to 6 (it is optional to report this price).
- promotion_id: promotion identification.
- promotion_type: type of promotion (DEAL).
Edit a deal in a campaign
To edit a deal of a certain campaign you should send the deal_id, item_id and desired price as well as the marketplace user_id of the country where the campaign takes place.
Request:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -d
{
"promotion_id": "DEAL",
"deal_price": "$DEAL_PRICE",
"promotion_type": "$PROMOTION_TYPE",
}
https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_IDExample:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X PUT curl
'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2760672650?user_id=1317418851' \
--header 'version: v2' \
--header 'Content-Type: text/plain' \
--data '{
"promotion_id": "P-MLM13757022",
"deal_price": 14,
"promotion_type": "DEAL"
}The fields regular_price and deal_price are expressed in US dollars.
Response:
{
"price": 14,
"original_price": 35,
"currency_id": "USD"
}The fields price and original_price are expressed in US dollars.
Delete a deal from a campaign
If you wish to remove an item from a campaign, you should send the item_id, the deal_id and the promotion_type. You’ll also need the marketplace user_id of the site where the campaign is active.
Request:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X DELETE https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID&promotion_type=$PROMOTION_TYPE&deal_id=$DEAL_IDExample:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X DELETE
'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2760672650?user_id=1317418851&promotion_type=DEAL&promotion_id=P-MLM13757022' \
--header 'version: v2' \
--header 'X-Client-Id: 1317417907' \
--header 'X-Caller-Id: 1317417907' \This method just returns a status_code 200 if it was processed as expected.
Next: Co-Funded Campaigns