• API Docs
  • Mercado Shops Guide
  • Management of Mercado Shops promotions
Last update 13/06/2022

Management of Mercado Shops promotions




Manage promotions

Mercado Shops´s promotions

Use the /seller-promotions resource to centralize all types of available promotions at Mercado Shops such us boleto (BOLETO), cupón (COUPON), descuentos individuales (INDIVIDUAL), descuentos tradicional (TRADITIONAL and MASSIVE).
You can also create promotions in Mercado Shops, you only need to have your store created and have items, to start using the promotion central in the channel.


Glossary of fields and parameters

Fields Field description Possible values ​​for the field and its description
name Promotion name. String
code Discount code. String
description Short description of the discount campaign. String
discount_type Discount type. “percent” and “fixed”.For the massive ones you can count with the value “by_item”.
value Discount value applied. Double
start_date Promotion star date. String, p,e: "2021-11-01T00:00:00.000+0000".
end_date Promotion end date (must be a date higher to start_date). String, p,e: "2021-12-01T00:00:00.000+0000".
min_payment_amount Minimum payment amount to apply discount. Double
campaign_item_type This field applies to traditional. “massive” our “traditional”
one_coupon_per_user Check if the coupon type campaign allows the use of the coupon more than once. Booleano
status Promotion status. “active” and “inactive”
id Promotion id. String
item_id Publication id. Publication id.
type Type of campaign that the user wants to create. “boleto”, “coupon”, “traditional”, “individual”.
target Coverage of products, identifies whether the campaign applies to all products, selected products or a list of products. “ALL_PRODUCTS”,” SELECTED_PRODUCTS”,”LISTED_PRODUCTS”.
shop_id store/user id. Integer
value_discount It is the value of the discount for the item (this field only applies to the creation of massive campaigns). Double
discount_type It is the type of discount that is applied to the item (this field only applies to the creation of massive campaigns). “fixed_price” and “percent”.

Check promotions

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=$TIPODEPROMOTION&channel=$CHANNEL

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/TR-496907760-202112031641564156?promotion_type=BOLETO&channel=mshops

Response traditional offer:

'{
    "id": "TR-496907760-202112031641564156",
    "name": "Traditional Modificada 3",
    "status": "ACTIVE",
    "type": "TRADITIONAL",
    "start_date": "2120-03-14T00:00:00.000+00:00",
    "end_date": "2120-02-13T00:00:00.000+00:00",
    "target": "SELECTED_PRODUCTS",
    "discount_type": "PERCENT",
    "value": 10,
    "shop_id": 496907780,
    "campaign_item_type": "traditional"
}'

Answer coupon:

{
   "id": "10097749",
   "name": "Cupon OPEN PLATFORM",
   "status": "ACTIVE",
   "type": "coupon",
   "start_date": "2022-10-30T00:00:00.000+00:00",
   "end_date": "2022-10-31T00:00:00.000+00:00",
   "target": "ALL_PRODUCTS",
   "discount_type": "percent",
   "value": 10,
   "shop_id": 654461415,
   "description": "Esta es la descripción del cupon",
   "code": "TESTCODE",
   "use_limit": 1
}

Response traditional massive:

{
   "id": "TRM-654461415-202202011726162616",
   "name": "Traditional Kike masiva prueba 3",
   "status": "ACTIVE",
   "type": "traditional",
   "start_date": "2120-03-14T00:00:00.000+00:00",
   "end_date": "2120-02-13T00:00:00.000+00:00",
   "target": "LISTED_PRODUCTS",
   "discount_type": "by_item",
   "shop_id": 654461415,
   "campaign_item_type": "massive"
}

Response by campaign not found:

'{
    "message": "GET to /shops/635345120/discounts/00006720 returned 404 and {\"status_code\":404,\"code\":\"discount_not_found_exception\",\"message\":\"discount with campaign id 00006720 not found for shop 635345120\",\"stacktrace\":null,\"request_id\":\"2edcb000-aacf-41d4-834e-916e1bd922ac\"}",
    "error": "internal_server_error",
    "status": 500,
    "cause": []
}'

Response for promotions that do not belong to Mercado Shops:

'{
"message": "Invalid promotion type",
"error": "bad_request",
"status": 400,
"cause": []
}'

Parameters

promotion_type: type of promotion to be queried.
promotion_id: Identifier of the campaign/promotion to be queried.
channel: channel in which we want to consult. By default, a marketplace will be available.


Manage publications with promotions

Use the /seller-promotions resource to manage publications with different promotions, for marketplace publications and Mercado Shops channel publications in a differentiated way.


Check promotions of a publication

This functionality allows you to recognize all the promotions that are active in a publication.


Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA932421975?channel=mshops

Response:

{
        "id": "TR-496907760-202112031641564156",
        "name": "Traditional Modificada 3",
        "status": "programmed",
        "type": "traditional",
        "start_date": "2120-03-13",
        "finish_date": "2120-02-12",
        "target": "SELECTED_PRODUCTS"
      "campaign_item_type": "traditional_campaign"
    }

Response if the item does not exist:

{
    "message": "Item with id MLA082324822 not found",
    "error": "not_found",
    "status": 404,
    "cause": []
}

Response if they do not have access:

{
    "message": "Caller don't have permissions to access this item",
    "error": "forbidden",
    "status": 403,
    "cause": []
}

Parameters

promotion_type: type of promotion to be queried.
promotion_id: Identifier of the campaign/promotion to be queried.
channel: channel in which we want to consult. By default, a marketplace will be available.


Check publications by promotion

This feature identifies all the publications associated with a promotion.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?channel=$CHANNEL&limit=$LIMIT&offset=$OFFSET

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/TR-496907760-202112031641564156/items?channel=mshops&limit=100&offset=0

Response:

{
   "items": [
       {
           "final_price": 90000,
           "id": "MLA1123020613",
           "original_price": 100000,
           "title": "Samsung Galaxy A10 32 Gb Azul 2 Gb Ram"
       },
       {
           "final_price": 1350,
           "id": "MLA897947944",
           "original_price": 1500,
           "title": "Sticker Tarjetas"
       },
       {
           "final_price": 1350,
           "id": "MLA838847599",
           "original_price": 1500,
           "title": "Billetera Ideal Para Gente Como Vos!"
       }
   ],
   "pagination": {
       "offset": 0,
       "limit": 100,
       "total": 3
   }
}

Parameters

promotion_id: identifier of the campaign/promotion to be queried. .
user_id: identification of the seller of which we want to know the promotions he has in his store.
channel: channel in which we want to consult. By default, a marketplace will be available.
limit: limit of the number of publications returned by the query.
offset: number of publications to omit before starting to return publications from the query.(pagination)


Add publications to a promotion

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotion/$PROMOTION_ID/items?channel=$CHANNEL

Response traditional promotion:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
    "items": [
        {
            "item_id": "MLA930546850"
        }
    ],
    "action": "add"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotion/10038085/items?channel=mshops

Response massive promotion:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
   "items": [
       {
           "item_id": "MLA1112170643",
           "value_discount":10,
           "discount_type":"PERCENT"
       },
               {
           "item_id": "MLA931566278",
           "value_discount":10,
           "discount_type":"FIXED_PRICE"
       }
   ],
   "action": "add"
}
https://api.mercadolibre.com/seller-promotions/users/496907760/promotion/10038085/items?channel=mshops
Nota:
The value_discount and discount_type fields only apply to add publications for a massive campaign.

Response satisfactory:

{
    "status": "Success",
    "code": "201"
}

Parameters

promotion_id: Identifier of the campaign/promotion to be queried.
channel: channel in which we want to consult. By default, a marketplace will be available. user_id: identificación del vendedor del cual queremos conocer las promociones que tiene en su tienda.


Delete a publication from a promotion

Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID/items?channel=$CHANNEL

Example:

ccurl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"items": [
{
"item_id": "MLA932423847"
}
],
"action": "delete"
}'

https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156/items?channel=mshops

Manage promotions by store

Use the /seller-promotions resource to manage different promotions by each Mercado Shops store in a differentiated way, allows to perform actions at the store level and not individually by items.


Check promotions by store

Check the active promotions by store.


Request:

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

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/496907760?channel=mshops

Response:

{
    "results": [
        {
            "id": "TR-496907760-202112031641564156",
            "name": "Traditional Modificada 3",
            "status": "ACTIVE",
            "type": "TRADITIONAL",
            "start_date": "2120-03-14T00:00:00.000+00:00",
            "end_date": "2120-02-13T00:00:00.000+00:00",
            "target": "SELECTED_PRODUCTS",
            "discount_type": "PERCENT",
            "value": 10,
            "shop_id": 496907780
        },
        {
            "id": "INDIVIDUAL-MLB2038165685-202111021040184018",
            "status": "ACTIVE",
            "type": "INDIVIDUAL",
            "start_date": "2021-12-14T00:00:00.000+00:00",
            "end_date": "2021-12-20T00:00:00.000+00:00",
            "target": "SELECTED_PRODUCTS",
            "discount_type": "PERCENT",
            "value": 5,
            "shop_id": 496907780,
            "item_id": "MLB2038165685"
        },
        {
            "id": "INDIVIDUAL-MLA930546840-20211103163908398",
            "status": "ACTIVE",
            "type": "INDIVIDUAL",
            "start_date": "2021-12-14T00:00:00.000+00:00",
            "end_date": "2021-12-20T00:00:00.000+00:00",
            "target": "SELECTED_PRODUCTS",
            "discount_type": "PERCENT",
            "value": 50,
            "shop_id": 496907780,
            "item_id": "MLA930546840"
        }
    ]
}

Response with invalid User_id:

{
    "message": "Caller don't have permissions to access this user",
    "error": "forbidden",
    "status": 403,
    "cause": []
}

Parameters

user_id: identification of the seller of which we want to know the promotions he has in his store.
channel: channel in which we want to consult. By default, a marketplace will be available.


Create a promotion by store

Using the following resource you can create a promotion for the entire store, so it will be applied to all the items that are active in it.


Request:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d 
{...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID?channel=$CHANNEL

Depends on the type of promotion you publish, the POST can have attributes such as: "name", "discount_type", "value", "campaign_type", "start_date", "end_date", "target", "description", "code", "item_id", "min_payment_amount", "items", "action".

Example:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo Prueba",
"code": "PRUEBA3",
"description": "Descripción cupon",
"discount_type": "fixed",
"value": 50000,
"start_date": "2021-12-01T00:00:00.000+0000",
"end_date": "2021-12-02T00:00:00.000+0000",
"min_payment_amount": 50001,
"max_user_budget": 50000,
"budget": 100000,
"type": "coupon",
"one_coupon_per_user": true,
"status": "active"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760?channel=mshops

Response of the promotion created:

{
    "id": "10029844",
    "name": "Nombre Promo Prueba",
    "status": "ACTIVE",
    "type": "COUPON",
    "start_date": "2021-12-01T00:00:00.000+00:00",
    "target": "ALL_PRODUCTS",
    "discount_type": "FIXED",
    "value": 50000,
    "shop_id": 496907780,
    "description": "Descripcion cupon",
    "code": "PRUEBA3"
}

Parameters:

user_id: user_id: Identification of the seller of which we want to know the promotions he has in his store.
channel: channel in which we want to consult. By default, a marketplace will be available.


Expected parameters by campaign type:

PROPERTY BOLETO COUPON COUPON-FIXED TRADITIONAL TRADITIONAL-ITEM TRADITIONAL-MASIVO INDIVIDUAL
Name Promotion name Promotion name Promotion name Promotion name Promotion name Promotion name
Discount_type PERCENT PERCENT FIXED PERCENT PERCENT BY_ITEM
Value Promotion value Promotion value Promotion value (fixed price) Promotion value Promotion value Promotion value
type boleto coupon coupon traditional traditional traditional individual
start_date Start date Start date Start date Start date Start date Start date Start date
end_date End date End date End date End date End date End date End date
target ALL_PRODUCTS SELECTED_PRODUCTS LISTED_PRODUCTS
min_payment_amount Minimum amount Minimum amount
Code Promotion code Promotion code
one_coupon_per_user true our false
items Promotion items list
Item_id Item ID
campaign_item_type TRADITIONAL TRADITIONAL MASSIVE


Modify promotions by store

This resource can be used to make changes in the promotions of a store. To do this, it is necessary to have the ID of the store and the ID of the promotion to be modified.


Request:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotion/$PROMOTION_ID?channel=$CHANNEL

Details

The following properties can be changed for coupon and fixed coupon:

  • Name
  • Value (As long as it is programmed)
  • start_date (As long as it is programmed)
  • end_date (As long as it is programmed)
  • Description
  • min Payment Amount (As long as it is programmed)

When you make a modification you must send at least the following data (only the properties mentioned above can be modified)

  • Name
  • Discount_type
  • Value
  • Type
  • start_date
  • end_date
  • start_date
  • code
  • min_payment_amount

Coupon fixed example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo 1 fixed",
"discount_type": "fixed",
"value": 3000,
"type": "coupon",
"start_date": "2023-02-08T20:57:00.000+0000",
"end_date": "2023-12-02T00:00:00.000+0000",
"code": "PRUEBA3",
"min_payment_amount": 50005
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Coupon example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre Promo 1 PERCENT",
"discount_type": "percent",
"value": 3000,
"type": "coupon",
"start_date": "2023-02-08T20:57:00.000+0000",
"end_date": "2023-12-02T00:00:00.000+0000",
"code": "PRUEBA3",
"min_payment_amount": 1
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Details

The following properties can be changed for boleto:

  • Name
  • Value (As long as it is programmed)
  • start_date(As long as it is programmed)
  • end_date (As long as it is programmed)

When you make a modification you must send at least the following data (only the properties mentioned above can be modified):

  • Name
  • Value
  • Type
  • start_date
  • end_date

Boleto example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Nombre PROMO 1 BOLETO",
"value": 20,
"type": "boleto",
"start_date": "2022-02-08T20:57:00.000+0000",
"end_date": "2022-12-08T00:00:00.000+0000"
}'

https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Details

For traditional (ALL_PRODUCTS) you can change the following properties:

  • Name
  • start_date (As long as it is programmed)
  • end_date (As long as it is programmed)

When you make a modification you must send at least the following data (only the properties mentioned above can be modified):

  • Name
  • Value
  • Type
  • start_date
  • end_date
  • target

Traditional ALL_PRODUCTS example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Traditional Mod",
"value":10,
"type": "traditional",
"start_date": "2022-02-18T08:00:00.000+0000",
"end_date": "2023-12-13T00:00:00.000+0000",
"target": "ALL_PRODUCTS"
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Response with an incorrect parameter:

{
    "message": "type mismatch for key [target]",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Parameters

user_id: identification of the seller of which we want to know the promotions he has in his store.
channel: channel in which we want to consult. By default, a marketplace will be available.
promotion_id: identifier of the campaign/promotion to be queried.


Delete promotions by store


Request:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID?channel=$CHANNEL

Example:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/INDIVIDUAL-MLA930546840-2021110811090191?channel=mshops

Parameters

user_id: Identification of the seller of which we want to know the promotions he has in his store.
channel: channel in which we want to consult. By default, a marketplace will be available. promotion_id: Identifier of the campaign/promotion to be queried.