• API Docs
  • Guía para Mercado Shops
  • Gestión de promociones
Última actualización 29/12/2022

Gestión de promociones

Promociones

Con el recurso /seller-promotions puedes centralizar todos los tipos de promociones disponibles en el canal de Mercado Shops tales como boleto (BOLETO), cupón (COUPON), descuentos individuales (INDIVIDUAL), descuentos tradicionales (TRADITIONAL y MASSIVE). Para poder comenzar a usar la central de promociones en el canal y realizar promociones solo deberás contar con tu tienda creada y tener ítems.

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

Con el recurso /seller-promotions puedes gestionar las publicaciones con las diferentes promociones tanto para publicaciones de marketplace como para publicaciones del canal de Mercado Shops de manera diferenciada.

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
Nota:
Ten en cuenta que los campos de value_discount y discount_type, solo aplican para agregar publicaciones para una campaña masiva.

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

Con el recurso /seller-promotions puedes gestionar las diferentes promociones por cada tienda de Mercado Shops de manera diferenciada, permitiendo hacer acciones a nivel tienda y no individuales por items.

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.