Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Catálogo

Crie e gerencie o cardápio da sua loja no iFood via API. A API de Catálogo sincroniza categorias, itens e complementos em tempo real com Entrega, Cardápio Digital e Consumo no Local, com preços e disponibilidade independentes por canal.Se você está integrando um POS existente, use a API para espelhar seu cardápio no iFood e manter preços, status e estoque atualizados em todas as plataformas.

Antes de começar

Você precisa de:

merchantId — ID da sua loja, fornecido no onboarding.
accessToken — Token Bearer para autenticação. Veja Autenticação para obter o seu.

Nos exemplos abaixo, substitua YOUR_MERCHANT_ID e YOUR_ACCESS_TOKEN pelos seus valores.

Começar agora

Siga os 5 passos práticos abaixo para criar seu primeiro catálogo, categoria, item e complementos. Para conceitos detalhados, consulte Como funciona.

Passo 1: Listar seus catálogos

Toda loja já tem pelo menos um catálogo criado. Liste-os para obter o catalogId que você usará nos próximos passos:

curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/catalogs' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Guarde o catalogId retornado.

Passo 2: Criar uma categoria

Crie uma categoria dentro do catálogo com POST /categories. O campo template define o tipo de categoria — use DEFAULT para itens comuns (lanches, bebidas, sobremesas); use PIZZA para estruturas especiais de pizza.

curl --request POST \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/categories' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Lanches",
    "status": "AVAILABLE",
    "template": "DEFAULT"
  }'

Guarde o id retornado — você usará como categoryId no próximo passo.

Passo 3: Criar um item

Crie um item com PUT /items usando o categoryId retornado no Passo 2.

Hierarquia do payload

Antes de criar, compreenda a estrutura aninhada do payload de PUT /items:

item             → metadados do item (id, preço, status, categoryId)
├── products     → produtos usados no item e nos complementos
├── optionGroups → grupos de complementos (bebidas, tamanhos)
└── options      → opções dentro dos grupos (Coca-Cola, Suco)

Todos os quatro campos são sempre enviados, mesmo que optionGroups e options estejam vazios.

Geração e padrão de IDs

Os campos id (para itens, produtos e opções) são gerados por você e devem seguir o padrão UUID v4. Cada id deve ser único dentro do merchant.Se você enviar um id que não esteja no formato UUID v4, a API retornará um erro 404. Exemplos de UUIDs v4 válidos:

550e8400-e29b-41d4-a716-446655440000
123e4567-e89b-12d3-a456-426614174000

O campo externalCode é seu identificador customizado para integração com o POS. Diferentemente do id, o externalCode não precisa seguir o padrão UUID — é uma string arbitrária que você controla. Mantenha um padrão consistente nele. Exemplos válidos:

BURGER_001, COKE_001, COLDRINK_GROUP
xburger-default, frappuccino-grande

Esses IDs são essenciais: você os usará para referenciar o item em atualizações futuras.

O `id` deve ser UUID v4 (obrigatório). O `externalCode` é opcional mas recomendado para facilitar a sincronização bidirecional com seu POS e evitar duplicatas. Não envie um `id` em outro formato — você receberá um erro `404`.

curl --request PUT \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "item": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "DEFAULT",
      "categoryId": "YOUR_CATEGORY_ID",
      "status": "AVAILABLE",
      "price": {"value": 25.00},
      "externalCode": "BURGER_001"
    },
    "products": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "X-Burger",
        "description": "Pão, carne, queijo e alface",
        "externalCode": "BURGER_PROD_001"
      }
    ],
    "optionGroups": [],
    "options": []
  }'

O item aparece no app do iFood imediatamente.

Passo 4: Adicionar complementos

PUT /items é idempotente: cada chamada substitui o item inteiro. Para adicionar complementos (bebidas, tamanhos, extras), reenvie a estrutura completa do item com os campos optionGroups e options preenchidos. Exemplo de complemento mostrando grupos de add-on e preços

Exemplo de complemento mostrando grupos de add-on e preços

curl --request PUT \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "item": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "DEFAULT",
      "categoryId": "YOUR_CATEGORY_ID",
      "status": "AVAILABLE",
      "price": {"value": 25.00},
      "externalCode": "BURGER_001"
    },
    "products": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "X-Burger",
        "description": "Pão, carne, queijo e alface",
        "externalCode": "BURGER_PROD_001",
        "optionGroups": [
          {"id": "550e8400-e29b-41d4-a716-446655440010", "min": 0, "max": 1}
        ]
      },
      {"id": "550e8400-e29b-41d4-a716-446655440002", "name": "Coca-Cola"},
      {"id": "550e8400-e29b-41d4-a716-446655440003", "name": "Suco natural"}
    ],
    "optionGroups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "name": "Escolha uma bebida",
        "status": "AVAILABLE",
        "optionGroupType": "OFFER_UNIT",
        "optionIds": ["550e8400-e29b-41d4-a716-446655440020", "550e8400-e29b-41d4-a716-446655440021"]
      }
    ],
    "options": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440020",
        "productId": "550e8400-e29b-41d4-a716-446655440002",
        "status": "AVAILABLE",
        "price": {"value": 8.00}
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440021",
        "productId": "550e8400-e29b-41d4-a716-446655440003",
        "status": "AVAILABLE",
        "price": {"value": 12.00}
      }
    ]
  }'

Passo 5: Verificar seu catálogo

Liste os itens da categoria para confirmar que tudo foi salvo:

curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/categories/YOUR_CATEGORY_ID/items' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Você deve ver seu item com os complementos associados.

Checklist

Catálogo e categoria com status AVAILABLE.
Item com price.value definido.
Complementos presentes na resposta do GET (se adicionados).
Item aparece na listagem da categoria.

Solução de problemas

Se algo não funcionar como esperado:

Item não aparece: Verifique se o item e categoria estão com status: AVAILABLE e se o item tem price.value definido.
Complementos não foram salvos: Use PUT /items (não POST) e sempre resend a estrutura completa com optionGroups e options.
Erro 409 Conflict: O externalCode é único por merchant. Use um código diferente ou atualizar um item existente pelo seu id.

Próximos passos

Seu catálogo está pronto. O próximo passo depende de seu caso:

Entender o fluxo completo — Como funciona mostra quando chamar cada endpoint e a hierarquia de dados.
Consulta de referência — Fundamentos documenta cada campo e seus tipos.
Estruturas especiais — Veja Pizza ou Combo se vender essas estruturas.
Múltiplos canais — Aprenda a usar contextModifiers e múltiplos contextos em Como funciona.
Erros e soluções — Erros e troubleshooting ajuda a diagnosticar problemas.

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página