Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Promotion

Gerencie promoções de produtos em sua loja com diferentes mecânicas de desconto. Crie, rastreie e controle campanhas promocionais em tempo real.A Promotion API permite integrar seu sistema de promoções com a plataforma iFood, oferecendo desconto percentual, combos (Leve X Pague Y) e descontos progressivos.

Acesso ao módulo

Módulo restrito a integrações existentesNovos parceiros devem usar o módulo Item para mecânicas simples (DE-POR e Atacarejo).

Acesso exclusivo: Este módulo está disponível apenas para mercados. Solicite acesso ao nosso time.

Principais funcionalidades

A Promotion API oferece:

Criar promoções com diferentes tipos de desconto
Consultar status do processamento assíncrono
Substituir campanhas completas com operação reset
Monitorar descontos em pedidos em tempo real

Tipos de promoção

A API suporta três mecânicas de desconto:

Tipo	Descrição	Exemplo
`PERCENTAGE`	Desconto percentual simples	20% de desconto em um item
`LXPY`	Promoção por quantidade	"Leve 3, Pague 2"
`PERCENTAGE_PER_X_UNITS`	Desconto em unidades progressivas	50% na terceira unidade

Quick start

Passo 1: Escolha o tipo de promoção

Selecione a mecânica de desconto que se adequa à sua estratégia:

PERCENTAGE para descontos simples
LXPY para estratégias de combo e volume
PERCENTAGE_PER_X_UNITS para incentivos progressivos

Passo 2: Prepare a requisição

{
  "aggregationTag": "promo-001",
  "promotions": [
    {
      "promotionName": "Desconto de Verão",
      "channels": ["IFOOD-APP"],
      "items": [
        {
          "ean": "7891234567890",
          "discountValue": 20.0,
          "initialDate": "2026-02-01",
          "finalDate": "2026-02-28",
          "promotionType": "PERCENTAGE"
        }
      ]
    }
  ]
}

Passo 3: Envie a requisição

curl -X POST "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{merchantId}/promotions" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Você receberá resposta 202 Accepted com um aggregationId para rastreamento.

Conceitos essenciais

Processamento assíncrono

Todos os endpoints retornam 202 Accepted, mas o processamento é assíncrono:

Você envia requisição → API retorna 202 imediatamente
Sistema enfileira sua requisição
Processamento ocorre nos próximos segundos
Consulte com aggregationId para verificar status

Status de promoção

Status	Significado
`PROCESSING`	Requisição em validação
`SCHEDULED`	Validação passou, aguardando data de início
`ACTIVE`	Promoção ativa e pronta
`ERROR`	Erro na validação ou processamento
`DUPLICATE`	Outro item com mesmo EAN já existe
`FINISHING`	Remoção em progresso
`FINISHED`	Remoção concluída

Campo `aggregationTag`

Use aggregationTag para rastreamento customizado. Deve ser único por requisição:

{
  "aggregationTag": "verão-2026-001",
  "promotions": [ ... ]
}

Próximos passos

Como funcionaEntenda reset, processamento assíncrono e estratégia de integração.

Erros e troubleshootingDiagnóstico e soluções para problemas comuns.

EndpointsReferência técnica completa com todos os endpoints.

HomologaçãoPrepare sua integração para produção.

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página