Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Promotion

O módulo de Promotions está restrito a integrações existentes. Novos parceiros devem usar o módulo Item para mecânicas de promoções simples. Saiba mais aqui

O módulo Promotion permite criar e gerenciar promoções de produtos em sua loja, oferecendo diferentes mecânicas de desconto para atrair e engajar clientes.Principais funcionalidades:

Criar promoções com desconto percentual
Configurar combos "Leve X Pague Y"
Aplicar desconto progressivo por unidade
Agendar período de vigência das promoções
Consultar status e detalhes das promoções ativas

Módulo exclusivoEste módulo é de uso exclusivo de parceiros que operam com mercado e não está disponível para todos os desenvolvedores. Caso tenha interesse em utilizar funções dessa API, entre em contato com o time de atendimento.

Outros tipos de promoçãoAs promoções do tipo DE-POR e ATACAREJO devem ser configuradas pelo módulo Item.

Criação de promoções

Use POST /merchants/{merchantId}/promotions para criar promoções.Descrição: Este endpoint cria novas promoções para uma loja.

Comportamento do endpointEste endpoint adiciona promoções à loja. As promoções ficam ativas até a data final. Novas requisições somam às promoções existentes. Para substituir a lista atual, use ?reset=true. Veja Atualização de promoções.

Exemplo 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": "Promoção teste",
        "channels": ["IFOOD-APP"],
        "items": [
          {
            "ean": "3213434343",
            "discountValue": 20.0,
            "initialDate": "2024-10-23",
            "finalDate": "2024-10-30",
            "promotionType": "PERCENTAGE"
          }
        ]
      }
    ]
  }'

Tipos de promoções

PERCENTAGE - Desconto percentual

Aplica desconto percentual no preço do item.Exemplo: Item de R$ 10,00 com 10% de desconto = R$ 9,00

{
  "aggregationTag": "123456",
  "promotions": [
    {
      "promotionName": "Promoção teste",
      "channels": ["IFOOD-APP"],
      "items": [
        {
          "ean": "3213434343",
          "discountValue": 20.0,
          "initialDate": "2024-10-23",
          "finalDate": "2024-10-30",
          "promotionType": "PERCENTAGE"
        }
      ]
    }
  ]
}

LXPY - Leve X Pague Y

Aplica desconto em combo de itens.Exemplo: Item de R$ 10,00 em combo "Leve 3 Pague 2" = R$ 20,00 total (R$ 6,66 cada)

{
  "aggregationTag": "123456",
  "promotions": [
    {
      "promotionName": "Promoção teste do 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 - Desconto na Nª unidade

Aplica desconto percentual a cada X unidades.Exemplo: Item de R$ 10,00 com 50% na 2ª unidade = R$ 15,00 total (2 unidades)

{
  "aggregationTag": "123456",
  "promotions": [
    {
      "promotionName": "Promoção teste - 50% na 3ª unidade",
      "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 do payload

Campo	Tipo	Obrigatório	Descrição
aggregationTag	String	Não	Identificador customizado da requisição
promotions[].promotionName	String	Não	Nome da promoção
promotions[].channels	Array	Sim	Canais de venda (ex: `IFOOD-APP`)
promotions[].items[].ean	String	Sim	Código EAN do produto
promotions[].items[].discountValue	Double	Condicional	Valor do desconto em %
promotions[].items[].initialDate	Date	Sim	Data de início (formato: `YYYY-MM-DD`)
promotions[].items[].finalDate	Date	Sim	Data de término (formato: `YYYY-MM-DD`)
promotions[].items[].promotionType	String	Sim	Tipo: `PERCENTAGE`, `LXPY` ou `PERCENTAGE_PER_X_UNITS`
progressiveDiscount.quantityToBuy	Integer	Condicional	Quantidade a comprar (LXPY e PERCENTAGE_PER_X_UNITS)
progressiveDiscount.quantityToPay	Integer	Condicional	Quantidade a pagar (apenas LXPY)

Regras de campos por tipo

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

Limite de descontoDescontos máximos permitidos: 70% do preço de catálogo. Itens com desconto superior serão rejeitados.Exemplo não permitido: "Leve 10 Pague 2" = 80% de desconto

Resposta da requisição

Sucesso (HTTP 202)

Campos retornados:

aggregationId (string): ID único para rastreamento da requisição de criação de promoções
message (string): Mensagem de confirmação

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

Processamento assíncronoO status 202 indica que a requisição foi recebida, mas não que as promoções foram criadas. Use o aggregationId para consultar o status real via GET.Recomendação: Valide o status no endpoint GET e confira no App do iFood antes de considerar a promoção ativa.

Erro

HTTP 400/422 - Erro de processamento

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

HTTP 412 - Erro de validação

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

Atualização de promoções

Para substituir todas as promoções ativas da loja, use o parâmetro ?reset=true:

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

Comportamento do reset:

Cria novos itens promocionais
Mantém itens idênticos aos já existentes
Desativa itens não incluídos no novo payload

Recomendações:

Use com moderação (diariamente fora do horário comercial)
Execute apenas quando houver alterações
Limite: máximo 10.000 itens promocionais por payload

Consulta de promoções

Use GET /merchants/{merchantId}/promotions/{aggregationId}/items para consultar status das promoções.Descrição: Retorna detalhes dos itens de promoção com suporte a filtros e paginação.Importante: O processamento é assíncrono. Consultas imediatas após o POST podem retornar lista vazia.

Exemplo 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 disponíveis

Parâmetro	Tipo	Descrição
ean	String	Código EAN do produto
promotionName	String	Nome da promoção
promotionType	String	Tipo da promoção
status	String	Status atual (veja tabela abaixo)
offset	Integer	Posição inicial da listagem
limit	Integer	Itens por página (máximo: 1000)

Status das promoções

Status	Descrição
PROCESSING	Recebido e em validação
SCHEDULED	Validado, aguardando data de início
ACTIVE	Validado e em operação
DUPLICATE	Item promocional duplicado (já enviado anteriormente)
FINISHING	Remoção solicitada, aguardando efetivação
FINISHED	Removido com sucesso
ERROR	Erro detectado (veja campo `error` para detalhes)

Status ACTIVE não garante visibilidadeUma promoção ACTIVE está cadastrada no sistema, mas pode não aparecer no App para todos os usuários devido a:

Outras promoções ativas para o mesmo item
Regras de priorização (mostra o melhor desconto)
Promoções do iFood, indústria ou inseridas via Portal do Parceiro

Resposta da requisição

Sucesso (HTTP 200)

Campos retornados:

promotions (array): Lista de itens de promoção
- promotionItemId (string, UUID): Identificador único do item de promoção
- ean (string): Código EAN do produto
- status (string): Status atual (PROCESSING, ACTIVE, FINISHED, SCHEDULED, FINISHING, ERROR)
- initialDate (string, date): Data de início da promoção
- finalDate (string, date): Data de término da promoção
- promotionType (string): Tipo da promoção (PERCENTAGE, LXPY, PERCENTAGE_PER_X_UNITS)
- discountValue (string): Valor do desconto (em %)
- promotionName (string): Nome da promoção
- progressiveDiscount (object, opcional): Desconto progressivo
  - quantityToBuy (number): Quantidade a comprar
  - quantityToPay (number): Quantidade a pagar
- error (string, opcional): Detalhamento do erro (retornado apenas quando status = ERROR)
pagination (object): Informações de paginação
- nextOffset (integer): Valor do próximo offset
- currentOffset (integer): Valor do offset atual

{
  "promotions": [
    {
      "promotionItemId": "005f5ea0-1ff4-4c9b-9f48-76d94bfe4694",
      "ean": "3213434343",
      "status": "ACTIVE",
      "initialDate": "2024-10-10",
      "finalDate": "2024-10-11",
      "promotionType": "LXPY",
      "promotionName": "Promoção teste do tipo LXPY",
      "progressiveDiscount": {
        "quantityToBuy": 3,
        "quantityToPay": 2
      }
    }
  ],
  "pagination": {
    "nextOffset": 99,
    "currentOffset": 0
  }
}

Códigos de erro

Código	Detalhamento
DATE_INVALID	Verifique formato das datas (`YYYY-MM-DD`) e se `finalDate` > `initialDate`
PROMOTION_TYPE_INVALID	Valores válidos: `PERCENTAGE`, `LXPY`, `PERCENTAGE_PER_X_UNITS`
DISCOUNT_INVALID	Verifique campos obrigatórios para cada tipo e limite de 70% de desconto
ITEM_NOT_FOUND	EAN incorreto ou produto inativo/sem estoque
INTERNAL_ERROR	Entre em contato com o suporte iFood

Promoções em pedidos

Promoções aplicadas aparecem no GET /orders/{id}/virtual-bag:Como identificar promoções da sua loja:

Benefícios em benefit.benefits
Filtre por target = ITEM
Filtre por sponsorships com 1 elemento onde liability = PARTNER ou CHAIN

Calcular valor com desconto:

Obtenha targetId do benefício
Correlacione com bag.items[].uniqueId
Subtraia sponsorships.amount.value de prices.grossValue.value

Próximos passos

Verifique os critérios para realizar sua homologação

Esta página foi útil?

Avalie sua experiência no novo Developer portal: