Referência de campos do produto

Use esta referência para decidir qual campo alterar em um produto. Para autenticação, exemplos de chamadas e edição em lote, veja Gerenciar produtos.

Os campos de identificação, preço, disponibilidade e comportamento abaixo são aceitos na criação (POST /v1/products) e na edição individual ou em lote (PUT /v1/products/{productId} e PUT /v1/products/bulk). Campos fiscais e controle de concorrência são exclusivos da edição.

Como enviar os valores

Envie preços como números JSON, com ponto decimal e até duas casas, por exemplo 28.90. A resposta usa strings com duas casas, como "28.90". Converta os valores retornados antes de reutilizá-los em uma escrita; não envie "R$ 28,90" nem copie o objeto de resposta inteiro como corpo de edição.

Identificação

name

string · obrigatório na criação · até 255 caracteres

Nome do produto usado no cardápio e na operação. Espaços nas extremidades são removidos; um nome vazio ou composto apenas de espaços é rejeitado. O nome não é um identificador único: use o id para sincronizar ou editar produtos.

product_category_id

integer positivo · obrigatório na criação

Identificador de uma categoria não removida do mesmo restaurante. Consulte as categorias em GET /v1/products ou GET /v1/menu; a criação de categorias não faz parte destas rotas de produtos.

A categoria tem suas próprias disponibilidades. Em /v1/menu com only_available=true, produto e categoria precisam estar disponíveis no canal consultado. Uma categoria indisponível pode receber um produto, mas isso não faz o produto aparecer no menu filtrado.

Ao enviar este campo na edição, o produto é posicionado ao final da categoria destino e passa a usar a marca vinculada a ela. Verifique também as configurações de impressão e KDS associadas à categoria no painel.

description

string | null · até 255 caracteres · padrão null

Texto descritivo para apresentar o produto no cardápio e na tela de detalhes. Não substitui o nome. Envie null para limpar ou omita para manter a descrição atual na edição.

Preços e promoções

price

number · obrigatório na criação · até duas casas decimais

Preço base do presencial (mesa, balcão e comanda) e último fallback do delivery. A criação exige um valor maior que zero. Na edição, zero é aceito; valores negativos são rejeitados.

O valor não inclui complementos, entrega ou taxa de serviço. Para produtos vendidos por peso, representa o preço por quilo.

price_promotion

number | null · maior ou igual a zero · até duas casas · padrão null

Preço promocional do presencial. Substitui price; não é um percentual nem um valor a subtrair. Por exemplo, price: 30 e price_promotion: 25 resultam em preço efetivo de "25.00" no canal in_store.

Envie null para encerrar a promoção. Zero é um preço promocional válido e não é interpretado como ausência de promoção. A API não exige que a promoção seja menor que o preço base; valide essa intenção na sua integração.

delivery_price

number | null · maior ou igual a zero · até duas casas · padrão null

Preço específico do delivery e da retirada pelo fluxo de delivery. Permite manter um valor diferente do presencial. Com null, o menu V1 usa price quando não existe promoção de delivery; com 0, usa preço zero.

delivery_price_promotion

number | null · maior ou igual a zero · até duas casas · padrão null

Preço promocional do delivery. Tem prioridade sobre delivery_price. Envie null para encerrar essa promoção sem alterar os demais preços.

Qual preço o menu V1 retorna?

GET /v1/menu resolve pricing.resolved.base usando o primeiro valor não nulo dos preços configurados abaixo (no menu, eles ficam agrupados em pricing):

Alterar o preço base não remove uma promoção existente. Se a intenção for trocar o preço praticado e encerrar a promoção, envie os dois campos:

{ "price": 32.9, "price_promotion": null }

Os preços próprios do iFood não são editáveis por estas rotas. Não trate uma alteração de delivery_price como uma atualização do catálogo do iFood.

Disponibilidade e esgotamento

Os três campos são independentes. Disponibilidade configura em qual canal o produto é vendido; esgotamento informa que ele acabou temporariamente.

Para pausar apenas um canal, use PATCH /v1/products/{productId}/availability. Essa rota aceita somente available e available_in_delivery, e exige pelo menos um deles.

Para marcar que acabou, use a edição individual ou em lote:

{ "sold_off": true }

Para repor, envie sold_off: false. Isso não reativa um canal cuja disponibilidade esteja false. O campo é um indicador, não uma quantidade de estoque; estas rotas não controlam saldo nem programam reposição automática.

Comportamento de venda

use_weight

boolean · padrão false

Indica venda por peso. O preço é por quilo, não por unidade: por exemplo, R$ 60,00/kg e 0,250 kg correspondem a R$ 15,00 antes de adicionais e taxas. A integração precisa coletar e tratar o peso no fluxo de pedido.

pricing.resolved.base representa o preço do canal por quilo; o menu não recebe peso nem calcula o total da porção. Não envie peso ou quantidade como campo da edição do produto.

has_starting_price

boolean · padrão false

Sinaliza a apresentação “a partir de”, útil quando o valor final depende de escolhas de complementos, como tamanho ou sabor. Não cria complementos, não define desconto e não altera os quatro campos de preço.

No menu V1, pricing.resolved.base considera a prioridade dos preços do canal; pricing.resolved.minimum soma a combinação válida mais barata das escolhas obrigatórias. O cálculo independe de has_starting_price. Leia complement_categories e pricing.mode para apresentar as escolhas. pricing.is_combo é uma informação separada e não é editável por estas rotas; não presuma que alterar has_starting_price transforma o produto em combo.

charge_service_tax

boolean · padrão true

Indica se o item participa da base de cálculo da taxa de serviço no presencial. Só tem efeito quando o restaurante e a comanda aplicam essa taxa. false exclui o item dessa base; não desativa a taxa dos demais produtos.

O campo não define o percentual e não acrescenta taxa a price ou pricing.resolved.base. Não representa taxa de entrega.

Campos exclusivos da edição

expected_updated_at

string em formato de data/hora ISO 8601 · opcional

Copie o updated_at retornado por GET /v1/products/{productId} para impedir que uma edição sobrescreva mudanças feitas desde a consulta. Não gere um horário novo no cliente. Em caso de diferença, a API retorna 409 product_update_conflict; consulte novamente e revise a alteração.

No lote, cada objeto pode levar sua própria versão. Um conflito impede a aplicação de todo o lote. O campo sozinho não constitui uma alteração válida.

fiscal_info

object · opcional · apenas no PUT individual ou em lote

Permite editar parcialmente os atributos fiscais já expostos no schema da edição. Os valores são strings ou null, inclusive atributos que representam alíquotas. Envie null em um atributo para limpá-lo; não envie fiscal_info: null. Atributos omitidos permanecem intactos.

O identificador interno fiscal_group_id não é exposto nem editável. Consulte Informações fiscais do produto para o objeto de resposta fiscal e a explicação de cada atributo. fiscal_info: {} sozinho não constitui alteração. Use os dados definidos pelo responsável fiscal do restaurante; a aceitação do corpo pela API não comprova a correção tributária dos valores.

Padrões na criação

Além dos campos obrigatórios (name, product_category_id, price), os valores omitidos assumem:

Esses padrões valem para criação. Em edição, omitir mantém o valor salvo; não restaura o padrão.

O produto não aparece ou tem um valor inesperado

Categorias de embalagem, espelhos internos do iFood e registros removidos não aparecem em /v1/menu, mesmo com only_available=false. Imagens, horários, agendamento, configuração de combos, vínculos de complementos e preços do iFood não são editáveis por estas rotas de produtos. Gerencie essas configurações no painel do restaurante.