Gestión de promociones
Promociones
Glosario de campos y parámetros
Campos | Descripción del campo | Valores posibles para el campo y su descripción |
---|---|---|
name | Nombre de la promoción. | String |
code | Código de descuento. | String |
description | Breve descripción de la campaña de descuento. | String |
discount_type | Tipo de descuento. | Los valores son percent: porcentaje y fixed: valor fijo. Para las masivas puede contar con el valor by_item. |
value | Valor de descuento aplicado | Double |
start_date | Fecha de inicio de la promoción. | Valor de tipo string, p,e: 2021-11-01T00:00:00.000+0000. |
end_date | Fecha de fin de la promoción (debe ser una fecha mayor a start_date). | Valor de tipo string, p,e: 2021-12-01T00:00:00.000+0000. |
min_payment_amount | Valor mínimo de pago para aplicar el descuento. | Double |
campaign_item_type | Este campo aplica para las tradicionales. | Los valores son massive o traditional. |
one_coupon_per_user | Identifica si la campaña tipo cupón permite el uso de cupón más de una vez. | Booleano |
status | Estado de la promoción. | Los valores son active: activo e inactive: inactivo. |
id | Id de la promoción. | String |
item_id | Id de la publicación. | Se podrá visualizar en las promociones individuales. |
type | Tipo de campaña que el usuario quiere crear. | Los valores son boleto, coupon, traditional, individual. |
target | Cobertura de los productos, permite identificar si la campaña aplica para todos los productos, productos seleccionados o aplica para a una lista de productos. | Los valores son ALL_PRODUCTS, SELECTED_PRODUCTS, LISTED_PRODUCTS. |
shop_id | Identificador de la tienda/user. | Integer |
value_discount | Es el valor del descuento para el item (este campo solo aplica para la creación de campañas masivas). | Double |
discount_type | Es el tipo de descuento que se le aplica al ítem (este campo solo aplica para la creación de campañas masivas). | Los valores posibles son fixed_price y percent. |
Consultar promociones
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=$TIPODEPROMOTION&channel=$CHANNEL
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/TR-496907760-202112031641564156?promotion_type=BOLETO&channel=mshops
Respuesta de oferta tradicional:
'{
"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"
}'
Respuesta de cupón:
{
"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
}
Respuesta de oferta tradicional masiva:
{
"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"
}
Respuesta por campaña no encontrada:
'{
"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": []
}'
Respuesta sobre promoción que no pertenece al canal de Mshop:
'{
"message": "Invalid promotion type",
"error": "bad_request",
"status": 400,
"cause": []
}'
Parámetros
promotion_type: tipo de promoción que se va a consultar.
promotion_id: identificador de la campaña/promoción a
consultar.
channel: canal en el cual queremos consultar. Por defecto,
disponibilizaremos marketplace.
Gestionar publicaciones con promociones
Consultar promociones de una publicación
Esta funcionalidad permite reconocer todas las promociones que se encuentran activas en una publicación.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?channel=$CHANNEL
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA932421975?channel=mshops
Respuesta:
{
"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"
}
Respuesta si el ítem no existe:
{
"message": "Item with id MLA082324822 not found",
"error": "not_found",
"status": 404,
"cause": []
}
Respuesta si no cuentan con acceso:
{
"message": "Caller don't have permissions to access this item",
"error": "forbidden",
"status": 403,
"cause": []
}
Parámetros
promotion_type: tipo de promoción que se va a consultar.
promotion_id: identificador de la campaña/promoción a
consultar.
channel: canal en el cual queremos consultar. Por defecto,
disponibilizaremos marketplace.
Consultar publicaciones por promoción
Esta funcionalidad permite reconocer todas las publicaciones asociadas a una promoción.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?channel=$CHANNEL&limit=$LIMIT&offset=$OFFSET
Ejemplo:
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
Respuesta:
{
"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
}
}
Parámetros
promotion_id: identificador de la campaña/promoción a
consultar.
user_id: identificación del vendedor del cual queremos
conocer las promociones que tiene en su tienda.
channel: canal en el cual queremos consultar. Por defecto,
disponibilizaremos marketplace.
limit: límite del número de publicaciones que devuelve la
consulta.
offset: número de publicaciones a omitir antes de comenzar a
devolver las publicaciones desde la consulta (paginación).
Agregar publicaciones a una promoción
Llamada:
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
Ejemplo para promoción tradicional:
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
Ejemplo para promoción masiva:
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
Respuesta satisfactoria:
{
"status": "Success",
"code": "201"
}
Parámetros
promotion_id: identificador de la campaña/promoción a
consultar.
channel: canal en el cual queremos consultar. Por defecto,
disponibilizaremos marketplace.
user_id: identificación del vendedor del cual queremos
conocer las promociones que tiene en su tienda.
Eliminar una publicación de una promoción
Llamada:
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
Ejemplo:
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
Gestionar promociones por tienda
Consultar promociones por tienda
Mediante este recurso se puede consultar las promociones activas de una tienda.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/seller-promotions/users/$USER_ID?channel=$CHANNEL
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/496907760?channel=mshops
Respuesta:
{
"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,
"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": "Prueba usos",
"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": "Usos",
"code": "USOSCUPON",
"use_limit": 1
},
{
"id": "TRM-654461415-202201270318521852",
"name": "Traditional Masivo",
"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"
}
]
}
Respuesta con user_id inválido:
{
"message": "Caller don't have permissions to access this user",
"error": "forbidden",
"status": 403,
"cause": []
}
Parámetros
user_id: identificación del vendedor del cual queremos
conocer las promociones que tiene en su tienda.
channel: canal en el cual queremos consultar. Por defecto,
disponibilizaremos marketplace.
Crear promoción por tienda
Mediante el siguiente recurso se puede crear una promoción para la tienda completa, por lo que se aplicará a todos los ítems que se encuentren activos en la misma.
Llamada:
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
Depende el tipo de promoción que publiques, el POST puede tener atributos como: name, discount_type, value, campaign_type, start_date, end_date, target, description, code, item_id, min_payment_amount, items, action.
Ejemplo:
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
Respuesta de la promoción creada:
{
"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"
}
Parámetros
user_id: identificación del vendedor del cual queremos
conocer las promociones que tiene en su tienda.
channel: canal en el cual queremos consultar. Por defecto,
disponibilizaremos marketplace.
Parámetros esperados por tipo de campaña
PROPIEDAD | BOLETO | COUPON | COUPON-FIXED | TRADITIONAL | TRADITIONAL-ITEM | TRADITIONAL-MASIVO | INDIVIDUAL |
---|---|---|---|---|---|---|---|
Name | Nombre de la promoción | Nombre de la promoción | Nombre de la promoción | Nombre de la promoción | Nombre de la promoción | Nombre de la promoción | |
Discount_type | PERCENT | PERCENT | FIXED | PERCENT | PERCENT | BY_ITEM | |
Value | Valor de la promoción | Valor de la promoción | Valor de la promoción (precio fijo) | Valor de la promoción | Valor de la promoción | Valor de la promoción | |
type | boleto | coupon | coupon | traditional | traditional | traditional | individual |
start_date | Fecha inicio | Fecha inicio | Fecha inicio | Fecha inicio | Fecha inicio | Fecha inicio | Fecha inicio |
end_date | Fecha final | Fecha final | Fecha final | Fecha final | Fecha final | Fecha final | Fecha final |
target | ALL_PRODUCTS | SELECTED_PRODUCTS | LISTED_PRODUCTS | ||||
min_payment_amount | Monto mínimo | Monto mínimo | |||||
Code | Código asignado a la promoción | Código asignado a la promoción | |||||
one_coupon_per_user | true o false | ||||||
items | Lista de items en la promoción | ||||||
Item_id | Id del item | ||||||
campaign_item_type | TRADITIONAL | TRADITIONAL | MASSIVE |
Modificar promoción por tienda
Mediante este recurso se podrán realizar cambios en las promociones de una tienda. Para esto es necesario contar con el ID de la tienda y el ID de la promoción que queremos modificar.
Llamada:
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
Aclaraciones
Para coupon y coupon fixed se pueden cambiar las siguientes propiedades:
- name
- value (siempre y cuando esté programada)
- start_date (siempre y cuando esté programada)
- end_date (siempre y cuando esté programada)
- Description
- min Payment Amount (siempre y cuando esté programada)
Al realizar una modificación se deben enviar al menos los siguientes datos (así solo se puedan modificar las propiedades antes mencionadas):
- name
- discount_type
- value
- type
- start_date
- end_date
- start_date
- code
- min_payment_amount
Ejemplo de coupon fixed:
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
Ejemplo de coupon:
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
Aclaraciones
Para boleto se puede cambiar las siguientes propiedades:
- name
- value (siempre y cuando esté programada)
- start_date (siempre y cuando esté programada)
- end_date (siempre y cuando esté programada)
Al realizar una modificación se deben enviar al menos los siguientes datos (así solo se puedan modificar las propiedades antes mencionadas):
- name
- value
- type
- start_date
- end_date
Ejemplo de boleto:
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
Aclaraciones
Para tradicionales (ALL_PRODUCTS) se puede cambiar las siguientes propiedades:
- name
- start_date (siempre y cuando esté programada)
- end_date (siempre y cuando esté programada)
Al realizar una modificación se deben enviar al menos los siguientes datos (así solo se puedan modificar las propiedades antes mencionadas):
- name
- value
- type
- start_date
- end_date
- target
Ejemplo de tradicional 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
Respuesta con algún parámetro incorrecto:
{
"message": "type mismatch for key [target]",
"error": "bad_request",
"status": 400,
"cause": []
}
Parámetros
user_id: identificación del vendedor del cual queremos
conocer las promociones que tiene en su tienda.
channel: canal en el cual queremos consultar. Por defecto,
disponibilizaremos marketplace.
promotion_id: identificador de la campaña/promoción a
consultar.
Eliminar promoción por tienda
Llamada:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/$USER_ID/promotions/$PROMOTION_ID?channel=$CHANNEL
Ejemplo:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/496907760/promotions/INDIVIDUAL-MLA930546840-2021110811090191?channel=mshops
Parámetros
user_id: identificación del vendedor del cual queremos
conocer las promociones que tiene en su tienda.
channel: canal en el cual queremos consultar. Por defecto,
disponibilizaremos marketplace.
promotion_id: identificador de la campaña/promoción a
consultar.
Siguiente: Ventas de usuarios invitados.