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.

Creación de promociones

Use POST /merchants/{merchantId}/promotions para crear promociones.Descripción: Este endpoint crea nuevas promociones para una tienda.

Comportamiento del endpointEste endpoint adiciona promociones a la tienda. Las promociones permanecen activas hasta la fecha final. Nuevas solicitudes se suman a las promociones existentes. Para sustituir la lista actual, use ?reset=true. Vea Actualización de promociones.

Ejemplo de 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"
          }
        ]
      }
    ]
  }'

Tipos de promociones

PERCENTAGE - Descuento porcentual

Aplica descuento porcentual en el precio del ítem.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.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.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
          }
        }
      ]
    }
  ]
}

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 la solicitud

Éxito (HTTP 202)

Campos retornados:

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

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

Procesamiento asíncronoEl estado 202 indica que la solicitud fue recibida, pero no que las promociones fueron creadas. Use el aggregationId para consultar el estado real vía GET.Recomendación: Valide el estado en el endpoint GET y verifique en la App de iFood antes de considerar la promoción activa.

Error

HTTP 400/422 - Error de procesamiento

{
  "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"
}

Actualización de promociones

Para sustituir todas las promociones activas de la tienda, use el parámetro ?reset=true:

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

Comportamiento del reset:

Crea nuevos ítems promocionales
Mantiene ítems idénticos a los ya existentes
Desactiva ítems no incluidos en el nuevo payload

Recomendaciones:

Use con moderación (diariamente fuera del horario comercial)
Ejecute solo cuando haya alteraciones
Límite: máximo 10.000 ítems promocionales por payload

Consulta de promociones

Use GET /merchants/{merchantId}/promotions/{aggregationId}/items para consultar estado de las promociones.Descripción: Retorna detalles de ítems de promoción con soporte a filtros y paginación.Importante: El procesamiento es asíncrono. Consultas inmediatas después del POST pueden retornar lista vacía.

Ejemplo de 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

Respuesta de la solicitud

Éxito (HTTP 200)

Campos retornados:

promotions (array): Lista de ítems de promoción
- promotionItemId (string, UUID): Identificador único del ítem de promoción
- ean (string): Código EAN del producto
- status (string): Estado actual (PROCESSING, ACTIVE, FINISHED, SCHEDULED, FINISHING, ERROR)
- 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 (PERCENTAGE, LXPY, PERCENTAGE_PER_X_UNITS)
- discountValue (string): Valor del descuento (en %)
- promotionName (string): Nombre de la promoción
- progressiveDiscount (object, opcional): Descuento progresivo
  - quantityToBuy (number): Cantidad a comprar
  - quantityToPay (number): Cantidad a pagar
- error (string, opcional): Detalle del error (retornado solo cuando status = ERROR)
pagination (object): Información de paginación
- nextOffset (integer): Valor del próximo offset
- 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

Promociones en pedidos

Promociones aplicadas aparecen en GET /orders/{id}/virtual-bag:Cómo identificar promociones de su tienda:

Beneficios en benefit.benefits
Filtre por target = ITEM
Filtre por sponsorships con 1 elemento donde liability = PARTNER o CHAIN

Calcular valor con descuento:

Obtenga targetId del beneficio
Correlacione con bag.items[].uniqueId
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: