Manage promotions

Use the /seller-promotions resource to centralize all types available promotions: Sales events (DEAL), Regular deal (PRICE_DISCOUNT), Deal of the day (DOD), Lightning deal (LIGHTNING), Volume discount campaigns (VOLUME), Co-funded campaigns (MARKETPLACE CAMPAIGN) and Pre-negotiated discount per item (PRE_NEGOTIATED). This is apart from the new types of deals that we will make available.
See more information about a What types of deals you can offer and How to offer a discount.

Contents

→Promotion characteristics
→Sales promotions for the seller
→Promotion details
→Items included in a promotion
→Item promotions
→Modify items


Promotion characteristics

Campaign type Name Price definition Price suggestion MELI Bonus money Stock to participate Deadline Approval
Sales events DEAL User defines No No No Yes Yes
Deals of the day DOD User accepts Yes No Yes, informative No No
Lightning deals LIGHTNING User defines Yes No Yes, required No No
Volume discount VOLUME User accepts No Yes No Yes No
Co-funded MARKETPLACE CAMPAIGN User accepts No Yes No Yes No
Pre-negotiated discount per item PRE_NEGOTIATED User agrees and accepts No Yes No Yes No


Sales promotions for the seller

A user can have more than one as well as different types of invitations.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/users/$USER_ID

Response:

{
    "results": [
        {
            "id": "LGH-MLM1000",
            "type": "LIGHTNING",
            "status": "started",
            "start_date": "2000-01-01T00:00:00.000Z",
            "finish_date": ""
        },
        {
            "id": "DOD-MLM1000",
            "type": "DOD",
            "status": "started",
            "start_date": "2000-01-01T00:00:00.000Z",
            "finish_date": ""
        },
       {
           "id": "MLM1907",
           "type": "DEAL",
           "status": "test",
           "start_date": "2020-01-31T07:59:00Z",
           "finish_date": "2022-11-01T16:59:00Z",
           "deadline_date": "2021-02-01T12:59:00-04:00",
           "name": "Name Deal"
       }
    ],
    "paging": {
        "offset": 0,
        "limit": 50,
        "total": 3
    }
}

Response fields

id: promotion ID code.
type: promotion type (DEAL, PRICE_DISCOUNT, DOD, LIGHTNING).
status: promotion status could be: candidate, pending, started (depending the promotion type).
start_date: promotion start date.
finish_date: promotion finish date.
deadline_date: maximum term to add promotional items.
name: promotion name.
deadline_date: maximum time limit for accepting the invitation to participate in the promotion.


Promotion details

Perform the following query to access the specific details of traditional campaigns, co-funded campaigns, and volume discounts.

Request:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$DEAL_ID?promotion_type=$PROMOTION_TYPE&user_id=$USER_ID

Example:

curl -H 'Authorization: Bearer $ACCESS_TOKEN' -X GET https://api.mercadolibre.com/marketplace/seller-promotions/promotions/MLM1907?promotion_type=DEAL&user_id=523132944

Response:

{
   "id": "MLM1907",
   "type": "DEAL",
   "status": "started",
   "start_date": "2020-01-31T07:59:00Z",
   "finish_date": "2022-11-01T16:59:00Z",
   "deadline_date": "2021-02-01T16:59:00Z",
   "name": "Name Deal"
}

Items included in a promotion

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$DEAL_ID/items?user_id=$USER_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/promotions/LGH-MLM1000/items?user_id=481244699

Response:

{
    "results": [
        {
            "id": "MLM745913661",
            "status": "candidate",
            "price": 26.05,
            "original_price": 0,
            "currency_id": "USD",
            "stock": {
                "min": 10,
                "max": 15
            }
        },
        {
            "id": "MLM755504940",
            "status": "candidate",
            "price": 22.2,
            "original_price": 0,
            "currency_id": "USD",
            "stock": {
                "min": 10,
                "max": 15
            }
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 50,
        "total": 2
    }
}

Item promotions

For DEALS we will return items with status = approved only. We will not approve test campaigns, which will remain with pending_approval, i.e., you will not see the promotion price.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM755504940?user_id=481244699

Resposta:

[
    {
        "id": "3587589-MLM755504940",
        "type": "DOD",
        "status": "pending",
        "start_date": "2021-06-11T00:00:00",
        "finish_date": "2021-06-11T23:59:59.999999999"
    },
    {
        "id": "3668214-MLM755504940",
        "type": "PRICE_DISCOUNT",
        "status": "started",
        "start_date": "2021-06-10T00:00:00",
        "finish_date": "2021-06-11T00:00:00"
    }
]

Modify items

You can change items included in Sales events. To edit Regular deal (PRICE DISCOUNT), Deals of the day (DOD) and Lightning deals (LIGHTNING) delete the promotion and apply it again.



Next: Sales events (DEAL).