Última actualización 04/05/2023

Descuento pre-acordado por ítem

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 son invitados periódicamente a participar de diferentes campañas que se realizan en el sitio. En este tipo de campaña el vendedor pre-acuerda un descuento para determinados ítems con un agente comercial de Mercado Libre, donde se establece el precio, el descuento ofrecido y el beneficio otorgado. Si recibiste una invitación y quieres sumarte puedes hacerlo con los siguientes recursos.


Vista del vendedor





Consultar detalles de una campaña

Ejemplo:

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

Respuesta:

{
   "id": "P-MLM394001",
   "type": "PRE_NEGOTIATED",
   "status": "started",
   "start_date": "2021-03-30T18:30:15.525Z",
   "finish_date": "2021-12-27T17:59:59.525Z",
   "deadline_date": "2021-05-27T17:59:59.525Z",
   "name": "Prueba descuento x item sin benefit",
   "offers": [
       {
           "id": "MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
           "original_price": 101,
           "new_price": 21,
           "status": "active",
           "start_date": "2021-05-10T16:00:00Z",
           "end_date": "2021-05-11T15:00:00Z",
           "benefits": {
               "type": "REBATE",
               "meli_percent": 9.9,
               "seller_percent": 69.3
           }
       }
   ]
}

Campos específicos de esta campaña


Offers: detalle del descuento pre-acordado.

  • id: id de la oferta
  • original_price: precio original del ítem
  • new_price: precio final del ítem
  • status: estado del ítem en la promoción
  • start_date: fecha de inicio de la oferta en la promoción
  • end_date: fecha de fin de la oferta en la promoción
  • Benefits: detalle de los beneficios de la promoción.
        • type: tipo de beneficio.
        • meli_percent: porcentaje que aporta Mercado Libre.
        • seller_percent: porcentaje que aporta el vendedor.


    Estados de las campañas

    Estos son los distintos estados por los que puede pasar una campaña con descuento pre-acordado.

    Estado Descripción
    pending Aprobada que aún no inició.
    started Activa
    finished Finalizada


    Consultar ítems en una campaña

    Para conocer los ítems que forman parte de una campaña con descuento pre-acordado puedes realizar la siguiente consulta:


    Ejemplo:

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

    Respuesta:

    {
       "results": [
           {
               "id": "MLM848619385",
               "status": "candidate",
               "price": 21,
               "original_price": 101,
               "offer_id": "MLM848619385-0e2f3064-0e13-425d-b4a7-0dee85414835",
               "meli_percentage": 24.8,
               "seller_percentage": 54.5,
               "start_date": "2021-05-11T22:00:00Z",
               "end_date": "2021-05-13T01:00:00Z"
           }
       ],
       "paging": {
           "total": 1
       }
    }
    

    Al crearse una nueva campaña se seleccionan todos los ítems aplicables a la misma. El estado inicial (status) de los ítems es candidate y cuentan con un offer_id único. Al momento que el vendedor incorpora un ítem a la campaña su status se modifica y pasa a estar programmed o active.



    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 Candidato para participar de la promoción.
    pending Promoción aprobada y programada.
    started Activo en la campaña.
    finished Eliminado de la campaña.


    Aceptar descuento

    Nota:
    Vea que para indicar y eliminar esta campaña de un ítem, cambiamos el wording de "deal_id" a "promotion_id".

    Una vez que se ha acordado un descuento para un ítem, con el siguiente recurso se puede dar la confirmación por parte del vendedor al pre-acuerdo.

    Llamada:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
    -d '{
       "promotion_id":"$PROMOTION_ID",
       "offer_id":"$OFFER_ID",
       "promotion_type":"$PROMOTION_TYPE"
    }'
    https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID
    

    Ejemplo:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
    -d '{
       "promotion_id":"P-MLM394001",
       "offer_id":"MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
       "promotion_type":"PRE_NEGOTIATED"
    }'
    https://api.mercadolibre.com/seller-promotions/items/MLM848619385
    

    Respuesta:

    {
       "offer_id": "MLM848619385-f588cf87-e298-498e-82ad-285b16dd11d5",
       "price": 21,
       "original_price": 101
    }
    

    Parámetros

    deal_id: identificación de la promoción.
    offer_id: identificación de la oferta acordada.
    promotion_type: tipo de promoción (PRE_NEGOTIATED).



    Eliminar descuento

    Con esta función puede eliminar la oferta del ítem.

    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_ID&offer_id=$OFFER_ID

    Ejemplo:

    curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLB1834747833?promotion_type=PRE_NEGOTIATED&promotion_id=P-MLM394001&offer_id=MLM1834747833-9eafadd4-16d2-49ae-b272-9a7a34585cb8

    Respuesta: Status 200 OK

    Nota:
    Ten en cuenta que si eliminas un descuento pre-acordado el ítem ya no se será candidato.

    Siguiente: Descuento individual