Central de ofertas

Con el recurso /seller-promotions podes centralizar todos los tipos de oferta disponibles como Deals (DEAL), Descuentos individuales (PRICE DISCOUNT), campañas co-fondeadas por Mercado Libre (MARKETPLACE CAMPAIGN). Además de los nuevos tipos de ofertas que desponibilicemos.


Contenidos

→Consultar las ofertas disponibles para el vendedor
→Consultar detalles de la oferta
    ↳Estado de la oferta
→Consultar ítems de la oferta
    ↳Estado del ítem en la oferta
→Participar de una oferta
    ↳Indicando ítems para un deal
    ↳Indicando ítems para una campaña co-fondeada
    ↳Ofreciendo un descuento para un ítem
→Consultar ofertas del ítem
→Modificar oferta
    ↳Modificando ítems de un deal
    ↳Modificando ítems de una campaña co-fondeada
→Eliminar oferta
→Errores comunes al ofrecer un descuento
→Asignar campaña de prueba



Consultar las ofertas disponibles para el vendedor

Con este recurso, puedes consultar las ofertas asociadas a un vendedor. Puede haber más de una invitación por usuario, incluso invitaciones de distintos tipos.


Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/users/631366846'

Respuesta:

{
"results": [
    {
      "id": "MLA686",
      "type": "DEAL",
      "status": "started",
      "start_date": "2019-02-04T17:50:00Z",
      "finish_date": "2020-10-31T17:20:00Z",
      "deadline_date": "2020-09-29T22:00:00-04:00",
      "name": "HOTSALE"
    },
    {
      "id": "P-MLA119001",
      "type": "MARKETPLACE_CAMPAIGN",
      "status": "started",
      "start_date": "2020-10-15T18:37:40.881Z",
      "finish_date": "2020-12-30T18:37:40.881Z",
      "deadline_date": "2020-12-29T22:00:00-04:00",
      "name": "P-MLA1252"
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 50,
    "total": 2
  }
}

Campos de la respuesta

id: código de identificación de la oferta.
type: tipo de la oferta (DEAL, MARKETPLACE_CAMPAIGN).
status: estado de la oferta.
start_date: fecha de inicio de la oferta.
finish_date: fecha de fin de la oferta.
start_date: fecha de inicio de la oferta.
deadline_date: plazo máximo para aceptar la invitación.
name: nombre de la campaña.



Consultar detalles de la oferta

Para obtener los detalles de las ofertas, realiza la siguiente consulta con el parámetro promotion_type (DEAL o MARKETPLACE_CAMPAIGN).


Llamada:

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

Ejemplo oferta tradicional (DEAL):

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/MLA686?promotion_type=DEAL'

Respuesta:

{
  "id": "MLA686",
  "type": "DEAL",
  "status": "started",
  "start_date": "2019-02-04T17:50:00Z",
  "finish_date": "2020-10-31T17:20:00Z",
  "deadline_date": "2020-09-30T02:00:00Z",
  "name": "HOTSALE"
}

Ejemplo oferta co-fondeada (MARKETPLACE CAMPAIGN):

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/MLA686?promotion_type=MARKETPLACE_CAMPAIGN'

Respuesta:

{
  "id": "MLA686",
  "type": "MARKETPLACE_CAMPAIGN",
  "status": "started",
  "start_date": "2019-02-04T17:50:00Z",
  "finish_date": "2020-10-31T17:20:00Z",
  "deadline_date": "2020-09-30T02:00:00Z",
  "name": "P-MLA1252",
  "benefits": {
    "type": "REBATE",
    "meli_percent": 90,
    "seller_percent": 0
  }
}


Estado de la oferta

En las siguientes tablas encuentras los posibles estados que pueden tener las distintas ofertas.



Campaña tradicional (DEAL)

Estado Descripción
pending Oferta aprobada que aún no inició
started Oferta activa
finished Oferta finalizada

Campaña co-fondeada (MARKETPLACE CAMPAIGN)

Estado Descripción
pending_approval Oferta pendiente de aprobación
pending Oferta aprobada que aún no inició
started Oferta activa



Consultar ítems de la oferta

Para conocer los ítems que forman parte de una determinada oferta puedes realizar la siguiente consulta:


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=PROMOTIONS_TYPE'

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/MLA686/items?promotion_type=DEAL'

Respuesta para campaña tradicional (DEAL):

{
  "results": [
    {
      "id": "MLA875050287",
      "status": "pending_approval",
      "price": 300,
      "original_price": 1000
    },
    {
      "id": "MLA876387768",
      "status": "pending_approval",
      "price": 900,
      "original_price": 1000
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 50,
    "total": 2
  }
}

Respuesta para campaña co-fondeada (MARKETPLACE CAMPAIGN):

{
  "results": [
        {
            "id": "MLA877277006",
            "status": "ACTIVE",
            "price": 1349,
            "original_price": 1500,
            "offer_id": "MLA877277006-e2c63989-ad16-4ef3-9b6d-0c6da0ac40a5"
        },
        {
            "id": "MLA1767902544",
            "status": "",
            "price": 0,
            "original_price": 0
        }
    ],
    "paging": {
        "total": 2
    }
}


Estado del ítem en la oferta

En las siguientes tablas puedes encontrar los posibles estados que pueden tomar los ítems dentro de las distintas campañas.



Descuento individual (PRICE DISCOUNT)

Estado Descripción
started Descuento activo en el ítem
finished Descuento finalizado
pending Descuento programado
sync_requested Proceso de activación pendiente
restore_requested Proceso pendiente de eliminación del descuento

Campaña tradicional (DEAL)

Estado Descripción
approved Ítem aprobado para la oferta
pending_approval Ítem pendiente de aprobación para la oferta
rejected Ítem rechazado para la oferta

Campaña co-fondeada (MARKETPLACE DISCOUNT)

Estado Descripción
active Ítem con oferta activa
programmed Ítem con oferta aprobada y programada


Participar de una oferta

Puedes participar en distintos tipos de campañas y ofrecer un descuento individual para los ítems:



Indicando ítems para un deal

Una vez que has sido invitado a participar en una campaña de ofertas, puedes indicar qué productos deseas incluir en la misma.


Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "deal_id":"$DEAL_ID",
   "regular_price":$REGULAR_PRICE,
   "deal_price":$DEAL_PRICE,
   "promotion_type":"$PROMOTION_TYPE"
}'
'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID'

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "deal_id":"MLA1804",
   "regular_price":350,
   "deal_price":240,
   "promotion_type":"DEAL"
}'
'https://api.mercadolibre.com/seller-promotions/items/MLA876768946'

Respuesta:

{
  "price": 240,
  "original_price": 350
}

Parámetros

deal_id: identificación de la oferta.
regular_price: precio del producto antes de la oferta.
deal_price: precio del ítem en la oferta.
promotion_type: tipo de oferta (DEAL.)



Indicando ítems para una campaña co-fondeada

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "deal_id":"$DEAL_ID",
   "deal_price": "$DEAL_PRICE",
   "promotion_type":"$PROMOTION_TYPE"
}'
'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID'

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "deal_id":"P-MLA147001",
   "deal_price": 1800,
   "promotion_type":"marketplace_campaign"
}'
'https://api.mercadolibre.com/seller-promotions/items/MLA876618673'

Respuesta:

{
  "offer_id": "MLA876618673-9eafadd4-16d2-49ae-b272-9a7a34585cb8",
  "price": 1800,
  "original_price": 2000
}

Parámetros

deal_id: identificación de la oferta co-fondeada.
deal_price: precio del ítem en la oferta.
promotion_type: tipo de oferta (MARKETPLACE_CAMPAIGN).



Ofreciendo un descuento para un ítem

Para este tipo de oferta, debes cumplir algunos requisitos. Conoce más sobre cómo ofrecer descuentos.


Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "discount_percent": $DISCOUNT_PERCENT,
   "top_discount_percent": $TOP_DISCOUNT_PERCENT,
   "start_date": "$START_DATE",
   "finish_date": "$FINISH_DATE",
   "promotion_type": "PRICE_DISCOUNT"
}'
'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID'

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "discount_percent": 20,
   "top_discount_percent": 30,
   "start_date": "2020-10-19T00:00:00",
   "finish_date": "2020-10-20T00:00:00",
   "promotion_type": "PRICE_DISCOUNT"
}'
'https://api.mercadolibre.com/seller-promotions/items/MLA876768946'

Respuesta:

{
    "price": 70,
    "original_price": 100
}

Parámetros

discount_percent: porcentaje de descuento para todos los compradores.
top_discount_percent: porcentaje de descuento para los mejores compradores (con nivel Mercado Puntos 3 a 6).
start_date: fecha de inicio del descuento.
finish_date: fecha de fin del descuento.


Consideraciones

  • El tag loyalty_discount_eligible indica que el producto es elegible para aplicar un descuento, pero deberás tener en cuenta las reglas sobre cómo ofrecerlos.
  • Es posible segmentar la oferta de descuentos estableciendo un porcentaje general para todos los compradores, y una superior solo para nuestros compradores leales (con nivel 3 al 6 de Mercado Puntos).
  • El descuento general debe ser como mínimo 5% menor al descuento de usuarios de nivel 3 al 6, para descuentos de hasta 35%. Para descuentos superiores, la diferencia debe ser de minimo 10%, es decir, damos mejores descuentos a los niveles más altos.
  • El descuento máximo debe ser menor a 80% y el descuento mínimo a ofrecer deberá ser mayor o igual al 5%.
  • Si se realiza una suba del precio del ítem, los descuentos serán quitados automáticamente.
  • Si al iniciar el descuento, el ítem se encuentra participando de un DEAL, dicho descuento no será aplicado hasta que finalice el DEAL asociado.
  • El plazo máximo para un descuento PRICE_DESCOUNT es de 7 días.
Nota:
Ten en cuenta que para realizar pruebas, es necesario que el usuario de TEST tenga reputación verde y el ítem tenga como mínimo 3 ventas con el precio actual.

Consultar ofertas del ítem

Para conocer las ofertas en el que está un item, realice la siguiente consulta:


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

Ejemplo:


curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLA876768946'

Respuesta:


[
  {
    "id": "2864-MLA876768946",
    "type": "PRICE_DISCOUNT",
    "status": "started",
    "start_date": "2020-09-09T00:00:00",
    "finish_date": "2020-09-15T00:00:00"
  },
  {
    "id": "MLA686",
    "type": "DEAL",
    "status": "approved",
    "start_date": "2019-02-04T17:50:00Z",
    "finish_date": "2020-10-31T17:20:00Z",
    "deadline_date": "2020-09-30T02:00:00Z",
    "name": "Super deal"
  },
  {
    "id": "P-MLA119001",
    "type": "MARKETPLACE_CAMPAIGN",
    "status": "started",
    "start_date": "2020-10-15T18:37:40.881Z",
    "finish_date": "2020-12-30T18:37:40.881Z",
    "name": "P-MLA1252"
  }
]
Nota:
- Para ofertas de tipo DEALS solo devolveremos los ítems con estado aprobado (status=approved).
- No aprobaremos campañas con ítems test, es decir, quedarán con estado pending_approval y no mostraremos el precio con oferta.



Modificar oferta

Para modificar los ítems que están participando de una oferta puedes hacerlo de la siguiente manera:


Modificando ítem de una campaña tradicional (DEAL)

Llamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
-d'{
   "deal_id":"$DEAL_ID",
   "regular_price":$REGULAR_PRICE,
   "deal_price":$DEAL_PRICE,
   "promotion_type":"DEAL"
}'
'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID'

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
-d'{
   "deal_id":"MLA1804",
   "regular_price":350,
   "deal_price":220,
   "promotion_type":"DEAL"
}'
'https://api.mercadolibre.com/seller-promotions/items/MLB1676902612'

Respuesta:

{
  "price": 220,
  "original_price": 350
}

Modificando ítems de una campaña co-fondeada (MARKETPLACE CAMPAIGN)

Llamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "deal_id":"$DEAL_ID",
   "deal_price":$DEAL_PRICE,
   "promotion_type":"MARKETPLACE_CAMPAIGN",
   "offer_id": "$OFER_ID"
}'
'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID'

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
-d '{
   "deal_id":"P-MLA147001",
   "deal_price":1900,
   "promotion_type":"MARKETPLACE_CAMPAIGN",
   "offer_id": "MLA876618673-9eafadd4-16d2-49ae-b272-9a7a34585cb8"
}'
'https://api.mercadolibre.com/seller-promotions/items/MLB1676902612'

Respuesta:

{
  "price": 1900,
"original_price": 2000
}
Nota:
Para editar los descuentos individuales (PRICE DISCOUNT) debes eliminarlos y darlos de alta nuevamente.



Eliminar oferta

Con este recurso podrás eliminar la oferta del ítem.


Eliminar items de una oferta tradicional (DEAL)

Llamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&deal_id=$DEAL_ID

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLA632979587?promotion_type=DEAL&deal_id=1804'

Eliminar ítems de una oferta co-fondeada (MARKETPLACE CAMPAIGN)

Llamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&deal_id=$DEAL_ID&offer_id=$OFFER_ID'

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLA632979587?promotion_type=MARKETPLACE_CAMPAIGN&deal_id=1804&offer_id=MLA876618673-9eafadd4-16d2-49ae-b272-9a7a34585cb8'

Eliminar descuento individual (PRICE DISCOUNT) a un ítem

Llamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&deal_id=$DEAL_ID&offer_id=$OFFER_ID'

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLA876768946?promotion_type=PRICE_DISCOUNT'

Recuerda que para las ofertas individuales (PRICE DISCOUNT) eliminarás toda la oferta, no podrás eliminar por niveles del comprador.


Respuesta: Status 200 OK



Errores comunes al ofrecer un descuento

Descuentos fuera de los rangos establecidos

{
   "key":"buyer_discount_not_in_range",
   "message":"buyers_discount_percentage parameter must be in range (5, 80)"
}
{
   "key":"best_buyer_discount_not_in_range",
   "message":"buyers_discount_percentage parameter must be in range (5, 80)"
}

Diferencias entre descuentos para niveles 1-2 y niveles 3-6 fuera de los márgenes establecidos

{
   "key":"discount_below_10_percent_difference",
   "message":"The best buyer discount difference cannot be below 10% when buyers discount is above 35%"
}
{
   "key":"discount_below_5_percent_difference",
   "message":"The discount difference cannot be below 5%"
}

Además, para algunos ítems a validar el descuento aplicado, podemos identificar si el descuento no es suficiente y el vendedor debe aplicar un descuento mayor. Para estos casos, devolveremos el siguiente error:

{
    "key": "error_credibility_price",
    "message": "The price is not credible."
}

Asignar campaña de prueba

Para realizar pruebas con campañas de test, envía los datos de tu usuario y/o ítems en el siguiente formulario.
Recuerda que tanto los usuarios como los ítems deben ser de test.


Nota:
Debes agregar el parámetro version=test dentro de las llamadas para interactuar con estas campañas

o regístrate para recibir las últimas novedades sobre nuestra API