Documentación Mercado Shops

Descubre toda la información que debes conocer sobre las APIs de Mercado Shops.
circulos azuis em degrade

Documentación

Última actualización 24/09/2024

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) y descuentos por volumen (VOLUME). 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.

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 .

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. También con discount_by_quantity, percentage_by_volume y percentage_by_unit, para los descuentos por volumen.
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, volume.
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, discount_by_quantity, percentage_by_unit y percentage_by_volume.
buy_quantity Es la cantidad de productos que forman parte de la promoción. Integer
pay_quantity Es la cantidad de productos que se pagan de la promoción. Integer

Importante:
A partir del 14/10/2024 los ID de las distintas promociones de Mshops pasan al formato C-{site}{Id} Ej: C-MLA242124. Se dará inicio a la migración progresiva con las campañas de cupones.

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 de ofertas por cantidad:

{
    "results": [
        {
            "id": "DXV-553421365-20230131110752752",
            "name": " DXV PRUEBA 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
        },
}

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 descuento tradicional:

{
        "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 oferta por cantidad:

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

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

Respuesta de ofertas por cantidad:


{
    "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": "Procesador De Alimentos"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 50,
        "total": 2
    }
}

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

Ejemplo para ofertas por cantidad:

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

Ejemplo de ofertas por cantidad:

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

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.

Parámetros esperados por tipo de campaña

PROPIEDAD BOLETO COUPON COUPON-FIXED TRADITIONAL
Name 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
Value Valor de la promoción Valor de la promoción Valor de la promoción (precio fijo) Valor de la promoción
type boleto coupon coupon traditional
start_date Fecha inicio Fecha inicio Fecha inicio Fecha inicio
end_date Fecha final Fecha final Fecha final Fecha final
target ALL_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
Item_id
campaign_item_type TRADITIONAL
buy_quantity
pay_quantity
PROPIEDAD TRADITIONAL-ITEM TRADITIONAL-MASIVO INDIVIDUAL VOLUME
Name Nombre de la promoción Nombre de la promoción Nombre de la promoción Nombre de la promoción
Discount_type PERCENT BY_ITEM discount_by_quantity , percentage_by_volume, percentage_by_unit
value Valor de la promoción Valor de la promoción Valor de la promoción (Excepto para discount_by_quantity)
type traditional traditional individual volume
start_date Fecha inicio Fecha inicio Fecha inicio Fecha inicio
end_date Fecha final Fecha final Fecha final Fecha final
target SELECTED_PRODUCTS LISTED_PRODUCTS SELECTED_PRODUCTS
min_payment_amount
code
one_coupon_per_use
items Lista de items en la promoción
item_id Id del item Id del item
campaign_item_type TRADITIONAL MASSIVE
buy_quantity cantidad de items que aplican a la promoción (entre 2 y 10 unidades)
pay_quantity cantidad de items que se deben pagar (Menor a la cantidad que lleva)


Consultar promociones por tienda

Mediante este recurso se puede consultar las promociones activas de una tienda.


Nota:
A partir del 14/10/2024 se visualizarán únicamente promociones que abarquen múltiples productos, es decir, no se enlistan aquellas campañas con type “individual”.

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 promociones

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, status, buy_quantity..


Ejemplo de cupon:


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 cupon 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"
}
Importante:

A partir del 14/10/12 se restringen las configuraciones de promociones por volumen. Las nuevas configuraciones son las siguientes:

  • Lleva “N” paga “M”:
    • 2 <= N <= 10
    • 1 <= M < N
  • Llevando “N”, “M”% de descuento en la compra:
    • 2 <= N <= 10
    • % descuento restringidos a: 5, 10, 15, 20, 25, 30, 40, 50, 60, 70 y 80
  • “M”% descuento en la N-ava unidad:
    • 2 <= N <= 10
    • % descuento restringidos a: 5, 10, 15, 20, 25, 30, 40, 50, 60, 70 y 80

Ejemplo ofertar por cantidad, sobre todas las unidades (20%off en la 6ta unidad):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
 "name": " DXV PRUEBA 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
}

Respuesta de la promoción creada:

{
    "id": "DXV-553421365-20230131110752752",
    "name": " DXV PRUEBA 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
}

Ejemplo de oferta por cantidad sobre una unidad ( 20%off comprando 6 unidades):

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

Respuesta satisfactoria:

{
    "id": "DXV-623329318-20240924115208528",
    "name": " DXV PRUEBA 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
}

Ejemplo de ofertas por cantidad de Unidades gratis (2x1)

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

Respuesta satisfactoria:

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

Tené en cuenta que no podés tener más de 1 oferta por cantidad al mismo tiempo en un producto, sean fechas exactas o días superpuestos.
Además que los porcentajes de ofertas pueden estar comprendidos entre (5% y 95%) y la cantidad de unidades aplicables a las promociones entre (2 y 10 unidades)


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.


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.


Consultar reporte de cupones

A través del recurso /coupons podrás obtener un reporte de los cupones vigentes en la tienda, permitiendo así tener visibilidad de los cupones creados en un rango de tiempo determinado.

Parámetros:

Se puede obtener el reporte de cupones disponibles en una tienda, realizando una consulta con los siguientes parámetros.


Nombre Tipo Descripcion Ejemplo
Seller_id String ID del vendedor/tienda 594239600
Start_date String Fecha de inicio del reporte en el formato yyyy-MM-dd 2024-07-09
End_date String Fecha de fin del reporte en el formato yyyy-MM-dd 2024-07-12

Llamada:


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

Ejemplo:


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

Respuesta exitosa de cupones


{
  "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"
    }
  ]
}

Respuesta exitosa de cupones, pero sin cupones dentro del rango de fecha seleccionado:


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

Recuperación de cupones sin fecha de inicio y/o sin fecha de fin:


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

Campos de la respuesta:

La respuesta de un GET al recurso /coupons proporcionará los siguientes parámetros

  • results:
    • id: id de la promoción/cupon
    • campaign_name: Nombre de la promoción/cupon
    • coupon_code: Código asignado para redimir el cupon
    • used_coupon: Booleano que me permite saber si fue usado o no el cupon
    • total_sales: Total de ventas generadas con los productos vendidos que aplicara el cupon
    • total_discount: Total de descuento generado con los productos vendidos que aplicara el cupon
    • created_date: Fecha creación de la promoción/cupon
    • start_date: Fecha inicio de la promoción/cupon
    • end_date: Fecha fin de la promoción/cupon
    • status: Estado de la promoción, sus valores pueden ser active (activo) o inactive (inactivo)

Errores Reporte Cupones

Recuperación de cupones con un formato de fecha incorrecto



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

Error al recuperar los cupones de un seller



 Request-code: 500
{
}

Error en el uso del access token para obtener información de cupones



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

Siguiente: Ventas de usuarios invitados.