Developers

Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.

Última actualización 25/09/2024

Promotion Management

Promotions

With the resource /seller-promotions, you can centralize all types of promotions available on the Mercado Shops channel such as boleto (BOLETO), coupon (COUPON), individual discounts (INDIVIDUAL), traditional discounts (TRADITIONAL and MASSIVE), and volume discounts (VOLUME). To start using the promotion center in the channel and create promotions, you only need to have your store created and have items.

Importante:

Para las ofertas por cantidad, un mismo producto puede participar en máximo 5 ofertas por cantidad, sin coincidir en la misma fecha. Si tu ofertas por cantidad (ej.: 2X1) coincide en fechas con una tradicional (ej.: 50% OFF), solo se mostrará al comprador la de mayor beneficio.

Adicional, las promociones masivas individuales (INDIVIDUAL_VOLUME) dejarán de estar disponibles a partir del 14/10/2024 .

Glossary of fields and parameters

Fields	Field Description	Possible field values and their description
name	Name of the promotion.	String
code	Discount code.	String
description	Short description of the discount campaign.	String
discount_type	Type of discount.	The values are percent: percentage and fixed: fixed amount. For massive campaigns, it can have the value by_item. Also, discount_by_quantity, percentage_by_volume, and percentage_by_unit for volume discounts.
status	Promotion status.	The values are active: active and inactive: inactive.
id	Promotion ID.	String
item_id	Publication ID.	It will be visible in individual promotions.
type	Type of campaign the user wants to create.	The values are boleto, coupon, traditional, individual, volume.
target	Product coverage, allows identifying if the campaign applies to all products, selected products, or a list of products.	The values are ALL_PRODUCTS, SELECTED_PRODUCTS, LISTED_PRODUCTS.
shop_id	Store/user identifier.	Integer
value_discount	The value of the discount for the item (this field only applies to the creation of massive campaigns).	Double
discount_type	Type of discount applied to the item (this field only applies to the creation of massive campaigns).	The possible values are fixed_price and percent, discount_by_quantity, percentage_by_unit and percentage_by_volume.
buy_quantity	Number of products that are part of the promotion.	Integer
pay_quantity	Number of products paid for in the promotion.	Integer

Important:

Starting on 10/14/2024, the IDs for different Mshops promotions will change to the format C-{site}{Id}. Example: C-MLA242124. The progressive migration will start with coupon campaigns.

Consult 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

Traditional offer response:

'{
    "id": "TR-496907760-202112031641564156",
    "name": "Traditional Modified 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"
}'

Coupon response:

{
   "id": "10097749",
   "name": "Coupon 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": "This is the coupon description",
   "code": "TESTCODE",
   "use_limit": 1
}

Massive traditional offer response:

{
   "id": "TRM-654461415-202202011726162616",
   "name": "Traditional Kike massive test 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"
}

Quantity offers response:

{
    "results": [
        {
            "id": "DXV-553421365-20230131110752752",
            "name": " DXV TEST 1",
            "status": "ACTIVE",
            "type": "volume",
            "start_date": "2023-02-02T00:00:00.000+00:00",
            "end_date": "2023-03-31T00:00:00.000+00:00",
            "target": "SELECTED_PRODUCTS",
            "discount_type": "percentage_by_unit",
            "value": 20,
            "shop_id": 553421365,
            "buy_quantity": 6
        },
}

Response for 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 promotion that does not belong to the Mshop channel:

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

Parameters

promotion_type: type of promotion to be queried.
promotion_id: ID of the campaign/promotion to be queried.
channel: channel through which we want to query. By default, we will provide marketplace.

Manage listings with promotions

With the /seller-promotions resource, you can manage listings with different promotions for both marketplace listings and Mercado Shops channel listings separately.

Query promotions of a listing

This functionality allows recognizing all promotions that are active on a listing.

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 for traditional discount:

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

Response for volume offer:

{
        "id": "DXV-553421365-20230131110752752",
        "name": " DXV TEST 1",
        "status": "programmed",
        "type": "volume",
        "start_date": "2023-02-01",
        "finish_date": "2023-03-30",
        "target": "SELECTED_PRODUCTS",
        "buy_quantity": 6
    }

Response if the item does not exist:

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

Response if access is denied:

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

Parameters

Query listings by promotion

This functionality allows recognizing all listings 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 Blue 2 Gb Ram"
       },
       {
           "final_price": 1350,
           "id": "MLA897947944",
           "original_price": 1500,
           "title": "Sticker Cards"
       },
       {
           "final_price": 1350,
           "id": "MLA838847599",
           "original_price": 1500,
           "title": "Wallet Perfect for People Like You!"
       }
   ],
   "pagination": {
       "offset": 0,
       "limit": 100,
       "total": 3
   }
}

Response for quantity offers:


{
    "items": [
        {
            "final_price": 591600000,
            "id": "MLA851258051",
            "original_price": 102000000,
            "title": "Smart Tv Tcl L50p8m Led 4k 50  100v/240v"
        },
        {
            "final_price": 116000,
            "id": "MLA1137574968",
            "original_price": 20000,
            "title": "Food Processor"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 50,
        "total": 2
    }
}

Parameters

promotion_id: ID of the campaign/promotion to be queried.
user_id: seller ID whose promotions we want to query.
channel: channel through which we want to query. By default, we will provide marketplace.
limit: limit of the number of listings returned by the query.
offset: number of listings to skip before starting to return listings from the query (pagination).

Add listings 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

Example for 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

Example for 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

Example for quantity offers:

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

Note:

Keep in mind that the value_discount and discount_type fields only apply when adding items to a massive campaign.

Successful response:

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

Parameters

promotion_id: ID of the campaign/promotion to be queried.
channel: the channel where we want to query. By default, we will provide marketplace.
user_id: ID of the seller whose promotions we want to query.

Remove a listing 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:

curl -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

Example for quantity offers:

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

https://api.mercadolibre.com/seller-promotions/users/553421365/promotions/DXV-553421365-20230131110752752/items?channel=mshops

Manage promotions by store:

With the /seller-promotions resource, you can manage different promotions for each Mercado Shops store separately, allowing actions at the store level rather than individually by items.

Expected parameters by campaign type

PROPERTY	BOLETO	COUPON	COUPON-FIXED	TRADITIONAL
Name	Promotion name	Promotion name	Promotion name	Promotion name
Discount_type	PERCENT	PERCENT	FIXED	PERCENT
Value	Promotion value	Promotion value	Promotion value (fixed price)	Promotion value
Type	boleto	coupon	coupon	traditional
Start_date	Start date	Start date	Start date	Start date
End_date	End date	End date	End date	End date
Target				ALL_PRODUCTS
min_payment_amount		Minimum amount	Minimum amount
Code		Code assigned to the promotion	Code assigned to the promotion
one_coupon_per_user			true or false
items
Item_id
campaign_item_type				TRADITIONAL
buy_quantity
pay_quantity

PROPERTY	TRADITIONAL-ITEM	TRADITIONAL-MASSIVE	INDIVIDUAL	VOLUME
Name	Promotion name	Promotion name	Promotion name	Promotion name
Discount type	PERCENT	BY_ITEM		discount_by_quantity, percentage_by_volume, percentage_by_unit
Value	Promotion value		Promotion value	Promotion value (Except for discount_by_quantity)
Type	traditional	traditional	individual	volume
Start date	Start date	Start date	Start date	Start date
End date	End date	End date	End date	End date
Target	SELECTED_PRODUCTS	LISTED_PRODUCTS		SELECTED_PRODUCTS
Minimum payment amount
Code
One coupon per use
Items	List of items in the promotion
Item_id			Item ID	Item ID
Campaign item type	TRADITIONAL	MASSIVE
Buy quantity				Number of items eligible for the promotion (between 2 and 10 units)
Pay quantity				Number of items to be paid for (Less than the quantity taken)

Consult promotions by store

This resource allows you to check the active promotions of a store.

Note:

Starting from 14/10/2024, only promotions covering multiple products will be displayed, meaning campaigns with type "individual" will not be listed.

Call:

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 Modified 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"
       },
       {
           "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": "10048392",
           "name": "Test uses",
           "status": "ACTIVE",
           "type": "coupon",
           "start_date": "2022-01-28T17:57:00.000+00:00",
           "end_date": "2022-10-29T05:00:00.000+00:00",
           "target": "ALL_PRODUCTS",
           "discount_type": "percent",
           "value": 20,
           "shop_id": 654461415,
           "description": "Uses",
           "code": "USOSCUPON",
           "use_limit": 1
       },
       {
           "id": "TRM-654461415-202201270318521852",
           "name": "Traditional Massive",
           "status": "ACTIVE",
           "type": "traditional",
           "start_date": "2120-01-18T00: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 with invalid user_id:

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

Parameters

user_id: ID of the seller whose promotions we want to check in their store.
channel: channel in which we want to query. By default, we will provide marketplace.

Create promotions

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

Call:

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

Depending on the type of promotion you publish, the POST can include attributes like: name, discount_type, value, campaign_type, start_date, end_date, target, description, code, item_id, min_payment_amount, items, action, status, buy_quantity..

Coupon example:


curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Promo Test Name",
"code": "TEST3",
"description": "Coupon description",
"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 created coupon promotion:

{
    "id": "10029844",
    "name": "Promo Test Name",
    "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": "Coupon description",
    "code": "TEST3"
}

Important:

Starting on 14/10/12, volume promotion configurations will be restricted. The new configurations are as follows:

Buy "N" pay "M":

2 <= N <= 10
1 <= M < N

Buying "N", "M"% discount on the purchase:

2 <= N <= 10
% discount restricted to: 5, 10, 15, 20, 25, 30, 40, 50, 60, 70, and 80

"M"% discount on the N-th unit:

2 <= N <= 10
% discount restricted to: 5, 10, 15, 20, 25, 30, 40, 50, 60, 70, and 80

Example of quantity-based offer, on all units (20% off on the 6th unit):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
 "name": " DXV TEST 1",
 "discount_type": "percentage_by_unit",
 "value": 20.0,
 "start_date": "2023-02-02T00:00:00.000+0000",
 "end_date": "2023-03-31T00:00:00.000+0000",
 "type": "volume",
 "target": "SELECTED_PRODUCTS",
 "buy_quantity": 6,
 "status": "ACTIVE"
}'
https://api.mercadolibre.com/seller-promotions/users/805246766?channel=mshops
}

Response of the created promotion:

{
    "id": "DXV-553421365-20230131110752752",
    "name": " DXV TEST 1",
    "status": "ACTIVE",
    "type": "volume",
    "start_date": "2023-02-02T00:00:00.000+00:00",
    "end_date": "2023-03-31T00:00:00.000+00:00",
    "target": "SELECTED_PRODUCTS",
    "discount_type": "percentage_by_unit",
    "value": 20,
    "shop_id": 805246766,
    "buy_quantity": 6
}

Example of quantity-based offer on a single unit (20% off when buying 6 units):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
"name": " DXV TEST 2",
"discount_type": "percentage_by_volume",
"value": 20.0,
"start_date": "2023-04-02T00:00:00.000+0000",
"end_date": "2023-04-31T00:00:00.000+0000",
"type": "ivolume",
"target": "SELECTED_PRODUCTS",
"buy_quantity": 6,
"status": "ACTIVE"
}
https://api.mercadolibre.com/seller-promotions/users/805246766?channel=mshops

Successful response:

{
    "id": "DXV-623329318-20240924115208528",
    "name": " DXV TEST 2",
    "status": "ACTIVE",
    "type": "volume",
    "start_date": "2023-04-02T00:00:00.000+00:00",
    "end_date": "2023-04-31T00:00:00.000+00:00",
    "target": "SELECTED_PRODUCTS",
    "discount_type": "percentage_by_volume",
    "value": 20,
    "shop_id": 805246766,
    "buy_quantity": 6
}

Example of quantity-based offers with free units (2x1)

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
"name": " DXV TEST 3 2x1",
"discount_type": "discount_by_quantity",
"start_date": "2023-05-02T00:00:00.000+0000",
"end_date": "2023-05-31T00:00:00.000+0000",
"type": "volume",
"target": "SELECTED_PRODUCTS",
"buy_quantity": 2,
"pay_quantity": 1,
"status": "ACTIVE"
}
https://api.mercadolibre.com/seller-promotions/users/805246766?channel=mshops

Successful response:

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

Keep in mind that you cannot have more than one quantity-based offer at the same time on a product, whether on exact dates or overlapping days.
Additionally, the offer percentages can range between (5% and 95%), and the number of units applicable to the promotions can range between (2 and 10 units).

Parameters

user_id: ID of the seller whose promotions we want to check in their store.
channel: channel in which we want to query. By default, we will provide marketplace.

Modify promotion by store

With this resource, changes can be made to the promotions of a store. For this, it is necessary to have the store ID and the ID of the promotion that we want to modify.

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?channel=$CHANNEL

Clarifications

For coupon and coupon fixed, the following properties can be changed:

name
value (as long as it is scheduled)
start_date (as long as it is scheduled)
end_date (as long as it is scheduled)
description
min_payment_amount (as long as it is scheduled)

When making a modification, at least the following data must be sent (even if only the properties mentioned above can be modified):

name
discount_type
value
type
start_date
end_date
code
min_payment_amount

Fixed coupon example:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Promo Name 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": "TEST3",
"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": "Promo Name 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": "TEST3",
"min_payment_amount": 1
}'
https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/TR-496907760-202112031641564156?channel=mshops

Clarifications

For boleto, the following properties can be changed:

name
value (as long as it is scheduled)
start_date (as long as it is scheduled)
end_date (as long as it is scheduled)

When making a modification, at least the following data must be sent (even if only the properties mentioned above can be modified):

name
value
type
start_date
end_date

Example of boleto:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"name": "Promo Name 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

Clarifications

For traditional campaigns (ALL_PRODUCTS), the following properties can be changed:

name
start_date (as long as it is scheduled)
end_date (as long as it is scheduled)

When making a modification, at least the following data must be sent (even if only the properties mentioned above can be modified):

name
value
type
start_date
end_date
target

Example of traditional ALL_PRODUCTS:

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: ID of the seller whose promotions we want to check in their store.
channel: channel in which we want to query. By default, we will provide marketplace.
promotion_id: ID of the campaign/promotion to be queried.

Remove promotion 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.

Manage coupon report

Through the /coupons resource, you can obtain a report of the coupons active in the store, thus allowing you to have visibility of the coupons created within a specific time range.

Parameters:

You can obtain the report of available coupons in a store by making a query with the following parameters.

Name	Type	Description	Example
Seller_id	String	ID of the seller/store	594239600
Start_date	String	Start date of the report in the format yyyy-MM-dd	2024-07-09
End_date	String	End date of the report in the format yyyy-MM-dd	2024-07-12

Request:


curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/$SELLER_ID/coupons?start_date=$START_DATE&end_date=$END_DATE&channel=mshops

Example:


curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/123/coupons?start_date=2024-04-01&end_date=2024-04-30

Successful coupons response


{
  "start_date": "2024-04-01",
  "end_date": "2024-04-30",
  "coupons": [
    {
      "id": 10996528,
      "campaign_name": "Cupon test",
      "coupon_code": "TESTCUPON",
      "used_coupon": 0,
      "total_sales": "$ 0",
      "total_discount": "$ 0",
      "created_date": "2024-03-30",
      "start_date": "2024-03-30",
      "end_date": "2024-05-14",
      "status": "active"
    },
    {
      "id": 10993413,
      "campaign_name": "Cupon test 2",
      "coupon_code": "TESTCUPON2",
      "used_coupon": 0,
      "total_sales": "$ 0",
      "total_discount": "$ 0",
      "created_date": "2024-03-24",
      "start_date": "2024-03-28",
      "end_date": "2024-04-30",
      "status": "active"
    },
    {
      "id": 10993343,
      "campaign_name": "Cupon test 3",
      "coupon_code": "TESTCUPON2",
      "used_coupon": 0,
      "total_sales": "$ 0",
      "total_discount": "$ 0",
      "created_date": "2024-03-24",
      "start_date": "2024-03-28",
      "end_date": "2024-04-13",
      "status": "inactive"
    }
  ]
}

Successful coupons response, but no coupons within the selected date range:


{
  "start_date": "2024-04-01",
  "end_date": "2024-04-30",
  "coupons": []
}

Coupons retrieval without start date and/or end date:


Request-code: 400
{
  "start and end dates must not be empty"
}

Response fields:

The response from a GET to the /coupons resource will provide the following parameters

results:
- id: promotion/coupon id
- campaign_name: Promotion/coupon name
- coupon_code: Code assigned to redeem the coupon
- used_coupon: Boolean that lets me know if the coupon was used or not
- total_sales: Total sales generated with the products sold that applied the coupon
- total_discount: Total discount generated with the products sold that applied the coupon
- created_date: Promotion/coupon creation date
- start_date: Promotion/coupon start date
- end_date: Promotion/coupon end date
- status: Promotion status, its values can be active or inactive

Coupons Errors

Retrieval of coupons with incorrect date format



    Request-code: 400
{
    "Start and end dates must be in correct format: yyyy-MM-dd"
}

Error retrieving coupons from a seller



 Request-code: 500
{
}

Error using the access token to obtain coupon information



 Request-code: 401
{
    "code": "unauthorized",
    "message": "invalid access token"
}

Next: Guest users sales.