Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.Documentación
Seller coupon campaigns
To offer this discount:
- You need to have green reputation.
- The item’s status must be equal to active.
- Condition: new.
- The item’s exposure cannot be free.
These are the same criteria for the item to participate in an individual discount campaign, e.g., if the item is a candidate for this campaign, it automatically meets the criteria to participate in a seller's coupon campaign as well.
Creating a campaign
There are two types of coupon campaigns (with or without code), but there are also two sub_types: FIXED_PERCENTAGE and FIXED_AMOUNT.
FIXED_AMOUNT it is the fixed amount of discount, regardless of the total accumulated price of the items participating in this campaign in the buyer's cart.
FIXED_PERCENTAGE this is the fixed discount percentage, and it's dependent on the total cumulative price of the items participating in this campaign in the buyer's cart.
To create a seller coupon campaign, perform the following request.
Example "sub_type": "FIXED_AMOUNT" with coupon code:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
{
"promotion_type": "SELLER_COUPON_CAMPAIGN",
"name": "test_coupon",
"sub_type": "FIXED_AMOUNT",
"start_date": "2023-10-14T00:00:00",
"finish_date": "2023-10-30T00:00:00",
"fixed_amount": 200,
"min_purchase_amount": 1000,
"partial_coupon_code": "MYCODE",
"budget": 10000
}
Example “sub_type”: “FIXED_AMOUNT” without coupon code:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
{
"promotion_type": "SELLER_COUPON_CAMPAIGN",
"name": "test_coupon",
"sub_type": "FIXED_AMOUNT",
"start_date": "2023-10-14T00:00:00",
"finish_date": "2023-10-30T00:00:00",
"fixed_amount": 200,
"min_purchase_amount": 1000,
"budget": 10000
}
Example “sub_type”: “FIXED_PERCENTAGE” with coupon code:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
{
"promotion_type": "SELLER_COUPON_CAMPAIGN",
"name": "test_coupon",
"sub_type": "FIXED_PERCENTAGE",
"start_date": "2023-10-14T00:00:00",
"finish_date": "2023-10-30T00:00:00",
"fixed_percentage": 10,
"min_purchase_amount": 1000,
"max_purchase_amount": 200,
"partial_coupon_code": "MYCODE",
"budget": 10000
}
Example "sub_type": "FIXED_PERCENTAGE" without coupon code:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
{
"promotion_type": "SELLER_COUPON_CAMPAIGN",
"name": "test_coupon",
"sub_type": "FIXED_PERCENTAGE",
"start_date": "2023-10-14T00:00:00",
"finish_date": "2023-10-30T00:00:00",
"fixed_percentage": 10,
"min_purchase_amount": 1000,
"max_purchase_amount": 200,
"budget": 10000
}
Request fields
- promotion_type (Mandatory): type of campaign to create, in this case SELLER_COUPON_CAMPAIGN.
- name (Mandatory): name of the campaign (only the seller will view it, the buyer won’t).
- sub_type (Mandatory): subtype of campaign to create. For the seller coupon campaign case, the allowed subtypes are FIXED_PERCENTAGE and FIXED_AMOUNT.
- fixed_percentage: promotion discount percentage. It’s only mandatory for the subtype FIXED_PERCENTAGE.
- fixed_amount: promotion discount amount. It’s only mandatory for the subtype FIXED_AMOUNT.
- min_purchase_amount (Mandatory): minimum purchase amount for the coupon to be applied.
- max_purchase_amount: maximum reimbursement amount for the total purchase value to which the coupon was applied. It’s only mandatory for the subtype FIXED_PERCENTAGE.
- start_date (Mandatory): start date of the campaign in the local format. The beginning of the day will always be considered as the start time.
- finish_date (Mandatory): campaign end date in the local format. The end of the day will always be considered as the end time.
- partial_coupon_code: partial coupon code. Optional. Only buyers who have this code will be able to use it for their purchase and the final value of this field will be composed by the first five characters of the seller's nickname followed by the value they send (maximum 10 characters). If this field is not submitted, all buyers who view the seller's listings will be able to use this couponr.
- budget (Mandatory): budget for the campaign. Once it’s used up, the campaign ends.
Response sub_type FIXED_AMOUNT with coupon code:
{
"id": "C-MLB1234",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_AMOUNT",
"fixed_amount": 200,
"min_purchase_amount": 1000,
"status": "pending",
"start_date": "2023-10-14T00:00:00Z",
"finish_date": "2023-11-01T02:59:59Z",
"name": "test_coupon",
"coupon_code": "NICKNMY_CODE",
"redeems_per_user": 1,
"budget": 10000,
"remaining_budget": 10000,
"used_coupons": 0
}
Response sub_type FIXED_AMOUNT without coupon code:
{
"id": "C-MLB1234",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_AMOUNT",
"fixed_amount": 200,
"min_purchase_amount": 1000,
"status": "pending",
"start_date": "2023-10-14T00:00:00Z",
"finish_date": "2023-11-01T02:59:59Z",
"name": "test_coupon",
"redeems_per_user": 1,
"budget": 10000,
"remaining_budget": 10000,
"used_coupons": 0
}
Response sub_type FIXED_PERCENTAGE with coupon code:
{
"id": "C-MLB1234",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_AMOUNT",
"fixed_percentage": 10,
"min_purchase_amount": 1000,
"max_purchase_amount": 200,
"status": "pending",
"start_date": "2023-10-14T00:00:00Z",
"finish_date": "2023-11-01T02:59:59Z",
"name": "test_coupon",
"coupon_code": "NICKNMY_CODE",
"redeems_per_user": 1,
"budget": 10000,
"remaining_budget": 10000,
"used_coupons": 0
}
Response sub_type FIXED_PERCENTAGE without coupon code:
{
"id": "C-MLB1234",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_AMOUNT",
"fixed_percentage": 10,
"min_purchase_amount": 1000,
"max_purchase_amount": 200,
"status": "pending",
"start_date": "2023-10-14T00:00:00Z",
"finish_date": "2023-11-01T02:59:59Z",
"name": "test_coupon",
"redeems_per_user": 1,
"budget": 10000,
"remaining_budget": 10000,
"used_coupons": 0
}
CResponse fields
- id: campaign identifier with the format C-{siteId}XXXXX. Example: “C-MLB1234”.
- type: type of campaign (SELLER_COUPON_CAMPAIGN).
- sub_type: campaign subtype (FIXED_AMOUNT or FIXED_PERCENTAGE).
- fixed_percentage: discount percentage value. Returned whenever the campaign is of subtype FIXED_PERCENTAGE.
- fixed_amount: discount amount value. Returned whenever the campaign is of subtype FIXED_AMOUNT.
- min_purchase_amount: minimum purchase amount.
- max_purchase_amount: maximum reimbursement amount. It is returned whenever the campaign is of subtype FIXED_PERCENTAGE.
- status: campaign status. Can be pending or started.
- start_date: campaign start date.
- finish_date: campaign end date.
- name: name used to identify the campaign.
- coupon_code: coupon code. If the nickname of the seller is NICKNAME1234, the coupon_code will be NICKN + the code completed by the user.
- redeems_per_user: amount of times a user can use the coupon of this campaign. It’s always 1, the buyer can use the coupon once.
- budget: budget for the campaign, it’s 100% at the seller’s expense.
- remaining_budget: remaining budget for the campaign.
- used_coupons: total amount of coupons used by buyers.
Update campaign
To update the campaign you only need to send the fields you want to modify. The only mandatory field is promotion_type, which must always be present.
Fields that can be updated:
- name
- start_date
- finish_date
- budget
- fixed_amount: only for the subtype FIXED_AMOUNT.
- fixed_percentage: only for the subtype FIXED_PERCENTAGE.
- min_purchase_amount
- max_purchase_amount: only for the subtype FIXED_PERCENTAGE.
Example:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?app_version=v2
{
"promotion_type": "SELLER_COUPON_CAMPAIGN",
"name": "test_coupon_modified",
"start_date": "2023-10-19T00:00:00",
"finish_date": "2023-11-05T00:00:00",
"fixed_percentage": 11,
"min_purchase_amount": 1100,
"max_purchase_amount": 270,
"budget": 20000
}
Response:
{
"id": "C-MLB1234",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_AMOUNT",
"fixed_percentage": 11,
"min_purchase_amount": 1100,
"max_purchase_amount": 270,
"status": "pending",
"start_date": "2023-10-19T00:00:00Z",
"finish_date": "2023-11-05T00:00:00Z",
"name": "test_coupon_modified",
"redeems_per_user": 1,
"budget": 20000,
"remaining_budget": 20000,
"used_coupons": 0
}
Remove campaign
To remove a seller coupon campaign, run this request:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=SELLER_COUPON_CAMPAIGN&app_version=v2
Example:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB1234?promotion_type=SELLER_COUPON_CAMPAIGN&app_version=v2
Response: Status 200 OK
Check campaign details
For seller coupon campaigns there are two subtypes and the option of having or not having the coupon code:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB300?promotion_type=SELLER_COUPON_CAMPAIGN&app_version=v2
Response sub_type FIXED_AMOUNT with coupon code:
{
"id": "C-MLB1082",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_AMOUNT",
"fixed_amount": 10,
"min_purchase_amount": 100,
"max_purchase_amount": 200,
"status": "started",
"start_date": "2023-09-14T03:00:00Z",
"finish_date": "2023-10-01T02:59:59Z",
"name": "test_coupon_004",
"coupon_code": "NICKNCCODE004",
"redeems_per_user": 1,
"budget": 1000,
"remaining_budget": 1000,
"used_coupons": 0
}
Response sub_type FIXED_AMOUNT without coupon code:
{
"id": "C-MLB1079",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_AMOUNT",
"fixed_amount": 50,
"min_purchase_amount": 500,
"max_purchase_amount": 1000,
"status": "started",
"start_date": "2023-09-14T03:00:00Z",
"finish_date": "2023-10-01T02:59:59Z",
"name": "test_coupon_002",
"redeems_per_user": 1,
"budget": 1000,
"remaining_budget": 1000,
"used_coupons": 0
}
Response sub_type FIXED_PERCENTAGE with coupon code:
{
"id": "C-MLB1081",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_PERCENTAGE",
"fixed_percentage": 5,
"min_purchase_amount": 10,
"max_purchase_amount": 100,
"status": "started",
"start_date": "2023-09-14T03:00:00Z",
"finish_date": "2023-10-01T02:59:59Z",
"name": "test_coupon_003",
"coupon_code": "NICKNCODE003",
"redeems_per_user": 1,
"budget": 1000,
"remaining_budget": 1000,
"used_coupons": 0
}
Response sub_type FIXED_PERCENTAGE without coupon code:
{
"id": "C-MLB1067",
"type": "SELLER_COUPON_CAMPAIGN",
"sub_type": "FIXED_PERCENTAGE",
"fixed_percentage": 5,
"min_purchase_amount": 10,
"max_purchase_amount": 100,
"status": "started",
"start_date": "2023-09-14T03:00:00Z",
"finish_date": "2023-10-01T02:59:59Z",
"name": "test_coupon_001",
"redeems_per_user": 1,
"budget": 1000,
"remaining_budget": 1000,
"used_coupons": 0
}
Statuses
These are the different statuses that a seller's coupon campaign can go through.
Status | Description |
---|---|
pending | Approved promotion that didn’t start yet. |
started | Active promotion. |
finished | Promotion ended. |
deleted | Campaign removed. |
Check items in a campaign
To find out which items are part of a seller's coupon campaign perform the following query:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?promotion_type=SELLER_COUPON_CAMPAIGN&app_version=v2'
Response sub_type FIXED_AMOUNT:
{
"results": [
{
"id": "MLB4096076774",
"status": "candidate",
"price": 0,
"original_price": 3346,
"fixed_amount": 200,
"start_date": "2023-12-07T00:00:00",
"end_date": "2024-01-06T23:59:59",
"sub_type": "FIXED_AMOUNT"
}
],
"paging": {
"total": 1,
"limit": 50
}
}
Response sub_type FIXED_PERCENTAGE:
{
"results": [
{
"id": "MLB4096076774",
"status": "candidate",
"price": 0,
"original_price": 3346,
"fixed_percentage": 15,
"start_date": "2023-12-07T00:00:00",
"end_date": "2024-01-06T23:59:59",
"sub_type": "FIXED_PERCENTAGE"
}
],
"paging": {
"total": 1,
"limit": 50
}
}
Status of the items
These are the possible statuses that items can have within this type of campaign.
Status | Description |
---|---|
candidated | Candidate item to participate in the promotion. |
pending | Item with approved and scheduled promotion. |
started | Active item in the campaign. |
finished | Item removed from the campaign. |
Indicate items for a campaign
Once you have candidate items to participate in this campaign, you can indicate which products you want to include. No prices are sent, since it is a discount coupon that is applied at the checkout of the buyer's purchase.
Example sub_type FIXED_PERCENTAGE:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
"promotion_id":"C-MLB1081",
"promotion_type":"SELLER_COUPON_CAMPAIGN"
}'
https://api.mercadolibre.com/seller-promotions/items/MLB123456789?app_version=v2
Response:
{
"price": 0,
"original_price": 0,
"promotion_name": "test_coupon_001",
"fixed_percentage": 5
}
Prices are always 0 because the offer does not have a price, it's a discount that is applied at checkout.
Remove item from the campaign
To remove a seller coupon campaign, perform this request:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=SELLER_COUPON_CAMPAIGN&promotion_id=$PROMOTION_ID&app_version=v2
Example:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLB123456789?promotion_type=SELLER_COUPON_CAMPAIGN&promotion_id=C-MLB1081&app_version=v2
Response: Status 200 OK
Validation errors
400 Bad Request
Error message | Description |
---|---|
start_date cannot be earlier than today | The start date of the campaign cannot be earlier than today.. |
finish_date cannot be earlier than start_date | The end date cannot be earlier than the start date of the campaign. |
maximum period cannot exceed the allowed | When an attempt is made to update any date (start date or end date or both), and the new period between the two exceeds the allowed 31 days. |
minimum period cannot be lower than allowed | When an attempt is made to update any date (start date or end date or both), and the new period between the two is less than the allowed 1 day. |
the field {field} not upgradable | When you want to modify a field that is not allowed when the promotion has the STARTED status. |
the promotion budget cannot be decreased | The budget can only be increased.. |
the name already exists | A coupon campaign with the same name already exists. |
the fixed_percentage is greater than allowed | The maximum percentage allowed is 70%. If you send, for example, fixed_percentage: 71. |
the fixed_percentage is less than allowed | The minimum allowed is 5%. If you send, for example, fixed_percentage: 4. |
The max_purchase_amount should be greater than min value allowed {value} | The value of the max_purchase_amount field must be greater than the minimum allowed. For MLB for example, it is 5. |
The fixed_percentage applied to min purchase amount should be lower than max purchase amount value | The value of the benefit applied to the minimum purchase amount must be less than the value of the maximum reimbursement amount. |
The promotion budget should be greater than max purchase amount value when campaign subtype is fixed percentage | When the budget is less than the maximum reimbursement amount for this subtype. |
The fixed_amount should be greater than min value allowed {value} | The value of the fixed_amount field must be greater than the minimum allowed. For all sites it is 0. |
The fixed_amount should be lower than min purchase amount value | When the value of the fixed_amount field is greater than the value of the min_puchase_amount field. For example, when you want to give a fixed amount discount of 10 but the minimum purchase value for the coupon to apply is 5. |
The min_puchase_amount {value} should be bigger than the min value: {min_value} | When the value of the min_puchase_amount field is less than the minimum percentage calculation allowed using the value of the fixed_amount field. |
The min_puchase_amount {value} should be lower than the max value: {max_value} | When the value of the min_puchase_amount field is greater than the maximum allowed percentage calculation using the value of the fixed_amount field. |
The promotion budget should be greater than benefit value when campaign subtype is fixed amount | When the budget is less than the fixed discount amount for this subtype. |