Developers

Documentación Mercado Libre

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

Última actualización 04/09/2024

Campañas del vendedor

Los vendedores pueden crear sus propias campañas y gestionarlas a través de la integración.

Nota:

El plazo máximo para este tipo de campaña es de 31 dias.

Para ofrecer este descuento es necesario:

Tener reputación verde.
El ítem debe tener status igual a activo.
Condición igual a nuevo.
La exposición del ítem no puede ser gratuita.

Crear campaña

Para crear una campaña del vendedor realize la siguiente llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions?app_version=v2
{
   "promotion_type": "SELLER_CAMPAIGN",
   "name": "test campana del seller",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 15,
   "loyalty_percentage": 30,
   "start_date": "2023-07-17T00:00:00",
   "finish_date": "2023-07-20T00:00:00"
}

Campos de la llamada

promotion_type: tipo de la campaña a crear, de momento solo se permite SELLER_CAMPAIGN.
name: nombre de la campaña.
sub_type: para el caso de Campañas del vendedor, los sub_types permitidos son FIXED_PERCENTAGE y FLEXIBLE_PERCENTAGE.
fixed_percentage: solo para FIXED_PERCENTAGE (Obligatorio).
loyalty_percentage: solo para FIXED_PERCENTAGE (Opcional, descuento con loyalty).
start_date: fecha de inicio de la campaña en formato local. Siempre se tomará el principio del día como hora de inicio.
finish_date: fecha de finalización de la campaña en formato local. Siempre se tomará el final del día como hora de finalización.

Respuesta:

{
   "id": "C-MLB360923",
   "type": "SELLER_CAMPAIGN",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 15,
   "loyalty_percentage": 30,
   "status": "pending",
   "start_date": "2023-07-17T00:00:00",
   "finish_date": "2023-07-20T23:59:59",
   "name": "test campana del seller"
}

Actualizar campaña

Todos los campos pueden ser modificados, pero solo deben enviarse los campos que deseen modificarse. El único obligatorio es promotion_type, el cual siempre debe estar presente. Si se quiere eliminar el descuento de loyalty, debe enviarse remove_loyalty en true.

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?app_version=v2
{
   "promotion_type": "SELLER_CAMPAIGN",
   "name": "new name 10",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 18,
   "loyalty_percentage": 33,
   "start_date": "2023-07-18T00:00:00",
   "finish_date": "2023-07-19T00:00:00",
   "remove_loyalty": false
}

Respuesta:

{
   "id": "C-MLB360923",
   "type": "SELLER_CAMPAIGN",
   "sub_type": "FIXED_PERCENTAGE",
   "fixed_percentage": 18,
   "loyalty_percentage": 33,
   "status": "pending",
   "start_date": "2023-07-18T00:00:00",
   "finish_date": "2023-07-19T23:59:59",
   "name": "new name 10"
}

Eliminar campaña

Para eliminar una campaña del vendedor debes realizar esta llamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID?promotion_type=SELLER_CAMPAIGN&app_version=v2

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB360923?promotion_type=SELLER_CAMPAIGN&app_version=v2

Respuesta: Status 200 OK

Consultar detalle de campaña

Para las campañas de vendedores existen dos subtipos:
FIXED_PERCENTAGE - tiene un porcentaje de descuento fijo.
FLEXIBLE_PERCENTAGE - no tiene porcentaje fijo.

Para obtener los detalles de una campaña del vendedor, realiza la siguiente consulta:
Ejemplo sub_type FIXED_PERCENTAGE:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB300?promotion_type=SELLER_CAMPAIGN&app_version=v2

Respuesta:

{
  "id": "C-MLB300",
  "type": "SELLER_CAMPAIGN",
  "sub_type": "FIXED_PERCENTAGE",
  "fixed_percentage": 15,
  "loyalty_percentage": 30,
  "status": "started",
  "start_date": "2023-04-27T15:03:00Z",
  "finish_date": "2023-05-05T03:00:00Z",
  "name": "camp del seller 1"
}

Ejemplo sub_type FLEXIBLE_PERCENTAGE:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/C-MLB302?promotion_type=SELLER_CAMPAIGN&app_version=v2

Respuesta:

{
  "id": "C-MLB302",
  "type": "SELLER_CAMPAIGN",
  "sub_type": "FLEXIBLE_PERCENTAGE",
  "status": "started",
  "start_date": "2023-04-27T15:04:00Z",
  "finish_date": "2023-05-05T03:00:00Z",
  "name": "camp del seller tahi 2"
}

Campos de la respuesta

id: identificador de la campaña.
type: tipo de campaña (SELLER_CAMPAIGN).
sub_type: actualmente tenemos dos, FIXED_PERCENTAGE y FLEXIBLE_PERCENTAGE.
fixed_percentage porcentaje de descuento para todos los compradores.
loyalty_percentage porcentaje de descuento para los mejores compradores (niveles 3 a 6 del Mercado Puntos).
status: status de la campaña.
start_date: fecha que empieza la campaña.
finish_date: fecha que se cierra la campaña.
name: nombre de la campaña.

Estados

Estos son los distintos estados por los que puede pasar una campaña del vendedor.

Estado	Descripción
pending	Promoción aprobada, pero aún no inició.
started	Promoción activa.
finished	Promoción finalizada.

Consultar ítems en una campaña

Para conocer los ítems que forman parte de una campaña del vendedor puedes realizar la siguiente consulta:

Ejemplo sub_type FIXED_PERCENTAGE:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/C-MLB300/items?promotion_type=SELLER_CAMPAIGN&app_version=v2'

Respuesta:

{
  "results": [
      {
          "id": "MLB3538191898",
          "status": "candidate",
          "price": 0,
          "original_price": 5000,
          "fixed_percentage": 15,
          "loyalty_percentage": 30,
          "start_date": "2023-04-27T12:03:00",
          "end_date": "2023-05-05T00:00:00",
          "sub_type": "FIXED_PERCENTAGE"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 1
  }
}

Ejemplo sub_type FLEXIBLE_PERCENTAGE:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/C-MLB302/items?promotion_type=SELLER_CAMPAIGN&app_version=v2'

Respuesta:

{
  "results": [
      {
          "id": "MLB3538191898",
          "status": "candidate",
          "price": 0,
          "original_price": 5000,
          "start_date": "2023-04-27T12:04:00",
          "end_date": "2023-05-05T00:00:00",
          "sub_type": "FLEXIBLE_PERCENTAGE"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 1
  }
}

Estado de los ítems

En la siguiente tabla puedes encontrar los posibles estados que pueden tomar los ítems dentro de este tipo de campaña.

Estado	Descripción
candidate	Ítem candidato para participar de la promoción.
pending	Ítem con promoción aprobada y programada.
started	Ítem activo en la campaña.
finished	Ítem eliminado de la campaña

Indicar ítems para una campaña

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

Ejemplo sub_type FIXED_PERCENTAGE:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
    "promotion_id":"C-MLB300",
    "promotion_type":"SELLER_CAMPAIGN"
  }'
  https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

Respuesta:

{
  "price": 4250,
  "original_price": 5000
}

Ejemplo sub_type FLEXIBLE_PERCENTAGE:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
    "promotion_id":"C-MLB302",
    "promotion_type":"SELLER_CAMPAIGN",
    "deal_price": 3500,
    "top_deal_price": 3000
  }'
  https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

Respuesta:

{
    "price": 3500,
    "original_price": 5000
 }

Parámetros

promotion_id: identificación de la promoción.
promotion_type: tipo de promoción (SELLER_CAMPAIGN).
deal_price precio del ítem en la promoción.
top_deal_price precio del ítem para los mejores compradores, con nivel Mercado Puntos 3 a 6 (es opcional informar este precio)

Modificar ítems

En este tipo de campaña solo puede modificar los items que pertenecen a campañas con sub_type FLEXIBLE_PERCENTAGE.
Para modificar los ítems realiza la siguiente operación.
Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
    "promotion_id":"C-MLB302",
    "promotion_type":"SELLER_CAMPAIGN",
    "deal_price": 3300,
    "top_deal_price": 3000,
      "remove_loyalty": true  
  }'
  https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

Respuesta:

{
  "price": 3300,
  "original_price": 5000
}

Consideraciones

Si la oferta está activa:

Si tiene descuento de loyalty cargado, no se puede quitar más ese descuento.
Error message: "Top_deal_price can't be removed when the seller campaign has already started".
Si fue creada sin el descuento loyalty, no se puede agregar después.
Error message: "Top_deal_price can't be set when the seller campaign has already started" .
Los precios sólo pueden mejorar.
Error message: "New deal_price must be lower than current deal_price" / "New top_deal_price must be lower than current top_deal_price".

Si la oferta está pendiente:

Puede modificarse el deal_price y top_deal_price para un mayor o menor descuento.
Se puede agregar o sacar el descuento loyalty.

En caso de querer sacar el descuento de loyalty, se envía “remove_loyalty”: true. En el resto de los casos (no se quiere eliminar, se quiere agregar, se quiere modificar, o no se desea actuar sobre dicho precio), el campo se envía en false o directamente no se envía.

En el body solo se envían los campos que se desee cambiar.

Ejemplo. Modificación de top_deal_price:

{
    "top_deal_price": 1000.33,
    "promotion_id": "C-MLA123",
    "promotion_type": "SELLER_CAMPAIGN"
}

Ejemplo. Modificación de deal_price y eliminación de top_deal_price:

{
    "deal_price": 700,
    "promotion_id": "C-MLA123",
    "promotion_type": "SELLER_CAMPAIGN",
    "remove_loyalty": true
}

Respuesta:

{
    "price": 950,
    "original_price": 1000
}

Eliminar

Llamada:

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

Ejemplo:

curl -X DELETE -H 'https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?promotion_type=SELLER_CAMPAIGN&promotion_id=C-MLB302

Respuesta: Status 200 OK

Error de validación: 400 bad request

Mensaje de error	Descripción
The name already exists.	Ya existe una campaña del vendedor con el mismo nombre.
Invalid sub_type	Cuando el sub_type de una SELLER_CAMPAIGN no es FLEXIBLE_PERCENTAGE ni FIXED_PERCENTAGE.
The percentage is greater than allowed. the maximum percentage allowed is 70.000000	El máximo porcentaje permitido es del 70%. Si se envía, por ejemplo, fixed_percentage: 71, retornará este error.
The percentage is less than allowed. the minimum percentage allowed is 10.000000	El porcentaje esta abajo del permitido.
Fixed_percentage is required	Si la promoción es del tipo FIXED_PERCENTAGE, el campo fixed_percentage es necesario.
Invalid promotion type	Cuando el promotion_type es inválido.
Start and finish dates must be in local format	Cuando las fechas enviadas no están en formato local (como el ejemplo) o no se envían.
Start_date cannot be earlier than today	Start_date no puede ser anterior a hoy.
Finish_date cannot be earlier than startdate	Finish_date no puede ser anterior a start_date.
Maximum period cannot exceed the allowed	Cuando la distancia entre la start y finish date es mayor a la permitida.
The percentage difference between sellerpercentage and loyaltypercentage does not meet the minimum required	La diferencia entre el seller_percentage y loyalty_percentage debe ser mayor o igual a 5%.
Maximum period can not exceed the allowed	Cuando se quiere actualizar alguna fecha (o las dos), y el nuevo período entre ambas excede el permitido.
Percentages of a FLEXIBLE PERCENTAGE promotion must be updated per offer	Se intenta modificar un porcentaje o porcentaje de loyalty a una campaña que es del tipo flexible_percentage. Los porcentajes solo pueden setearse de forma generalizada en las fixed_percentages. Para las promociones flexibles, deben editarse los precios de las ofertas particulares.
The start_date field cannot be modified for the current promotion status	No se puede cambiar la fecha de inicio de una promoción en estado started.