Última actualización 12/05/2023

Campañas del vendedor

Importante:
A partir del 10 de Mayo de 2023 deberá enviar el query param app_version=v2 para obtener la respuesta con la nueva versión de los recursos.
Por ahora las 2 versiones de /seller-promotions convivirán juntas, es decir, habrá retrocompatibilidad por un tiempo, para que pueda actualizar su desarrollo.

Los vendedores pueden crear sus propias campañas a través de su cuenta de Mercado Libre y gestionarlas a través de la integración. Si el vendedor ya ha creado una campaña y desea gestionar los ítems candidatos puedes hacerlo con los siguientes recursos.



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