Seller campaigns

To offer this discount, it is necessary:

• To have a green reputation.
• The item must have a status equal to active.
• 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 the offer isactive:

• 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".

If the offer is pending:

• The deal_price and top_deal_price can be modified for a higher or lower discount.
• You can add or remove the loyalty discount.

In case you want to remove the loyalty discount, "remove_loyalty": true is sent. In all other cases (do not want to remove, want to add, want to modify, or do not want to act on this price), the field is set to false or not sent at all.

Only the fields to be changed are sent in the body.

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.