Gestionar promociones

Características de las promociones

Nombre de la campaña	Tipo de campaña	Definición de precio	Sugerencia de precio	Bonificación MELI	Stock para participar	Deadline	Aprobación
Tradiconal	DEAL	Usuario define	No	No	No	Sí	Sí
Co-fondeada	MARKETPLACE CAMPAIGN	Usuario acepta	No	Sí	No	Sí	No
Descuento por volumen	VOLUME	Usuario acepta	No	Sí	No	Sí	No
Oferta del día	DOD	Usuario define	Sí	No	Sí, informativo	No	No
Oferta relámpago	LIGHTNING	Usuario define	Sí	No	Sí, mandatorio	No	No
Descuento pre-acordado por ítem	PRE_NEGOTIATED	Usuario acuerda y acepta	No	Sí	Sí	Sí	No
Campaña del vendedor	SELLER CAMPAIGN	Usuario define y acepta	No	No	No	Sí	No
Campaña co-fondeada automatizada	SMART	Usuario acepta	No	Sí	No	Sí	No
Campaña de precios competitivos	PRICE_MATCHING	Usuario acepta	No	Sí	No	Sí	No
Campaña de liquidación stock Full	UNHEALTHY_STOCK	Usuario acuerda y acepta	No	Sí	Sí	Sí	No

Disponibilidad por país

Sitio	Campañas tradicionales (DEAL)	Campaña co-fondeada (MARKETPLACE CAMPAIGN)	Descuento individual (PRICE DISCOUNT)	Descuento por volumen (VOLUME)	Descuento pre-acordado por ítem (PRE_NEGOTIATED)	Oferta del día (DOD)	Oferta relámpago (LIGHTNING)	Campaña co-fondeada automatizada (SMART)	Campaña de precios competitivos (PRICE_MATCHING)	Campaña de liquidación stock Full (UNHEALTHY_STOCK)	Campaña del vendedor (SELLER_CAMPAIGN)
MLA, MLB, MLM, MCO, MLC, MLU, MPE
MLV y MEC

Promociones del vendedor

Recuerda que un usuario puede tener más de una invitación y de diferentes tipos.

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/1356551933?app_version=v2

Respuesta:

{
      "results": [
          {
              "id": "P-MLB1806015",
              "type": "MARKETPLACE_CAMPAIGN",
              "status": "started",
              "start_date": "2023-04-20T02:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "Campanha de teste v2",
              "benefits": {
                  "type": "REBATE",
                  "meli_percent": 5,
                  "seller_percent": 25
              }
          },
          {
              "id": "P-MLB1806017",
              "type": "VOLUME",
              "status": "started",
              "start_date": "2023-04-20T03:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "Leva 3 paga 2",
              "benefits": {
                  "type": "VOLUME",
                  "meli_percent": 9.9999,
                  "seller_percent": 23.3331,
                  "name": "3x2",
                  "buy_quantity": 3,
                  "pay_quantity": 2,
                  "item_discount_percent": 33.333
              }
          },
          {
              "id": "P-MLB1806019",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-20T03:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "deals de teste v2"
          },
          {
              "id": "P-MLB1809008",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-21T21:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "Deals de test v2"
          },
          {
              "id": "P-MLB1809009",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-21T23:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "campanha de teste"
          }
      ],
      "paging": {
          "offset": 0,
          "limit": 50,
          "total": 5
      }
   }

Campos de la respuesta

id: código de identificación de la oferta.
type: tipo de la oferta (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
status: Estado
start_date: fecha de inicio de la oferta.
finish_date: fecha de fin de la oferta.
deadline_date: plazo máximo para aceptar la invitación.
name: nombre de la promoción.
deadline_date: plazo máximo para incorporar los ítems a la promoción.
benefits: configuración de beneficios de la promoción.

Consultar items candidatos

El recurso /seller-promotions/candidates permite identificar los ítems invitados a participar de una promoción. Siempre que un ítem obtiene el status de candidate en una promoción se envía una notificación con el candidate_id, con este recurso es posible identificar el ítem, la promoción y el status.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID?app_version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663?app_version=v2

Respuesta:

{    
    "id": "CANDIDATE-MLB1254949426-803130663",    
    "item_id": "MLB1254949426",    
    "promotion_id": "P-MLB4629001",    
    "type": "MARKETPLACE_CAMPAIGN",    
    "status": {        
    "id": "candidate"    
  } 
}

Campos de respuesta

id: código de identificación del candidato.

item_id: ítem asociado al candidato.

promotion_id: id de la promoción.

type: tipo de promoción (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).

status: estado del candidato.

Consultar ofertas

El recurso /seller-promotions/offers permite identificar cambios en la oferta de un ítem. Todos los cambios se envían por medio de notificaciones con el offer_id, es posible identificar el item, la promoción y el estado.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID?app_version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792?app_version=v2

Respuesta:

{    
    "id": "OFFER-MLB1970246686-42701792",    
    "item_id": "MLB1970246686",    
    "promotion_id": "P-MLB3329001",    
    "type": "DEAL",    
    "status": {        
    "id": "ACTIVE"    
  } 
}

Campos de la respuesta

id: código de identificación de la oferta.
item_id: ítem asociado a la oferta.
promotion_id: id de la promoción.
type: tipo de promoción (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART, PRICE_MATCHING, UNHEALTHY_STOCK y SELLER_COUPON_CAMPAIGN).
status: estado de la oferta. (programmed, active, e inactive).

Consultar detalles de la promoción

Realiza la siguiente consulta para acceder a los detalles particulares de una campaña tradicional, campaña co-fondeada y para los descuentos por volumen.

Llamada:

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

Para obtener más información, acceda a las documentaciones de cada campaña.

Estado

A continuación puedes encontrar los posibles estados que pueden tener los distintos tipos de promociones:

• Estados de campaña tradicional
• Estado de una campaña co-fondeada
• Estado de campaña descuento por volumen
• Estado de campaña con descuento pre-acordado por ítem

Consultar ítems de la promoción

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&app_version=v2

Además, puedes consultar ítems de una campaña:

• Tradicional
• Co-fondeada
• con descuento por volumen
• de Oferta del día
• de Oferta relámpago
• con descuento pre-acordado por ítem
• del vendedor
• Smart.

Filtros

Puedes aplicar filtros por ítem o status.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?promotion_type=$PROMOTION_TYPE&status=$STATUS&item_id=$ITEM_ID&app_version=v2

Ejemplo de filtro por ítem:

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

Respuesta:

 {
   "results": [
       {
           "id": "MLA604400000",
           "status": "started",
           "price": 23968,
           "original_price": 28549
       }
   ],
   "paging": {...}
}

Ejemplo de filtro por status started:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' /seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&status=started&app_version=v2

Respuesta:

  {
   "results": [
       {
            "id": "MLA639970000",
            "status": "started",
            "price": 4037,
            "original_price": 4427
        },
        {
            "id": "MLA639973333",
            "status": "started",
            "price": 6007,
            "original_price": 6587
        },
],
   "paging": [...]
}

Paginación

Para realizar la paginación deberás utilizar el parámetro search_after.
En la respuesta del GET, devolvemos el parámetro searchAfter, el cual servirá para poder recorrer los resultados. Para ello se deberá recuperar dicho ID y realizar la siguiente request con el query param search_after={search_after}. Este ID es un string, por eso tienen que aceptar el string y usarlo luego en sus pegadas.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&app_version=v2&limit=50&search_after={$SEARCH_AFTER}'

Ejemplo de paginación:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB13451002MLB9377/items?promotion_type=DEAL&app_version=v2&limit=50&search_after=d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca1b1a42'

Respuesta:

"results": [
       {
           "id": "MLB2674512266",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674506199",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674506138",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674505931",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674505924",
           "status": "candidate",
           "price": 0,
           "original_price": 0
 
 […]
 
 "paging": {
       "searchAfter":
"d3e3fb02371ca8e49ceb3e998c4a1b8da189235497375e55d3027c7dacf5a4ef0175b2aaca4f4a0fdf31299947d82ba661037482172ba7f9cfb1b0250d3134aa71c889367aa7c1401e4c3ff5bd70ee14337dfaa18c99bbe5e52dc3a2c1b55b195131903ecbc60a1c639e01dbecf11b15126d4b38cdb6122182acde2eca3b5b55",
       "limit": 50,
       "total": 14424
   }
}

Consideraciones

• Se devolverá search_after en todas las páginas, excepto en la última.
• La única forma de avanzar en la respuesta (paginar) es a través del uso de este parámetro.
• Al iterar los resultados, cada llamada retornará el search_after que deberá ser utilizado en la siguiente llamada.
• Siempre se debe utilizar el search_after que fue proporcionado por la respuesta del request, ya que este puede cambiar y expirar (tienen un TTL de 5 minutos).
• No es posible realizar paginados hacia atrás.

Cómo participar

Puedes participar en distintos tipos de promociones e incluso ofrecer un descuento individual para los ítems:

• Indicando ítems para una campaña tradicional.
• Indicando ítems para una campaña co-fondeada.
• Indicando ítems para descuento por volumen.
• Aceptando descuento pre-acordado por ítem.
• Indicando ítems para una oferta del día.
• Indicando ítems para una oferta oferta ralámpago.
• Ofreciendo un descuento individual para un ítem.
• Indicando items para una campaña del vendedor.
• Indicando items para una campaña smart.

Consultar promociones del ítem

Aca puede obtener todas las promociones que tiene el item y los status de las promociones en el momento de la consulta.

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

Ejemplo:

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

Respuesta:

[
      {
          "type": "PRICE_DISCOUNT",
          "status": "candidate",
          "price": 4000,
          "start_date": "2023-04-26T00:00:00",
          "finish_date": "2023-05-10T00:00:00"
      },
      {
          "type": "DOD",
          "status": "candidate",
          "price": 4000,
          "start_date": "2023-04-28T00:00:00",
          "finish_date": "2023-04-28T23:59:59"
      },
      {
          "id": "P-MLB1817004",
          "type": "MARKETPLACE_CAMPAIGN",
          "status": "pending",
          "start_date": "2023-04-27T23:00:00Z",
          "finish_date": "2023-06-01T02:00:00Z",
          "deadline_date": "2023-06-01T01:00:00Z",
          "name": "Campanha teste 10",
          "benefits": {
              "type": "REBATE",
              "meli_percent": 3,
              "seller_percent": 27
          }
      },
      {
          "id": "MLB1345",
          "type": "DEAL",
          "status": "pending",
          "start_date": "2023-04-27T23:00:00-03:00",
          "finish_date": "2023-05-31T23:00:00-03:00",
          "name": "teste 20"
      },
      {
          "id": "C-MLB300",
          "type": "SELLER_CAMPAIGN",
          "sub_type": "FIXED_PERCENTAGE",
          "status": "started",
          "price": 4250,
          "top_price": 3500,
          "start_date": "2023-04-27T00:00:00",
          "finish_date": "2023-05-05T23:59:59",
          "name": "camp del seller 1"
      },
      {
          "id": "P-MLB1812010",
          "type": "SMART",
          "status": "started",
          "name": "test-smart-2",
          "offers": [
              {
                  "id": "OFFER-MLB3538191898-177685",
                  "original_price": 5000,
                  "new_price": 3000,
                  "prime_price": null,
                  "status": "active",
                  "start_date": "2023-04-26T11:40:00Z",
                  "end_date": "2023-05-30T15:47:00Z",
                  "benefits": {
                      "type": "REBATE",
                      "meli_percent": 20,
                      "seller_percent": 20
                  }
              }
          ]
      },
      {
          "id": "C-MLB302",
          "type": "SELLER_CAMPAIGN",
          "sub_type": "FLEXIBLE_PERCENTAGE",
          "status": "candidate",
          "start_date": "2023-04-27T12:04:00",
          "finish_date": "2023-05-05T00:00:00",
          "name": "camp del seller 2"
      }
   ]  

Modificar ítems

Puedes modificar los ítems que están participando en una determinada oferta:

• Modificando ítems en una campaña tradicional.
• Modificando ítems en una campaña co-fondeada.
• Modificando ítems en una campaña con descuento por volumen.

Delete masivo de ofertas

Puedes eliminar de forma masiva todas las ofertas que están en el ítem.

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

Ejemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA1399846831?app_version=v2

Respuesta:

 {
   "successful_ids": [
       {
           "offer_id": "OFFER-MLA1399846831-10000081416",
           "error": null
       },
       {
           "offer_id": "OFFER-MLA1399846831-10000081567",
           "error": null
       }
   ],
   "errors": []
}

En casos donde el ítem tenga campañas que no pueden ser eliminadas de forma masiva, la llamada tendrá una respuesta http 200, pero la respuesta contendrá los mensajes de error.

Ejemplo donde ninguna oferta puede ser eliminada:

{
   "successful_ids": [],
   "errors": [
       {
           "offer_id": "OFFER-MLA1399846831-10000081416",
           "error": "The offer of type DOD not allowed for delete."
       },
       {
           "offer_id": "OFFER-MLA1399846831-10000081828",
           "error": "The offer could not be deleted. Try again."
       }
   ]
}

Ejemplo donde las ofertas fueron eliminadas correctamente y también ocurrieron errores:

{
   "successful_ids": [
       {
           "offer_id": "OFFER-MLA1399846831-10000081416",
           "error": null
       },
       {
           "offer_id": "OFFER-MLA1399846831-10000081417",
           "error": null
       }
   ],
   "errors": [
       {
           "offer_id": "OFFER-MLA1399846831-10000081418",
           "error": "The offer of type DOD not allowed for delete."
       },
       {
           "offer_id": "OFFER-MLA1399846831-10000081419",
           "error": "The offer could not be deleted. Try again."
       }
   ]
}

Posibles errores

423_ENTITY_LOCKED: La solicitud no pudo ser procesada porque el ítem está temporalmente bloqueado para realizar solicitudes. La solicitud puede intentarse nuevamente después de unos segundos.

400_BAD_REQUEST: Cuando el formato del ítem es inválido.

Eliminar ítems

Puedes eliminar los ítems que están participando en una determinada oferta:

• Eliminando ítems en una campaña tradicional.
• Eliminando ítems en una campaña co-fondeada.
• Eliminando ítems en una campaña con descuento por volumen.
• Eliminando descuento pre-acordado por ítem.
• Eliminando ítems en una oferta del día.
• Eliminando ítems en una oferta relámpago.
• Eliminando descuento individual a un ítem.

Asignar campañas de pruebas

Para realizar pruebas con campañas de test, envíanos los datos de tu usuario y/o ítems en el soporte por site.

• Argentina
• México
• Chile
• Bolivia
• Colombia
• Costa Rica
• República Dominicana
• Ecuador
• Uruguay
• Perú

Recuerda que tanto los usuarios como los ítems deben ser de test.

Next post: Campañas co-fondeadas