Documentation Mercado Libre
Check out all the necessary information about APIs Mercado Libre.
Documentation
Manage Promotions
Promotion Characteristics
Campaign type | Name | Price definition | Price suggestion | Bonus MELI | Stock to participate | Deadline | Approval |
---|---|---|---|---|---|---|---|
Sales events | DEAL | User defines | No | No | No | Yes | Yes |
Co-funded campaigns | MARKETPLACE CAMPAIGN | User accepts | No | Yes | No | Yes | No |
Deals of the day | DOD | User accepts | Yes | No | Yes, informative | No | No |
Lightning deals | LIGHTNING | User defines | Yes | No | Yes, required | No | No |
Volume discount | VOLUME | User accepts | No | Yes | No | Yes | No |
Pre-negotiated discount per item | PRE_NEGOTIATED | User agree and accepts | No | Yes | No | Yes | No |
Sales promotions for the seller
A user can have more than one as well as different types of invitations.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/$USER_ID'
Response:
{
"results": [
{
"id": "LGH-MLM1000",
"type": "LIGHTNING",
"status": "started",
"start_date": "2000-01-01T00:00:00.000Z",
"finish_date": ""
},
{
"id": "DOD-MLM1000",
"type": "DOD",
"status": "started",
"start_date": "2000-01-01T00:00:00.000Z",
"finish_date": ""
},
{
"id": "MLM1907",
"type": "DEAL",
"status": "test",
"start_date": "2020-01-31T07:59:00Z",
"finish_date": "2022-11-01T16:59:00Z",
"deadline_date": "2021-02-01T12:59:00-04:00",
"name": "Name Deal"
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 3
}
}
Response fields
id: promotion ID code.
type: promotion type (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME).
status: Status.
start_date: promotion start date.
finish_date: promotion finish date.
deadline_date: maximum term to add promotional items.
name: promotion name.
deadline_date: maximum time limit for accepting the invitation to participate in the promotion.
benefits: promotion benefit configuration.
Consult candidate items
The /seller-promotions/candidates resource allows you to identify the items invited to participate in a promotion. Whenever an item obtains the status of "candidate" in a promotion a notification is sent with the candidate_id, with this resource it is possible to identify the item, the promotion and the status.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663
Response:
{
"id": "CANDIDATE-MLB1254949426-803130663",
"item_id": "MLB1254949426",
"promotion_id": "P-MLB4629001",
"type": "MARKETPLACE_CAMPAIGN",
"status": {
"id": "candidate"
}
}
Response fields
id: candidate identification code.
item_id: item associated with the candidate.
promotion_id: promotion id.
type: promotion type (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED).
status: status of the applicant.
Check offers
Use the /seller-promotions/offers resource allows you to identify changes in the offer of an item. All changes are sent by notifications with the offer_id, and it is possible to identify the item, the promotion, and the status.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792
Response:
{
"id": "OFFER-MLB1970246686-42701792",
"item_id": "MLB1970246686",
"promotion_id": "P-MLB3329001",
"type": "DEAL",
"status": {
"id": "ACTIVE"
}
}
Response fields
id: Identification code of the offer.
item_id: Item associated with the offer.
promotion_id: Promotion id.
type: type of promotion (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED).
status: status of the offer (programmed, active, e inactive).
Promotion Details
Perform the following query to access the specific details of traditional campaigns, co-funded campaigns, and volume discounts.
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$DEAL_ID?promotion_type=$PROMOTION_TYPE&user_id=$USER_ID
Example:
curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/MLM1907?promotion_type=DEAL&user_id=523132944
Response:
{
"id": "MLM1907",
"type": "DEAL",
"status": "started",
"start_date": "2020-01-31T07:59:00Z",
"finish_date": "2022-11-01T16:59:00Z",
"deadline_date": "2021-02-01T16:59:00Z",
"name": "Name Deal"
}
Check Promotion Items
Perform the query below to check the items included in a given promotion:
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$DEAL_ID/items?user_id=$USER_ID'
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/promotions/LGH-MLM1000/items?user_id=481244699
Response:
{
"results": [
{
"id": "MLM745913661",
"status": "candidate",
"price": 26.05,
"original_price": 0,
"currency_id": "USD",
"stock": {
"min": 10,
"max": 15
}
},
{
"id": "MLM755504940",
"status": "candidate",
"price": 22.2,
"original_price": 0,
"currency_id": "USD",
"stock": {
"min": 10,
"max": 15
}
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 2
}
}
You can also check the items included in a traditional campaign.
Check deal of the day items and lightning deal items.
Filters
You can apply filters by item or status.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=DEAL&status=$STATUS&item_id=$ITEM_ID
Example of filter by item:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&item_id=MLA604400000
Response:
{
"results": [
{
"id": "MLA604400000",
"status": "rejected",
"price": 23968,
"original_price": 28549
}
],
"paging": {...}
}
Example of filter by status started:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' /seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&status=approved
Response:
{
"results": [
{
"id": "MLA639970000",
"status": "started",
"price": 4037,
"original_price": 4427
},
{
"id": "MLA639973333",
"status": "started",
"price": 6007,
"original_price": 6587
},
],
"paging": [...]
}
Pagination
To perform pagination you must use the searchAfter parameter. The value sent in this parameter is always the last id of the item returned in the previous call.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&searchAfter=$ITEM_ID'
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/MLB9377/items?promotion_type=DEAL&searchAfter=MLB2674512267'
Response:
"results": [
{
"id": "MLB2674512266",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674506199",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674506138",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674505931",
"status": "candidate",
"price": 0,
"original_price": 0
},
{
"id": "MLB2674505924",
"status": "candidate",
"price": 0,
"original_price": 0
[…]
"paging": {
"searchAfter": "MLB2674512267",
"limit": 50,
"total": 14424
}
}
Participate in a Promotion
You can participate in different types of promotions and even offer an item price discount by:
- Specifying items for a traditional campaign.
- Offering a price discount for an item.
- Specifying items for a deal of the day.
- Specifying items for a lightning deal.
Check Item Promotions
For DEALS we will return items with status = approved only.
We will not approve test campaigns, which will remain with pending_approval, i.e., you will not see the promotion price.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM755504940?user_id=481244699
Response:
[
{
"id": "3587589-MLM755504940",
"type": "DOD",
"status": "pending",
"start_date": "2021-06-11T00:00:00",
"finish_date": "2021-06-11T23:59:59.999999999"
},
{
"id": "3668214-MLM755504940",
"type": "PRICE_DISCOUNT",
"status": "started",
"start_date": "2021-06-10T00:00:00",
"finish_date": "2021-06-11T00:00:00"
}
]