Gestionar promociones
Características de las promociones
Tipo de campaña | Nombre | 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 |
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 por volumen | VOLUME | Usuario acepta | No | Sí | No | Sí | No |
Descuento pre-acordado por ítem | PRE_NEGOTIATED | Usuario acuerda y acepta | No | Sí | Sí | Sí | No |
Disponibilidad de promoción 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) |
---|---|---|---|---|---|---|---|
MLA | |||||||
MLB | |||||||
MLM | |||||||
MCO | |||||||
MLC | |||||||
MLU | |||||||
MPE | |||||||
MLV |
Consultar las promociones disponibles para el 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
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/631366846
Respuesta:
{
"results": [
{
"id": "MLB686",
"type": "DEAL",
"status": "started",
"start_date": "2020-02-04T17:50:00Z",
"finish_date": "2022-10-31T17:20:00Z",
"deadline_date": "2020-01-30T02:00:00Z",
"name": "HOTSALE"
},
{
"id": "DOD-MLB1000",
"type": "DOD",
"status": "started",
"start_date": "2000-01-01T00:00:00.000Z"
},
{
"id": "LGH-MLB1000",
"type": "LIGHTNING",
"status": "started",
"start_date": "2000-01-01T00:00:00.000Z"
},
{
"id": "P-MLB379009",
"type": "VOLUME",
"status": "started",
"start_date": "2021-03-25T16:40:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test volume MLB",
"benefits": {
"type": "VOLUME",
"meli_percent": 8,
"seller_percent": 17,
"name": "4x3",
"buy_quantity": 4,
"pay_quantity": 3,
"item_discount_percent": 25
}
},
{
"id": "P-MLB380001",
"type": "VOLUME",
"status": "started",
"start_date": "2021-03-25T19:00:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test volume MLB BNSP",
"benefits": {
"type": "VOLUME",
"meli_percent": 10,
"seller_percent": 30,
"name": "buy 4 save 40%",
"buy_quantity": 4,
"item_discount_percent": 40
}
},
{
"id": "P-MLB380002",
"type": "VOLUME",
"status": "started",
"start_date": "2021-03-25T19:30:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test volume MLB SPONTH",
"benefits": {
"type": "VOLUME",
"meli_percent": 8,
"seller_percent": 17,
"name": "save 50% on 2nd",
"buy_quantity": 2,
"item_discount_percent": 25
}
},
{
"id": "P-MLB382001",
"type": "MARKETPLACE_CAMPAIGN",
"status": "started",
"start_date": "2021-03-25T22:36:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test cofondeada",
"benefits": {
"type": "REBATE",
"meli_percent": 2,
"seller_percent": 8
}
},
{
"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"
}
],
"paging": {
"offset": 0,
"limit": 50,
"total": 7
}
}
Campos de la respuesta
id: código de identificación de la oferta.
type: tipo de la oferta (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRE NEGOTIATED).
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
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663
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).
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
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792
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).
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
Conoce más detalles sobre campaña tradicional , campaña co-fondeada (marketplace campaign) y descuento por volumen.
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
Además, puedes consultar ítems de una campaña tradicional,
de una campaña
co-fondeada y los
items que pueden acceder a descuento por volumen.
Aquí puedes consultar los ítems de una
oferta del día, de una
oferta relámpago y estado de campaña con descuento pre-acordado por ítem
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
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
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
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 searchAfter. El valor enviado en este parámetro es siempre el último id del ítem retornado en la llamada anterior.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&searchAfter=$ITEM_ID'
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/MLB9377/items?promotion_type=DEAL&searchAfter=MLB2674512267'
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": "MLB2674512267",
"limit": 50,
"total": 14424
}
}
Participar de una promoción
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.
Consultar promociones del ítem
Para ofertas de tipo DEALS solo devolveremos los ítems con estado aprobado (status=approved).
No aprobaremos campañas con ítems test, es decir, quedarán con estado pending_approval y no mostraremos el precio
con promoción.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/items/MLA876768946
Respuesta:
[
{
"id": "2864-MLB876768946",
"type": "PRICE_DISCOUNT",
"status": "started",
"price": 700,
"top_price": 650,
"start_date": "2020-09-09T00:00:00",
"finish_date": "2020-09-15T00:00:00"
},
{
"id": "MLB686",
"type": "DEAL",
"status": "started",
"price": 680,
"start_date": "2021-03-04T17:50:00Z",
"finish_date": "2021-10-31T17:20:00Z",
"deadline_date": "2021-03-03T02:00:00Z",
"name": "HOT SALE"
},
{
"id": "P-MLB119001",
"type": "MARKETPLACE_CAMPAIGN",
"status": "started",
"start_date": "2021-04-15T18:37:40.881Z",
"finish_date": "2021-04-30T18:37:40.881Z",
"name": "10% en herramientas"
"benefits": {
"type": "REBATE",
"meli_percent": 2,
"seller_percent": 8
}
},
{
"id": "1504782-MLA874447795",
"type": "DOD",
"status": "started",
"price": 789,
"start_date": "2021-04-19T00:00:00",
"finish_date": "2021-04-19T23:59:59.999999999"
},
{
"id": "1499515-MLA915978647",
"type": "LIGHTNING",
"status": "started",
"price": 745,
"start_date": "2021-04-19T06:00:00",
"finish_date": "2021-04-19T12:00:00",
"remaining_stock": 3
},
{
"id": "P-MLB379009",
"type": "VOLUME",
"status": "started",
"start_date": "2021-03-25T16:40:00Z",
"finish_date": "2021-04-30T18:00:00Z",
"name": "test volume MLB",
"benefits": {
"type": "VOLUME",
"meli_percent": 8,
"seller_percent": 17,
"name": "4x3",
"buy_quantity": 4,
"pay_quantity": 3,
"item_discount_percent": 25
}
},
{
"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
}
}
]
}
]
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.
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 siguiente formulario.
Recuerda que tanto los usuarios como los ítems deben ser de test.
Next post: Campañas co-fondeadas