Buscar en la documentación

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluciones

Promotion

El módulo de Promociones está restringido a las integraciones existentes. Los nuevos socios deben usar el módulo de Artículos para mecánicas promocionales sencillas. Más información aquí.

El módulo Promotion permite crear y gestionar promociones de productos en su tienda, ofreciendo diferentes mecánicas de descuento para atraer y comprometer clientes.Principales funcionalidades:

Crear promociones con descuento porcentual
Configurar combos "Lleve X Pague Y"
Aplicar descuento progresivo por unidad
Agendar período de vigencia de las promociones
Consultar estado y detalles de las promociones activas

Módulo exclusivoEste módulo es de uso exclusivo de partners que operan con mercado y no está disponible para todos los desarrolladores. Si tiene interés en utilizar funciones de esta API, entre en contacto con el equipo de atención.

Otros tipos de promociónLas promociones del tipo DE-POR y ATACAREJO deben ser configuradas por el módulo Item.

Crear Promociones

Use POST /merchants/{merchantId}/promotions para crear promociones.Descripción: Este endpoint crea nuevas promociones para una tienda. Las promociones permanecen activas hasta la fecha final especificada. Nuevas solicitudes se suman a las promociones existentes — para sustituir la lista completa, use el parámetro ?reset=true.

Tipos de Promociones

Elija el tipo de promoción según su necesidad de descuento:

PERCENTAGE - Descuento Porcentual

Aplica descuento porcentual en el precio del ítem. Use para promociones simples donde quiere ofrecer un descuento fijo porcentual.Ejemplo: Ítem de R$ 10,00 con 10% de descuento = R$ 9,00

{
  "aggregationTag": "123456",
  "promotions": [
    {
      "promotionName": "Promoción prueba",
      "channels": ["IFOOD-APP"],
      "items": [
        {
          "ean": "3213434343",
          "discountValue": 20.0,
          "initialDate": "2024-10-23",
          "finalDate": "2024-10-30",
          "promotionType": "PERCENTAGE"
        }
      ]
    }
  ]
}

LXPY - Lleve X Pague Y

Aplica descuento en combo de ítems. Use para promociones de cantidad como "compre 3, pague 2".Ejemplo: Ítem de R$ 10,00 en combo "Lleve 3 Pague 2" = R$ 20,00 total (R$ 6,66 cada uno)

{
  "aggregationTag": "123456",
  "promotions": [
    {
      "promotionName": "Promoción prueba del tipo LXPY",
      "channels": ["IFOOD-APP"],
      "items": [
        {
          "ean": "3213434343",
          "discountValue": null,
          "initialDate": "2024-10-23",
          "finalDate": "2024-10-30",
          "promotionType": "LXPY",
          "progressiveDiscount": {
            "quantityToBuy": 3,
            "quantityToPay": 2
          }
        }
      ]
    }
  ]
}

PERCENTAGE_PER_X_UNITS - Descuento en la Nª Unidad

Aplica descuento porcentual a cada X unidades compradas. Use para incentivar compras en cantidad con descuento progresivo.Ejemplo: Ítem de R$ 10,00 con 50% en la 2ª unidad = R$ 15,00 total (2 unidades)

{
  "aggregationTag": "123456",
  "promotions": [
    {
      "promotionName": "Promoción prueba - 50% en la 3ª unidad",
      "channels": ["IFOOD-APP"],
      "items": [
        {
          "ean": "3213434343",
          "discountValue": 50.0,
          "initialDate": "2024-10-23",
          "finalDate": "2024-10-30",
          "promotionType": "PERCENTAGE_PER_X_UNITS",
          "progressiveDiscount": {
            "quantityToBuy": 3
          }
        }
      ]
    }
  ]
}

Ejemplo de Solicitud

cURL

curl -X POST "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{{merchantId}}/promotions" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregationTag": "123456",
    "promotions": [
      {
        "promotionName": "Promoción prueba",
        "channels": ["IFOOD-APP"],
        "items": [
          {
            "ean": "3213434343",
            "discountValue": 20.0,
            "initialDate": "2024-10-23",
            "finalDate": "2024-10-30",
            "promotionType": "PERCENTAGE"
          }
        ]
      }
    ]
  }'

Campos del payload

Campo	Tipo	Obligatorio	Descripción
`aggregationTag`	String	No	Identificador personalizado de la solicitud
`promotions[].promotionName`	String	No	Nombre de la promoción
`promotions[].channels`	Array	Sí	Canales de venta (ej: `IFOOD-APP`)
`promotions[].items[].ean`	String	Sí	Código EAN del producto
`promotions[].items[].discountValue`	Double	Condicional	Valor del descuento en %
`promotions[].items[].initialDate`	Date	Sí	Fecha de inicio (formato: `YYYY-MM-DD`)
`promotions[].items[].finalDate`	Date	Sí	Fecha de término (formato: `YYYY-MM-DD`)
`promotions[].items[].promotionType`	String	Sí	Tipo: `PERCENTAGE`, `LXPY` o `PERCENTAGE_PER_X_UNITS`
`progressiveDiscount.quantityToBuy`	Integer	Condicional	Cantidad a comprar (LXPY y PERCENTAGE_PER_X_UNITS)
`progressiveDiscount.quantityToPay`	Integer	Condicional	Cantidad a pagar (solo LXPY)

Reglas de campos por tipo

Tipo	Campos obligatorios
`PERCENTAGE`	`discountValue`
`LXPY`	`quantityToBuy`, `quantityToPay`
`PERCENTAGE_PER_X_UNITS`	`discountValue`, `quantityToBuy`

Límite de descuentoDescuentos máximos permitidos: 70% del precio de catálogo. Ítems con descuento superior serán rechazados.Ejemplo no permitido: "Lleve 10 Pague 2" = 80% de descuento

Respuesta de Éxito

HTTP 202 - Aceptado (Procesamiento Asíncrono)Su solicitud fue recibida con éxito, pero el procesamiento de promociones ocurre de forma asíncrona. Use el aggregationId retornado para rastrear el estado real de sus promociones.

{
  "aggregationId": "abc123",
  "message": "We have successfully received your request to create promotions"
}

Campos retornados:

aggregationId (string): ID único para rastreo de la solicitud
message (string): Mensaje de confirmación

Importante: Procesamiento AsíncronoEl estado HTTP 202 indica que su solicitud fue recibida, pero no confirma que las promociones fueron creadas con éxito. Debe usar el endpoint GET con el aggregationId para verificar el estado real y confirmar que todas las promociones fueron procesadas sin errores.Recomendación: Siempre consulte el estado vía GET y valide en la App de iFood antes de comunicar la promoción al cliente.

Errores Comunes

HTTP 400/422 - Error de Negocio

{
  "type": "Business Exception",
  "title": "Business Exception",
  "status": 400,
  "detail": "Detail error",
  "instance": "07228dab-644c-4bec-b8a3-073397a839a0"
}

HTTP 412 - Error de Validación

{
  "type": "Invalid Argument",
  "title": "Invalid Request Body",
  "status": 412,
  "detail": "Detail error",
  "instance": "07228dab-644c-4bec-b8a3-073397a839a0"
}

Causas Comunes:

Fechas en formato incorrecto (use YYYY-MM-DD)
Descuento superior a 70% del precio
EAN del producto inexistente o inactivo
Campos obligatorios faltando conforme el tipo de promoción

Actualizar Promociones (Reset)

Para sustituir completamente todas las promociones activas de la tienda, agregue el parámetro ?reset=true a la solicitud POST:

POST /merchants/{merchantId}/promotions?reset=true

Comportamiento del Reset

Cuando usa ?reset=true, el sistema realiza las siguientes acciones:

Crea nuevos ítems promocionales que están en el payload
Mantiene ítems que ya existen y están presentes en el nuevo payload
Desactiva automáticamente ítems que NO están en el nuevo payload

Cuándo NO usar reset=trueNo use el parámetro reset si solo quiere agregar nuevas promociones. Use reset solo cuando necesite sustituir la lista completa de promociones.

Mejores Prácticas

Frecuencia: Use con moderación (preferiblemente diariamente fuera del horario comercial)
Validación: Ejecute solo cuando haya cambios significativos
Límite: Máximo 10.000 ítems promocionales por solicitud
Timing: Evite ejecutar durante horarios pico de ventas

Consultar Estado de Promociones

Use GET /merchants/{merchantId}/promotions/{aggregationId}/items para verificar el estado de procesamiento de sus promociones.Descripción: Retorna detalles de ítems de promoción con soporte a filtros y paginación. Permite monitorear el estado del procesamiento asíncrono iniciado por la solicitud de creación.

Procesamiento AsíncronoComo el procesamiento es asíncrono, consultas inmediatas después del POST pueden retornar una lista vacía. Espere algunos segundos antes de consultar el estado.

Ejemplo de Solicitud

cURL

curl -X GET "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{{merchantId}}/promotions/{{aggregationId}}/items?offset=0&limit=10&status=ACTIVE" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json"

Filtros disponibles

Parámetro	Tipo	Descripción
`ean`	String	Código EAN del producto
`promotionName`	String	Nombre de la promoción
`promotionType`	String	Tipo de la promoción
`status`	String	Estado actual (vea tabla abajo)
`offset`	Integer	Posición inicial del listado
`limit`	Integer	Ítems por página (máximo: 1000)

Estado de las promociones

Estado	Descripción
`PROCESSING`	Recibido y en validación
`SCHEDULED`	Validado, aguardando fecha de inicio
`ACTIVE`	Validado y en operación
`DUPLICATE`	Ítem promocional duplicado (ya enviado anteriormente)
`FINISHING`	Remoción solicitada, aguardando efectivización
`FINISHED`	Removido con éxito
`ERROR`	Error detectado (vea campo `error` para detalles)

Estado ACTIVE no garantiza visibilidadUna promoción ACTIVE está registrada en el sistema, pero puede no aparecer en la App para todos los usuarios debido a:

Otras promociones activas para el mismo ítem
Reglas de priorización (muestra el mejor descuento)
Promociones de iFood, industria o insertadas vía Portal del Partner

Interpretando la Respuesta

HTTP 200 - ÉxitoCampos retornados:

promotions (array): Lista de ítems de promoción procesados
- promotionItemId (string, UUID): Identificador único del ítem de promoción
- ean (string): Código EAN del producto
- status (string): Estado actual (vea tabla abajo)
- initialDate (string, date): Fecha de inicio de la promoción
- finalDate (string, date): Fecha de término de la promoción
- promotionType (string): Tipo de promoción
- discountValue (string): Valor del descuento (en %)
- promotionName (string): Nombre de la promoción
- progressiveDiscount (object, opcional): Descuento progresivo (si aplica)
  - quantityToBuy (number): Cantidad a comprar
  - quantityToPay (number): Cantidad a pagar
- error (string, opcional): Detalle del error (presente solo cuando status = ERROR)
pagination (object): Información de paginación
- nextOffset (integer): Valor del próximo offset para paginación
- currentOffset (integer): Valor del offset actual

{
  "promotions": [
    {
      "promotionItemId": "005f5ea0-1ff4-4c9b-9f48-76d94bfe4694",
      "ean": "3213434343",
      "status": "ACTIVE",
      "initialDate": "2024-10-10",
      "finalDate": "2024-10-11",
      "promotionType": "LXPY",
      "promotionName": "Promoción prueba del tipo LXPY",
      "progressiveDiscount": {
        "quantityToBuy": 3,
        "quantityToPay": 2
      }
    }
  ],
  "pagination": {
    "nextOffset": 99,
    "currentOffset": 0
  }
}

Códigos de error

Código	Detalle
`DATE_INVALID`	Verifique formato de las fechas (`YYYY-MM-DD`) y si `finalDate` > `initialDate`
`PROMOTION_TYPE_INVALID`	Valores válidos: `PERCENTAGE`, `LXPY`, `PERCENTAGE_PER_X_UNITS`
`DISCOUNT_INVALID`	Verifique campos obligatorios para cada tipo y límite de 70% de descuento
`ITEM_NOT_FOUND`	EAN incorrecto o producto inactivo/sin stock
`INTERNAL_ERROR`	Entre en contacto con el soporte iFood

Verificar Promociones en Pedidos

Las promociones aprobadas y activas aparecen automáticamente en los pedidos de los clientes. Puede verificar cómo una promoción fue aplicada consultando el GET /orders/{id}/virtual-bag:

Identificar Promociones de su Tienda

Siga estos pasos para localizar promociones de su tienda dentro de un pedido:

Acceda a la sección benefit.benefits de la respuesta
Filtre beneficios donde target = ITEM
Filtre por sponsorships contiendo 1 elemento donde liability = PARTNER o CHAIN

Calcular el Valor Final con Descuento

Para determinar el precio final de un ítem con descuento aplicado:

Obtenga el targetId del beneficio
Correlacione con el bag.items[].uniqueId correspondiente
Reste sponsorships.amount.value de prices.grossValue.value

Próximos pasos

Verifique los criterios para realizar su homologación

¿Esta página fue útil?

Evalúa tu experiencia en el nuevo portal de desarrolladores: