Campañas del vendedor

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.

Para ofrecer este descuento es necesario:

• Tener reputación verde.
• El ítem debe tener status igual a activo o pausado.
• 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.

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.

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

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

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