Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Endpoints

Referência técnica completa da API de Promotion. Todos os endpoints requerem autenticação JWT e retornam JSON.

Base URL

https://merchant-api.ifood.com.br/promotion/v1.0

Autenticação

Todos os endpoints requerem token OAuth 2.0 no header Authorization:

Authorization: Bearer {JWT_TOKEN}

O token deve ser incluído em todas as requisições. Se o token expirar ou for inválido, a API retornará 401 Unauthorized.Para detalhes sobre autenticação e gerenciamento de tokens, consulte a documentação de autenticação.

Operações disponíveis

Método	Endpoint	Descrição
`POST`	`/merchants/{merchantId}/promotions`	Criar promoções
`POST`	`/merchants/{merchantId}/promotions?reset=true`	Substituir todas as promoções
`GET`	`/merchants/{merchantId}/promotions/{aggregationId}/items`	Consultar status das promoções

Criar promoções

Cria novas promoções para uma loja. As promoções ficam ativas até a data final especificada.

POST /merchants/{merchantId}/promotions

Comportamento

Novas requisições adicionam-se às promoções existentes. Para substituir completamente todas as promoções, use o parâmetro de query reset=true.

Parâmetros de path

Parâmetro	Tipo	Descrição
`merchantId`	uuid	ID único da loja

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
`reset`	boolean	`false`	Quando `true`, substitui completamente todas as promoções existentes

Campos do corpo da requisição

Campo raiz

Campo	Tipo	Obrigatório	Descrição
`aggregationTag`	string	Não	Identificador customizado para rastreamento. Deve ser único.
`promotions`	array	Sim	Lista contendo as promoções a criar

Objeto de promoção: `promotions[]`

Campo	Tipo	Obrigatório	Descrição
`promotionName`	string	Não	Nome descritivo da promoção (máx. 255 caracteres)
`channels`	array	Sim	Lista de canais de venda (ex: `IFOOD-APP`)
`items`	array	Sim	Lista de itens a promover

Objeto de item: `promotions[].items[]`

Campo	Tipo	Obrigatório	Descrição
`ean`	string	Sim	Código EAN do produto (formato UPC-A, 12 dígitos)
`discountValue`	number	Condicional	Percentual de desconto (0-70). Obrigatório para `PERCENTAGE` e `PERCENTAGE_PER_X_UNITS`
`initialDate`	string	Sim	Data de início em formato ISO 8601 (`YYYY-MM-DD`)
`finalDate`	string	Sim	Data de término em formato ISO 8601 (`YYYY-MM-DD`)
`promotionType`	string	Sim	Tipo de promoção: `PERCENTAGE`, `LXPY` ou `PERCENTAGE_PER_X_UNITS`
`progressiveDiscount`	object	Condicional	Configuração para promoções de tipo `LXPY` ou `PERCENTAGE_PER_X_UNITS`

Objeto de desconto progressivo: `progressiveDiscount`

Campo	Tipo	Obrigatório	Descrição
`quantityToBuy`	integer	Condicional	Quantidade de itens que o cliente deve comprar (mín. 2)
`quantityToPay`	integer	Condicional	Quantidade de itens que o cliente paga (apenas para `LXPY`)

Regras de validação

Campos obrigatórios por tipo de promoção

Tipo	Campos obrigatórios
`PERCENTAGE`	`discountValue`
`LXPY`	`progressiveDiscount.quantityToBuy`, `progressiveDiscount.quantityToPay`
`PERCENTAGE_PER_X_UNITS`	`discountValue`, `progressiveDiscount.quantityToBuy`

Restrições de valor

Limite máximo de desconto: O desconto não pode exceder 70% do preço de catálogo. Requisições com descontos superiores serão rejeitadas com erro DISCOUNT_INVALID.

Restrições de data

initialDate deve ser anterior a finalDate
Ambas devem estar em formato YYYY-MM-DD
Datas retroativas são permitidas (para promoções já iniciadas)

Exemplos de requisição

PERCENTAGE — Desconto percentual

Aplica um desconto percentual fixo no preço do item.Cenário: Promover um item com desconto de 20%. Cliente paga R$ 8,00 em um item de R$ 10,00.

{
  "aggregationTag": "promo-percentage",
  "promotions": [
    {
      "promotionName": "Desconto 20%",
      "channels": ["IFOOD-APP"],
      "items": [
        {
          "ean": "7891234567890",
          "discountValue": 20.0,
          "initialDate": "2026-02-01",
          "finalDate": "2026-02-28",
          "promotionType": "PERCENTAGE"
        }
      ]
    }
  ]
}

LXPY — Leve X Pague Y

Aplica desconto em combo baseado em quantidade: cliente leva X unidades e paga apenas Y.Cenário: "Leve 3, Pague 2" em um item de R$ 10,00. Cliente gasta R$ 20,00 por 3 unidades.

{
  "aggregationTag": "promo-lxpy",
  "promotions": [
    {
      "promotionName": "Leve 3 Pague 2",
      "channels": ["IFOOD-APP"],
      "items": [
        {
          "ean": "7891234567890",
          "discountValue": null,
          "initialDate": "2026-02-01",
          "finalDate": "2026-02-28",
          "promotionType": "LXPY",
          "progressiveDiscount": {
            "quantityToBuy": 3,
            "quantityToPay": 2
          }
        }
      ]
    }
  ]
}

PERCENTAGE_PER_X_UNITS — Desconto na Nª unidade

Aplica desconto percentual progressivo a partir de uma quantidade específica.Cenário: 50% de desconto na terceira unidade. Cliente gasta R$ 10 + R$ 10 + R$ 5 = R$ 25,00 por 3 unidades.

{
  "aggregationTag": "promo-progressive",
  "promotions": [
    {
      "promotionName": "50% na 3ª unidade",
      "channels": ["IFOOD-APP"],
      "items": [
        {
          "ean": "7891234567890",
          "discountValue": 50.0,
          "initialDate": "2026-02-01",
          "finalDate": "2026-02-28",
          "promotionType": "PERCENTAGE_PER_X_UNITS",
          "progressiveDiscount": {
            "quantityToBuy": 3
          }
        }
      ]
    }
  ]
}

Resposta de sucesso

A API retorna HTTP 202 Accepted, indicando que a requisição foi recebida para processamento assíncrono.

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

Campo	Tipo	Descrição
`aggregationId`	string	Identificador único da requisição. Use este valor para consultar o status do processamento
`message`	string	Confirmação legível da recepção da requisição

Interpretando a resposta HTTP 202

Processamento assíncronoO status HTTP 202 confirma apenas que a requisição foi recebida e enfileirada para processamento. Não indica que as promoções foram criadas com sucesso. As validações ocorrem de forma assíncrona no backend.Para verificar o status real, use o endpoint GET com o aggregationId retornado.

Substituir promoções (reset)

Substitui completamente todas as promoções ativas da loja com o novo conjunto fornecido.

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

Comportamento da operação reset

Quando você usa reset=true, a API executa as seguintes ações:

Ação	Item	Resultado
Criar	Itens no payload que não existem	Novos itens promocionais são criados
Manter	Itens existentes presentes no novo payload	Itens continuam ativos com os parâmetros atualizados
Desativar	Itens existentes ausentes do novo payload	Itens são marcados como `FINISHING` e removidos

Quando usar reset

Sincronizar completamente o estado de promoções com um sistema externo
Remover todas as promoções ativas de uma loja
Garantir que apenas o conjunto especificado esteja ativo

Quando NÃO usar reset

Evite reset=true nos seguintes cenários:

Se você apenas quer adicionar novas promoções (use POST sem o parâmetro)
Durante horários de pico de vendas na loja
Sem ter validado o payload completo internamente
Se a loja tem mais de 10.000 itens promocionais

Boas práticas para reset

Aspecto	Recomendação
Frequência	Executar preferencialmente uma vez por dia
Horário	Escolher horários fora do pico de vendas (ex: 2h-6h)
Limite	Máximo 10.000 itens promocionais por requisição
Validação	Validar o payload localmente antes de enviar
Rastreamento	Usar `aggregationTag` com timestamp para auditoria

Exemplo de timing seguro

# Agendar reset para as 3h da madrugada
0 3 * * * curl -X POST "https://merchant-api.ifood.com.br/promotion/v1.0/merchants/{merchantId}/promotions?reset=true" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '@promotions.json'

Consultar status das promoções

Retorna detalhes dos itens de promoção com suporte a filtros e paginação.

GET /merchants/{merchantId}/promotions/{aggregationId}/items

Parâmetros de path

Parâmetro	Tipo	Descrição
`merchantId`	uuid	ID único da loja
`aggregationId`	string	ID retornado na criação (do campo `aggregationId` da resposta 202)

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
`ean`	string	-	Filtrar por código EAN do produto
`promotionName`	string	-	Filtrar por nome da promoção
`promotionType`	string	-	Filtrar por tipo (`PERCENTAGE`, `LXPY`, `PERCENTAGE_PER_X_UNITS`)
`status`	string	-	Filtrar por status (ex: `ACTIVE`, `ERROR`, `PROCESSING`)
`offset`	integer	0	Número de itens a pular (para paginação)
`limit`	integer	100	Número máximo de itens a retornar (máximo: 1000)

Exemplo de requisição

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

Resposta de sucesso (HTTP 200)

{
  "promotions": [
    {
      "promotionItemId": "005f5ea0-1ff4-4c9b-9f48-76d94bfe4694",
      "ean": "7891234567890",
      "status": "ACTIVE",
      "initialDate": "2026-02-01",
      "finalDate": "2026-02-28",
      "promotionType": "LXPY",
      "promotionName": "Leve 3 Pague 2",
      "progressiveDiscount": {
        "quantityToBuy": 3,
        "quantityToPay": 2
      },
      "error": null
    }
  ],
  "pagination": {
    "nextOffset": 10,
    "currentOffset": 0
  }
}

Campo	Tipo	Descrição
`promotions`	array	Lista de itens promocionais
`promotions[].promotionItemId`	string	ID único do item promocional
`promotions[].ean`	string	Código EAN do produto
`promotions[].status`	string	Status atual da promoção (veja tabela abaixo)
`promotions[].initialDate`	string	Data de início em formato ISO 8601
`promotions[].finalDate`	string	Data de término em formato ISO 8601
`promotions[].promotionType`	string	Tipo de promoção
`promotions[].promotionName`	string	Nome descritivo da promoção
`promotions[].progressiveDiscount`	object	Configuração de desconto (se aplicável)
`promotions[].error`	string ou null	Mensagem de erro detalhada (se status = `ERROR`)
`pagination.nextOffset`	integer	Offset para a próxima página (se houver mais resultados)
`pagination.currentOffset`	integer	Offset atual

Estados de promoção

Status	Significado	Ação esperada
`PROCESSING`	Requisição recebida e em validação no backend	Aguardar conclusão da validação
`SCHEDULED`	Validação passou, aguardando `initialDate`	Nenhuma ação necessária
`ACTIVE`	Promoção ativa e pronta para uso	Verificar aplicação em pedidos
`DUPLICATE`	Outro item com mesmo EAN e período já existe	Remover duplicação e reenviar
`FINISHING`	Remoção em progresso (após reset ou exclusão)	Aguardar transição para `FINISHED`
`FINISHED`	Remoção concluída com sucesso	Verificar próximos passos
`ERROR`	Erro na validação ou processamento	Consultar campo `error` para detalhes

Status ACTIVE e visibilidade

Um status ACTIVE significa que a promoção foi validada e cadastrada no sistema. No entanto, isso não garante que a promoção apareça no app do cliente.Uma promoção ativa pode não ser visível nos seguintes casos:

Outra promoção ativa com maior prioridade está configurada para o mesmo item
Configurações de negócio da loja limitam a quantidade de promoções simultâneas por item
Filtros de elegibilidade aplicados no nível do app excluem o item ou cliente

Para confirmar se uma promoção está sendo efetivamente aplicada, consulte o endpoint de detalhes do pedido e verifique se o desconto aparece nos benefícios (bag.benefits.benefits[]).

Monitoramento de processamento

Como o processamento é assíncrono, siga esta estratégia:

Logo após criar (POST 202): Aguarde 2-3 segundos antes de consultar
Ainda em PROCESSING: Aguarde mais alguns segundos e repita
Transição para ACTIVE: Promoção está pronta
Status ERROR: Verifique o campo error para detalhes da falha

Verificar promoções em pedidos

Promoções aprovadas aparecem automaticamente nos pedidos do cliente. Para validar se a sua promoção foi corretamente aplicada, use o endpoint de detalhes do pedido.

Acessar dados da promoção em um pedido

Consulte GET /orders/{id}/virtual-bag para obter a composição completa do pedido, incluindo benefícios aplicados.Referência: Módulo Order - Detalhes do Pedido

Identificar descontos da sua loja

Para validar se um desconto foi aplicado corretamente:

Navegue até bag.benefits.benefits[] na resposta
Filtre onde target = ITEM
Identifique benefícios onde sponsorships[].liability é PARTNER ou CHAIN

Estes são benefícios cuja responsabilidade é sua (partner ou chain).

Calcular o valor final do item com desconto

Localize o targetId no benefício
Correlacione com bag.items[].uniqueId para identificar o item
Subtraia sponsorships[].amount.value de prices.grossValue.value

Resultado: preço_final = preço_bruto - desconto_aplicado

Próximos passos

Como funciona — Reset, processamento assíncrono, estratégia
Erros e troubleshooting — Diagnóstico de problemas
Homologação — Prepare para produção

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Endpoints

Base URL

Autenticação

Operações disponíveis

Criar promoções

Comportamento

Parâmetros de path

Parâmetros de query

Campos do corpo da requisição

Campo raiz

Objeto de promoção: promotions[]

Objeto de item: promotions[].items[]

Objeto de desconto progressivo: progressiveDiscount

Regras de validação

Campos obrigatórios por tipo de promoção

Restrições de valor

Restrições de data

Exemplos de requisição

PERCENTAGE — Desconto percentual

LXPY — Leve X Pague Y

PERCENTAGE_PER_X_UNITS — Desconto na Nª unidade

Resposta de sucesso

Interpretando a resposta HTTP 202

Substituir promoções (reset)

Comportamento da operação reset

Quando usar reset

Quando NÃO usar reset

Boas práticas para reset

Exemplo de timing seguro

Consultar status das promoções

Parâmetros de path

Parâmetros de query

Exemplo de requisição

Resposta de sucesso (HTTP 200)

Estados de promoção

Status ACTIVE e visibilidade

Monitoramento de processamento

Verificar promoções em pedidos

Acessar dados da promoção em um pedido

Identificar descontos da sua loja

Calcular o valor final do item com desconto

Próximos passos

Objeto de promoção: `promotions[]`

Objeto de item: `promotions[].items[]`

Objeto de desconto progressivo: `progressiveDiscount`