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.

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:

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