Developers

Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.

Última actualización 04/01/2024

Seller coupon campaigns

Important:

This campaign is only available for MLB.
As of January 10, 2024, we will remove the old version of the resource of /seller-promotions.
To get the reply with the new version, send the query to app_version=v2. Check the documentation of each campaign to stay up to date with the changes.

Sellers can create their own coupon campaigns. In this type of campaign, the discount is applied to the total value of the sale of the participating products and is cumulative with the active promotion (only one coupon per sale is allowed).
There are two types of coupon campaigns, those that have a coupon code in which only buyers who have this code will have access to the discount, and those that do not have a coupon code in which all buyers who view the listings will have access to this discount. In this case, Mercado Libre will highlight the coupon discount in these listings that participate in the coupon campaign.

Note:

The maximum term for this type of campaign is 31 days.

To offer this discount:

You need to have green reputation.
The item’s status must be equal to active or paused.
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-MLB1",
   "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-MLB1",
   "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-MLB1",
   "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-MLB1",
   "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-MLB123”.
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.

Note:

For the campaigns with a STARTED status, you can only edit the fields:

finish_date
budget: can only be increased
name

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-MLB1",
       "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-MLB1?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.

Important:

It is not possible to modify an item in the campaign, as these are fixed discount amounts or percentages that are connected to the campaign settings.

Remove campaign

To remove a seller coupon campaign, perform 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-MLB1081?promotion_type=SELLER_COUPON_CAMPAIGN&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.