Seller Coupon Campaigns

To offer this discount you need:

• Have green reputation.
• The item must have active status.
• Condition must be new.
• The item's listing type cannot be free.

These are the same criteria for an item to participate in an individual discount campaign, meaning if the item is a candidate for this campaign, it automatically also meets the criteria to participate in a seller coupon campaign.

Create campaign

There are two types of coupon campaigns (with code or without code), but there are also two sub_types: FIXED_PERCENTAGE and FIXED_AMOUNT.

FIXED_AMOUNT Is the fixed discount amount, regardless of the total accumulated price of the items participating in this campaign in the buyer's cart.

FIXED_PERCENTAGE Is the fixed discount percentage, and is dependent on the total accumulated price of the items participating in this campaign in the buyer's cart.

To create a seller coupon campaign, make the following request:

"sub_type": "FIXED_AMOUNT" example 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
}

"sub_type": "FIXED_AMOUNT" example 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
      }

"sub_type": "FIXED_PERCENTAGE" example 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
      }

"sub_type": "FIXED_PERCENTAGE" example 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 (Required): Type of campaign to create, in this case SELLER_COUPON_CAMPAIGN.
• name (Required): Campaign name (only the seller will see it, the buyer will not see it).
• sub_type (Required): Campaign subtype to create. For seller coupon campaigns, the allowed subtypes are FIXED_PERCENTAGE and FIXED_AMOUNT.
• fixed_percentage: Discount percentage of the promotion. Only required for the FIXED_PERCENTAGE subtype.
• fixed_amount: Discount amount of the promotion. Only required for the FIXED_AMOUNT subtype.
• min_purchase_amount (Required): Minimum purchase amount for the coupon to apply.
• max_purchase_amount: Maximum refund amount for the total purchase value to which the coupon was applied. Only required for FIXED_PERCENTAGE subtype.
• start_date (Required): Campaign start date in local format. The beginning of the day will always be taken as the start time.
• finish_date (Required): Campaign end date in local format. The end of the day will always be taken as the end time.
• partial_coupon_code: Partial coupon code. Optional. Only buyers who have this code can use it for their purchase and the final value of this field will be composed of the first five characters of the seller's nickname concatenated to the value sent (Maximum 10 characters). If this field is not sent, all buyers who see the seller's listings can use this coupon.
• budget (Required): Budget allocated to the campaign. Once exhausted, 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
}

Response fields

• id: Campaign identifier with format C-{siteId}XXXXX. Example: "C-MLB1234"
• type: Campaign type (SELLER_COUPON_CAMPAIGN).
• sub_type: Campaign subtype (FIXED_AMOUNT or FIXED_PERCENTAGE).
• fixed_percentage: Discount percentage value. Returned whenever the campaign is of FIXED_PERCENTAGE subtype.
• fixed_amount: Discount amount value. Returned whenever the campaign is of FIXED_AMOUNT subtype.
• min_purchase_amount: Minimum purchase amount.
• max_purchase_amount: Maximum refund amount. Returned whenever the campaign is of FIXED_PERCENTAGE subtype.
• 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 seller's nickname is NICKNAME1234, the coupon_code will be NICKN + the code completed by the user.
• redeems_per_user: Number of times a user can use the coupon from this campaign. Always 1, the buyer can only use the coupon once.
• budget: Budget allocated to the campaign, 100% paid by the seller.
• remaining_budget: Remaining campaign budget.
• used_coupons: Total number of coupons used by buyers.

Update campaign

To update the campaign, only the fields you want to modify should be sent. The only required field is promotion_type, which must always be present.

Fields that can be updated:

• name
• start_date
• finish_date
• budget
• fixed_amount: Only for FIXED_AMOUNT subtype.
• fixed_percentage: Only for FIXED_PERCENTAGE subtype.
• min_purchase_amount
• max_purchase_amount: Only for FIXED_PERCENTAGE subtype.

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
    }

Delete campaign

To delete a seller coupon campaign, make 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

Query campaign details

For seller coupon campaigns there are two subtypes and the option to have or not have a 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 coupon campaign can go through.

Status	Description
pending	Approved promotion that has not yet started.
started	Active promotion.
finished	Finished promotion.
deleted	Deleted campaign.

Query items in a campaign

To find out which items are part of a seller coupon campaign, make the following request:

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
             }
          }

Item statuses

These are the possible statuses that items can have within this type of campaign.

Status	Description
candidate	Candidate item to participate in the promotion.
pending	Item with approved and scheduled promotion.
started	Item active in the campaign.
finished	Item removed from the campaign.

Add items to 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, as it is a discount coupon that is applied at the buyer's purchase checkout.

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 has no price, but rather it is a discount that is applied at the purchase checkout.

Delete item from campaign

To delete a seller campaign, make 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 campaign start date cannot be earlier than today.
finish_date cannot be earlier than start_date	The end date cannot be earlier than the campaign start date.
maximum period cannot exceed the allowed	When trying to update any date (start or end or both), and the new period between them exceeds the allowed 31 days.
minimum period cannot be lower than allowed	When trying to update any date (start or end or both), and the new period between them is less than the allowed 1 day.
the field {field} not upgradable	When trying to modify a non-allowed field when the promotion has STARTED status.
the promotion budget cannot be decreased	The budget can only be increased.
the name already exists	A seller coupon campaign with the same name already exists.
the fixed_percentage is greater than allowed	The maximum allowed percentage is 80%. If sent, for example, fixed_percentage: 71.
the fixed_percentage is less than allowed	The minimum allowed is 5%. If sent, for example, fixed_percentage: 4.
The max_purchase_amount should be greater than min value allowed {value}	The max_purchase_amount field value 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 benefit value applied to the minimum purchase amount must be less than the maximum refund amount value.
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 refund amount for this subtype.
The fixed_amount should be greater than min value allowed {value}	The fixed_amount field value 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 fixed_amount field value is greater than the min_purchase_amount field value. For example, when you want to give 10 as a fixed discount amount 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 min_purchase_amount field value is less than the calculation of the minimum allowed percentage using the fixed_amount field value.
The min_puchase_amount {value} should be lower than the max value: {max_value}	When the min_purchase_amount field value is greater than the calculation of the maximum allowed percentage using the fixed_amount field value.
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.