Deals

Get Campaign Details

Retrieve detailed information about a specific commercial campaign (Deal) that a seller has been invited to participate in. Use this endpoint to obtain the campaign's status, dates, and general configuration before submitting items.

Request:

curl -X GET 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$PROMOTION_ID?promotion_type=DEAL&user_id=$USER_ID' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: $CLIENT_ID' \
-H 'X-Caller-Id: $CALLER_ID'

Example:

curl -X GET 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13757022?promotion_type=DEAL&user_id=1317418851' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: 1317417907' \
-H 'X-Caller-Id: 1317417907'

Response:

{
    "id": "P-MLM13757022",
    "type": "DEAL",
    "status": "started",
    "start_date": "2024-01-29T06:00:00Z",
    "finish_date": "2024-02-12T06:00:00Z",
    "deadline_date": "2024-02-11T06:00:00Z",
    "name": "Ano nuevo chino"
}

Response fields

• id: unique identifier of the campaign (promotion).
• type: type of promotion. For commercial campaigns, this value is DEAL.
• status: current status of the campaign. See the status table below.
• start_date: date and time when the campaign starts, in ISO 8601 format.
• finish_date: date and time when the campaign ends, in ISO 8601 format.
• deadline_date: last date and time to submit items to the campaign, in ISO 8601 format.
• name: name of the campaign.

Campaign Status

Find below the different traditional campaign statuses:

Status	Description
pending	Promotion approved but not yet started.
started	Active promotion.
finished	Finished promotion.

Check Campaign Items

Retrieve all items included in a specific campaign. Use this endpoint to view which items are eligible (candidates) or already participating in a Deal, along with their pricing information.

Request:

curl -X GET 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/$PROMOTION_ID/items?user_id=$USER_ID' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: $CLIENT_ID' \
-H 'X-Caller-Id: $CALLER_ID'

Example:

curl -X GET 'https://api.mercadolibre.com/marketplace/seller-promotions/promotions/P-MLM13757022/items?user_id=1317418851' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: 1317417907' \
-H 'X-Caller-Id: 1317417907'

Response:

{
    "results": [
        {
            "id": "MLM2760672650",
            "status": "candidate",
            "price": 35,
            "original_price": 0,
            "currency_id": "USD",
            "min_discounted_price": 10.5
        },
        {
            "id": "MLM2183693560",
            "status": "started",
            "price": 65.8,
            "original_price": 70,
            "currency_id": "USD"
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 50,
        "total": 19,
        "searchAfter": ""
    }
}

Response fields

• results: list of items in the campaign.
• results[].id: item ID.
• results[].status: item status in the campaign. See the item status table below.
• results[].price: current item price. For candidate items, this is the original price. For started items, this is the promotional price.
• results[].original_price: item's original price without promotion. Value is 0 for candidate items.
• results[].currency_id: currency code (e.g., USD).
• results[].min_discounted_price: minimum allowed price for the item in this campaign. Only present for candidate items.
• paging: pagination information.
• paging.offset: current offset position.
• paging.limit: maximum number of items per page.
• paging.total: total number of items in the campaign.
• paging.searchAfter: cursor for pagination. Use this value in the search_after parameter to get the next page of results.

Item status

The table below shows the possible item status in this type of campaign.

Status	Description
candidate	Item eligible for deal.
pending	Item sent to deal but not started.
started	Item with deal already started.
finished	Item deleted from campaign.

Submit an Item to a Campaign

Submit an item to participate in a commercial campaign. You must send the item ID, the desired promotional price, and the marketplace user ID of the country where you want to participate.

Request:

curl -X POST 'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: $CLIENT_ID' \
-H 'X-Caller-Id: $CALLER_ID' \
-H 'Content-Type: application/json' \
-d '{
    "promotion_id": "$PROMOTION_ID",
    "deal_price": $DEAL_PRICE,
    "promotion_type": "DEAL"
}'

Example:

curl -X POST 'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2760672650?user_id=1317418851' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: 1317417907' \
-H 'X-Caller-Id: 1317417907' \
-H 'Content-Type: application/json' \
-d '{
    "promotion_id": "P-MLM13757022",
    "deal_price": 15,
    "promotion_type": "DEAL"
}'

The field deal_price should be in US dollars.

Response:

{
    "price": 15,
    "original_price": 35,
    "currency_id": "USD"
}

The fields price and original_price are expressed in US dollars.

Request body parameters

• promotion_id: promotion identification code (e.g., P-MLM13757022).
• deal_price: item price in the promotion, in US dollars.
• top_deal_price: (optional) item price for best buyers with Mercado Puntos level 3 to 6.
• promotion_type: type of promotion. Use DEAL for commercial campaigns.

Response fields

• price: the promotional price set for the item, in US dollars.
• original_price: the item's original price before the promotion, in US dollars.
• currency_id: currency code (e.g., USD).

Edit a Deal in a Campaign

Update the promotional price of an item already submitted to a campaign. You must send the promotion ID, item ID, and the new desired price, along with the marketplace user ID of the country where the campaign takes place.

Request:

curl -X PUT 'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: $CLIENT_ID' \
-H 'X-Caller-Id: $CALLER_ID' \
-H 'Content-Type: application/json' \
-d '{
    "promotion_id": "$PROMOTION_ID",
    "deal_price": $DEAL_PRICE,
    "promotion_type": "DEAL"
}'

Example:

curl -X PUT 'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2760672650?user_id=1317418851' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: 1317417907' \
-H 'X-Caller-Id: 1317417907' \
-H 'Content-Type: application/json' \
-d '{
    "promotion_id": "P-MLM13757022",
    "deal_price": 14,
    "promotion_type": "DEAL"
}'

The field deal_price should be in US dollars.

Response:

{
    "price": 14,
    "original_price": 35,
    "currency_id": "USD"
}

The fields price and original_price are expressed in US dollars.

Response fields

• price: the updated promotional price for the item, in US dollars.
• original_price: the item's original price before the promotion, in US dollars.
• currency_id: currency code (e.g., USD).

Delete a Deal from a Campaign

Remove an item from a commercial campaign. You must send the item ID, the promotion ID, and the promotion type, along with the marketplace user ID of the site where the campaign is active.

Request:

curl -X DELETE 'https://api.mercadolibre.com/marketplace/seller-promotions/items/$ITEM_ID?user_id=$USER_ID&promotion_type=DEAL&promotion_id=$PROMOTION_ID' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: $CLIENT_ID' \
-H 'X-Caller-Id: $CALLER_ID'

Example:

curl -X DELETE 'https://api.mercadolibre.com/marketplace/seller-promotions/items/MLM2760672650?user_id=1317418851&promotion_type=DEAL&promotion_id=P-MLM13757022' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'version: v2' \
-H 'X-Client-Id: 1317417907' \
-H 'X-Caller-Id: 1317417907'

This method returns a 200 OK status code if the item was successfully removed from the campaign.

Next: Co-Funded Campaigns