Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
Seller campaigns
Sellers can create their own campaigns through their Mercado Livre account and manage them through the integration. If the seller has created a campaign and wants to manage the candidate items, he can do so with the following resources.
To offer this discount, it is necessary:
- To have a green reputation.
- The item must have a status equal to active or paused.
- Condition equal to new.
- The item's exposure cannot be free.
Create campaign
To create a seller campaign make the following request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
{
"promotion_type": "SELLER_CAMPAIGN",
"name": "test campana del seller",
"sub_type": "FIXED_PERCENTAGE",
"fixed_percentage": 15,
"loyalty_percentage": 30,
"start_date": "2023-07-17T00:00:00",
"finish_date": "2023-07-20T00:00:00"
}
Request fields
promotion_type: type of campaign to create, at the moment only SELLER_CAMPAIGN is allowed.
name: campaign name.
sub_type: in the case of Seller Campaigns, the sub_types allowed are FIXED_PERCENTAGE and FLEXIBLE_PERCENTAGE.
fixed_percentage: only for FIXED_PERCENTAGE (Required).
loyalty_percentage: only for FIXED_PERCENTAGE (Optional, discount with loyalty).
start_date: campaign start date in local format. The beginning of the day will always be taken as the start time.
finish_date: campaign end date in local format. The end of the day will always be taken as the end time.
Response:
{
"id": "C-MLB360923",
"type": "SELLER_CAMPAIGN",
"sub_type": "FIXED_PERCENTAGE",
"fixed_percentage": 15,
"loyalty_percentage": 30,
"status": "pending",
"start_date": "2023-07-17T00:00:00",
"finish_date": "2023-07-20T23:59:59",
"name": "test campana del seller"
}
Update campaign
All fields can be modified, but only the fields that you wish to modify should be submitted. The only mandatory one is promotion_type, which must always be present. If you want to remove the loyalty discount, you must send remove_loyalty to true.
Example:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?app_version=v2
{
"promotion_type": "SELLER_CAMPAIGN",
"name": "new name 10",
"sub_type": "FIXED_PERCENTAGE",
"fixed_percentage": 18,
"loyalty_percentage": 33,
"start_date": "2023-07-18T00:00:00",
"finish_date": "2023-07-19T00:00:00",
"remove_loyalty": false
}
Response:
{
"id": "C-MLB360923",
"type": "SELLER_CAMPAIGN",
"sub_type": "FIXED_PERCENTAGE",
"fixed_percentage": 18,
"loyalty_percentage": 33,
"status": "pending",
"start_date": "2023-07-18T00:00:00",
"finish_date": "2023-07-19T23:59:59",
"name": "new name 10"
}
Delete campaign
To remove a campaign from the seller I make this call:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=SELLER_CAMPAIGN&app_version=v2
Example:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB360923?promotion_type=SELLER_CAMPAIGN&app_version=v2
Response: Status 200 OK
View campaign details
There are two subtypes of seller campaigns:
FIXED_PERCENTAGE - has a fixed discount percentage.
FLEXIBLE_PERCENTAGE - has no fixed percentage.
To get the details of a seller campaign, make the following query:
Example sub_type FIXED_PERCENTAGE:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB300?promotion_type=SELLER_CAMPAIGN&app_version=v2
Response:
{
"id": "C-MLB300",
"type": "SELLER_CAMPAIGN",
"sub_type": "FIXED_PERCENTAGE",
"fixed_percentage": 15,
"loyalty_percentage": 30,
"status": "started",
"start_date": "2023-04-27T15:03:00Z",
"finish_date": "2023-05-05T03:00:00Z",
"name": "camp del seller 1"
}
Example sub_type FLEXIBLE_PERCENTAGE:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB302?promotion_type=SELLER_CAMPAIGN&app_version=v2
Response:
{
"id": "C-MLB302",
"type": "SELLER_CAMPAIGN",
"sub_type": "FLEXIBLE_PERCENTAGE",
"status": "started",
"start_date": "2023-04-27T15:04:00Z",
"finish_date": "2023-05-05T03:00:00Z",
"name": "camp del seller tahi 2"
}
Response fields
- id: campaign identifier.
- type: campaign type (SELLER_CAMPAIGN).
- sub_type: currently we have two, which are: FIXED_PERCENTAGE and FLEXIBLE_PERCENTAGE.
- fixed_percentage discount percentage for all buyers.
- loyalty_percentage discount percentage for the best buyers (levels 3 to 6 of the Mercado Puntos).
- status: campaign status.
- start_date: date when the campaign starts.
- finish_date: date when the campaign ends.
- name: name of the campaign.
Status
These are the different states that a seller's campaign can go through.
Status | Description |
---|---|
pending | Promotion approved, but not yet started. |
started | Active promotion. |
finished | Finished promotion. |
View items in a campaign
To see the items that are part of a seller campaign, make the following query:
Example sub_type FIXED_PERCENTAGE:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/C-MLB300/items?promotion_type=SELLER_CAMPAIGN&app_version=v2'
Response:
{
"results": [
{
"id": "MLB3538191898",
"status": "candidate",
"price": 0,
"original_price": 5000,
"fixed_percentage": 15,
"loyalty_percentage": 30,
"start_date": "2023-04-27T12:03:00",
"end_date": "2023-05-05T00:00:00",
"sub_type": "FIXED_PERCENTAGE"
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 1
}
}
Example sub_type FLEXIBLE_PERCENTAGE:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/C-MLB302/items?promotion_type=SELLER_CAMPAIGN&app_version=v2'
Response:
{
"results": [
{
"id": "MLB3538191898",
"status": "candidate",
"price": 0,
"original_price": 5000,
"start_date": "2023-04-27T12:04:00",
"end_date": "2023-05-05T00:00:00",
"sub_type": "FLEXIBLE_PERCENTAGE"
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 1
}
}
Items-status
In the following table you will find the possible status that items in a seller campaign can have:
Status | Description |
---|---|
candidate | Candidate item to participate in the promotion. |
pending | Approved item and scheduled promotion. |
started | Active item in the campaign. |
finished | Deleted item from the campaign. |
Indicates items fo a campaign
Once you have items invited to participate in a seller campaign, you can indicate which products you want to include in the campaign.
Example sub_type FIXED_PERCENTAGE:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
"promotion_id":"C-MLB300",
"promotion_type":"SELLER_CAMPAIGN"
}'
https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2
Response:
{
"price": 4250,
"original_price": 5000
}
Example sub_type FLEXIBLE_PERCENTAGE:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
"promotion_id":"C-MLB302",
"promotion_type":"SELLER_CAMPAIGN",
"deal_price": 3500,
"top_deal_price": 3000
}'
https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2
Response:
{
"price": 3500,
"original_price": 5000
}
Parameters
- promotion_id: promotion ID.
- promotion_type: promotion type (SELLER_CAMPAIGN).
- deal_price price of the item in the promotion.
- top_deal_price price of the item for the best buyers, with level 3 to 6 of the Mercado Puntos (it is optional to inform this price).
Modify items
In this type of campaign, you can only modify the items that belong to the campaign with sub_type FLEXIBLE_PERCENTAGE.
To modify the items perform the following operation.
Example:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
"promotion_id":"C-MLB302",
"promotion_type":"SELLER_CAMPAIGN",
"deal_price": 3300,
"top_deal_price": 3000
}'
https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2
Response:
{
"price": 3300,
"original_price": 5000
}
Considerations
- If you have loyalty discount loaded, you can't remove that discount anymore.
Error message: "Top_deal_price can't be removed when the seller campaign has already started". - If it was created without the loyalty discount, it cannot be added later.
Error message: "Top_deal_price can't be set when the seller campaign has already started" . - Prices can only improve.
Error message: "New deal_price must be lower than current deal_price" / "New top_deal_price must be lower than current top_deal_price".
- The deal_price and top_deal_price can be modified for a higher or lower discount.
- You can add or remove the loyalty discount.
Example. Modification of top_deal_price:
{
"top_deal_price": 1000.33,
"promotion_id": "C-MLA123",
"promotion_type": "SELLER_CAMPAIGN"
}
Example. Modification of deal_price and removal of top_deal_price:
{
"deal_price": 700,
"promotion_id": "C-MLA123",
"promotion_type": "SELLER_CAMPAIGN",
"remove_loyalty": true
}
Response:
{
"price": 950,
"original_price": 1000
}
Delete
Request:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&promotion_id=$PROMOTION&app_version=v2'
Example:
curl -X DELETE -H 'https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?promotion_type=SELLER_CAMPAIGN&promotion_id=C-MLB302
Response: Status 200 OK
Validation errors: 400 bad request
Error message | Description |
---|---|
The name already exists | A seller campaign with the same name already exists. |
Invalid sub_type | When the sub_type of a SELLER_CAMPAIGN is neither FLEXIBLE_PERCENTAGE nor FIXED_PERCENTAGE. |
The percentage is greater than allowed. the maximum percentage allowed is 70.000000 | The maximum percentage allowed is 70%. If it is sent, for example, fixed_percentage: 71, it will return this error. |
The percentage is less than allowed. the minimum percentage allowed is 10.000000 | The percentage is below the allowed. |
Fixed_percentage is required | If the promotion is of type FIXED_PERCENTAGE, the fixed_percentage field is required. |
Invalid promotion type | When the promotion_type is invalid. |
Start and finish dates must be in local format | When the dates sent are not in local format (like the example) or are not sent at all. |
Start_date cannot be earlier than today | Start_date cannot be earlier than today. |
Finish_date cannot be earlier than startdate | Finish_date cannot be earlier than start_date. |
Maximum period cannot exceed the allowed | When the distance between the start and finish date is greater than the allowed one. |
The percentage difference between sellerpercentage and loyaltypercentage does not meet the minimum required | The difference between the seller_percentage and loyalty_percentage must be greater than or equal to 5%. |
Maximum period cannot exceed the allowed | When you want to update some date (or both), and the new period between them exceeds the allowed one. |
Percentages of a FLEXIBLE PERCENTAGE promotion must be updated per offer | An attempt is made to modify a percentage or loyalty percentage to a campaign that is of the flexible_percentage type. Percentages can only be set generally in fixed_percentages. For flexible promotions, the prices of particular offers must be edited. |
The start_date field cannot be modified for the current promotion status | You cannot change the start date of a promotion in the started state. |