Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentación
Manage Promotions
Use the /seller-promotions resource to centralize all the available promotion types, such as traditional campaigns (DEAL), Mercado Libre co-funded campaigns (MARKETPLACE_CAMPAIGN), price discounts (PRICE_DISCOUNT), lightning deals (LIGHTNING), deals of the day (DOD), volume discount (VOLUME), pre-negotiated discount per item (PRE NEGOTIATED), seller campaign (SELLER_CAMPAIGN), Automated co-participation (SMART), Competitive pricing campaign (PRICE_MATCHING), Full stock sale campaign (UNHEALTHY_STOCK), and seller coupon campaigns (SELLER_COUPON_CAMPAIGN). Besides the new types of deals that we will make available.
Promotion Characteristics
Campaign type | Name | Price definition | Price suggestion | Bonus MELI | Stock to participate | Deadline | Approval |
---|---|---|---|---|---|---|---|
Traditional | DEAL | User defines | No | No | No | Yes | Yes |
Co-funded campaigns | MARKETPLACE CAMPAIGN | User accepts | No | Yes | No | Yes | No |
Volume discount | VOLUME | 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 | Sim | No | Yes, required | No | No |
Pre-negotiated discount per item | PRE_NEGOTIATED | User agree and accepts | No | Yes | Yes | Yes | No |
Seller campaign | SELLER_CAMPAIGN | User defines and accepts | No | No | No | Yes | No |
Automated co-participation | SMART | User accepts | No | Yes | No | Yes | No |
Competitive pricing campaign | PRICE_MATCHING | User accepts | No | Yes | No | Yes | No |
Full stock sale campaign | UNHEALTHY_STOCK | User accepts | No | Yes | Yes | Yes | No |
Promotion Availability by Country
Site | Traditional campaigns (DEAL) |
Co-funded campaigns
(MARKETPLACE CAMPAIGN) |
Price discounts
(PRICE DISCOUNT) |
Volume discoun
(VOLUME) |
Pre-negotiated discount per item
(PRE_NEGOTIATED) |
Deals of the day
(DOD) |
Lightning deals
(LIGHTNING) |
Automated co-participation
(SMART) |
Competitive pricing campaign
(PRICE_MATCHING) |
Full stock sale campaign
(UNHEALTHY_STOCK) |
Seller campaign
(SELLER_CAMPAIGN) |
---|---|---|---|---|---|---|---|---|---|---|---|
MLA, MLB, MLM, MCO, MLC, MLU, MPE. | |||||||||||
MLV and MEC |
Campaigns available for sellers
Reminder - a user can have more than one and different types of invitations.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/$USER_ID?app_version=v2'
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/6313668461356551933?app_version=v2'
Response:
{
"results": [
{
"id": "P-MLB1806015",
"type": "MARKETPLACE_CAMPAIGN",
"status": "started",
"start_date": "2023-04-20T02:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "Campanha de teste v2",
"benefits": {
"type": "REBATE",
"meli_percent": 5,
"seller_percent": 25
}
},
{
"id": "P-MLB1806017",
"type": "VOLUME",
"status": "started",
"start_date": "2023-04-20T03:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "Leva 3 paga 2",
"benefits": {
"type": "VOLUME",
"meli_percent": 9.9999,
"seller_percent": 23.3331,
"name": "3x2",
"buy_quantity": 3,
"pay_quantity": 2,
"item_discount_percent": 33.333
}
},
{
"id": "P-MLB1806019",
"type": "DEAL",
"status": "started",
"start_date": "2023-04-20T03:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "deals de teste v2"
},
{
"id": "P-MLB1809008",
"type": "DEAL",
"status": "started",
"start_date": "2023-04-21T21:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "Deals de test v2"
},
{
"id": "P-MLB1809009",
"type": "DEAL",
"status": "started",
"start_date": "2023-04-21T23:00:00Z",
"finish_date": "2023-08-01T02:00:00Z",
"deadline_date": "2023-08-01T01:00:00Z",
"name": "campanha de teste"
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 5
}
}
Response fields
id: promotion ID code.
type: promotion type (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, SELLER_CAMPAIGN, SMART).
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?app_version=v2
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663?app_version=v2
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, SELLER_CAMPAIGN, SMART).
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?app_version=v2
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792?app_version=v2
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, SELLER_CAMPAIGN, SMART).
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.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=$PROMOTION_TYPE&app_version=v2'
Para obtener más información, acceda a las documentaciones de cada campaña.
Status
Find below the different and possible promotion type statuses:
- Traditional campaign status
- Co-funded campaign status
- Volume discount campaign status
- Pre-negotiated discount per item campaign status
View 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/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=PROMOTION_TYPE&app_version=v2'
It is also possible to view items of a:
- Traditional campaign
- Co-funded campaign
- Volume discount items
- Deal of the day
- Lightning deal
- Pre-negotiated discount
- Seller's campaign
- Smart campaign
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/items?promotion_type=$PROMOTION_TYPE&status=$STATUS&item_id=$ITEM_ID&app_version=v2
Filter example 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&app_version=v2
Response:
{
"results": [
{
"id": "MLA604400000",
"status": "started",
"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=started&app_version=v2
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.
In the GET response, we return the searchAfter parameter, which will be used to scroll through the results. To do this you must retrieve this ID and make the following request with the query param search_after={search_after}. This ID is a string, so you have to accept the string and use it later in your calls.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&app_version=v2&limit=50&search_after={$SEARCH_AFTER}'
Example of pagination:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB13451002MLB9377/items?promotion_type=DEAL&app_version=v2&limit=50&search_after=d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca1b1a42'
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":
"d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca3b5b55MLB2674512267",
"limit": 50,
"total": 14424
}
}
Considerations
- Search_after will be returned on all pages except the last page.
- The only way to advance the response (paginate) is through the use of this parameter.
- When iterating the results, each request will return the search_after that should be used in the next call.
- Always use the search_after that was provided by the request response, since it can change and expire (they have a TTL of 5 minutes).
- Backward paging is not possible.
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.
- Specifying items for a co-funded campaign.
- Specifying items for volume discount.
- Accepting a pre-negotiated discount per Item.
- Specifying items for a deal of the day.
- Specifying items for a lightning deal.
- Offering a price discount for an item.
- Indicating items for a seller's campaign.
- Indicating items for a Smart campaign.
Check Item Promotions
Here you can obtain all the promotions that the item has and the status of the promotions at the moment of the consult.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA876768946MLB3538191898?app_version=v2
Resposta:
[
{
"type": "PRICE_DISCOUNT",
"status": "candidate",
"price": 4000,
"start_date": "2023-04-26T00:00:00",
"finish_date": "2023-05-10T00:00:00"
},
{
"type": "DOD",
"status": "candidate",
"price": 4000,
"start_date": "2023-04-28T00:00:00",
"finish_date": "2023-04-28T23:59:59"
},
{
"id": "P-MLB1817004",
"type": "MARKETPLACE_CAMPAIGN",
"status": "pending",
"start_date": "2023-04-27T23:00:00Z",
"finish_date": "2023-06-01T02:00:00Z",
"deadline_date": "2023-06-01T01:00:00Z",
"name": "Campanha teste 10",
"benefits": {
"type": "REBATE",
"meli_percent": 3,
"seller_percent": 27
}
},
{
"id": "MLB1345",
"type": "DEAL",
"status": "pending",
"start_date": "2023-04-27T23:00:00-03:00",
"finish_date": "2023-05-31T23:00:00-03:00",
"name": "teste 20"
},
{
"id": "C-MLB300",
"type": "SELLER_CAMPAIGN",
"sub_type": "FIXED_PERCENTAGE",
"status": "started",
"price": 4250,
"top_price": 3500,
"start_date": "2023-04-27T00:00:00",
"finish_date": "2023-05-05T23:59:59",
"name": "camp del seller 1"
},
{
"id": "P-MLB1812010",
"type": "SMART",
"status": "started",
"name": "test-smart-2",
"offers": [
{
"id": "OFFER-MLB3538191898-177685",
"original_price": 5000,
"new_price": 3000,
"prime_price": null,
"status": "active",
"start_date": "2023-04-26T11:40:00Z",
"end_date": "2023-05-30T15:47:00Z",
"benefits": {
"type": "REBATE",
"meli_percent": 20,
"seller_percent": 20
}
}
]
},
{
"id": "C-MLB302",
"type": "SELLER_CAMPAIGN",
"sub_type": "FLEXIBLE_PERCENTAGE",
"status": "candidate",
"start_date": "2023-04-27T12:04:00",
"finish_date": "2023-05-05T00:00:00",
"name": "camp del seller 2"
}
]
Modify Items
You can modify items included in a deal by:
- Changing items in a traditional campaign.
- Changing items in a co-funded campaign.
- Changing items in a volume discount campaign.
Massive delete of offers
You can massively delete all the offers that are in the item.
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2
Example:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA1399846831?app_version=v2
Response:
{
"successful_ids": [
{
"offer_id": "OFFER-MLA1399846831-10000081416",
"error": null
},
{
"offer_id": "OFFER-MLA1399846831-10000081567",
"error": null
}
],
"errors": []
}
In cases where the item has campaigns that cannot be deleted in bulk, the call will receive an HTTP 200 response, but the response will contain error messages.
Example where no offer can be deleted:
{
"successful_ids": [],
"errors": [
{
"offer_id": "OFFER-MLA1399846831-10000081416",
"error": "The offer of type DOD not allowed for delete."
},
{
"offer_id": "OFFER-MLA1399846831-10000081828",
"error": "The offer could not be deleted. Try again."
}
]
}
Example where offers were successfully removed and errors also occurred:
{
"successful_ids": [
{
"offer_id": "OFFER-MLA1399846831-10000081416",
"error": null
},
{
"offer_id": "OFFER-MLA1399846831-10000081417",
"error": null
}
],
"errors": [
{
"offer_id": "OFFER-MLA1399846831-10000081418",
"error": "The offer of type DOD not allowed for delete."
},
{
"offer_id": "OFFER-MLA1399846831-10000081419",
"error": "The offer could not be deleted. Try again."
}
]
}
Possible errors.
423_ENTITY_LOCKED: The request could not be processed because the item is temporarily blocked from making requests. The request can be attempted again after a few seconds
400_BAD_REQUEST: When the item format is invalid.
Delete Items
You can change the items included in a given deal by:
- Deleting items in a traditional campaign.
- Deleting items in a co-funded campaign.
- Deleting items in a volume discount campaign.
- Deleting a pre-negotiated discount per item.
- Deleting items in a deal of the day.
- Deleting items in a lightning deal.
- Deleting a price discount for an item.
Test Campaigns
For test campaigns, please send user data and/or items in the following support.
Reminder - both users and items should be test users and items.
Next Post: Traditional Campaigns