Buscar na documentação
ctrl+4K
Módulos
Authentication
Merchant
Catalog
Order
Events
Logistics
Shipping
Review
Financial
Soluções

Endpoints

Referência dos endpoints da Catalog API v2.0.
Teste no Postman
As collections pré-configuradas do Postman cobrem todos os endpoints desta página.

Catálogos

Listar catálogos

Obtenha todos os catálogos da loja e seus contextos.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/catalogs' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Resposta:
[
  {
    "catalogId": "cat-main-001",
    "context": ["DEFAULT"],
    "status": "AVAILABLE",
    "modifiedAt": 1640000000.12345
  }
]

Categorias

Listar categorias

Obtenha todas as categorias. Use o parâmetro include_items=true para incluir itens dentro de cada categoria.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/categories?include_items=true' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Criar categoria

Crie uma categoria para agrupar itens.
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"
  }'
Resposta:
{
  "id": "cat-lanches-001",
  "name": "Lanches",
  "status": "AVAILABLE",
  "template": "DEFAULT"
}

Itens

Criar ou atualizar item

Crie um item completo com produtos, grupos de complementos e opções. Se os IDs já existem, a API atualiza o item. Use contextModifiers para sobrescrever preço, status ou código por contexto.
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": "cat-lanches-001",
      "status": "AVAILABLE",
      "price": {"value": 25.00},
      "externalCode": "BURGER_001",
      "contextModifiers": [
        {
          "catalogContext": "WHITELABEL",
          "price": {"value": 28.00},
          "status": "UNAVAILABLE"
        }
      ]
    },
    "products": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "X-Burger",
        "description": "Pão, carne, queijo e salada",
        "externalCode": "BURGER_PROD_001"
      }
    ],
    "optionGroups": [],
    "options": []
  }'

Listar itens da categoria

Obtenha os itens de uma categoria com seus complementos.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/categories/cat-lanches-001/items' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Obter item específico

Obtenha um item com todos os seus componentes (produto, grupos, opções).
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items/550e8400-e29b-41d4-a716-446655440000/flat' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Listar itens à venda

Obtenha os itens ativos e disponíveis para venda em um catálogo.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/catalogs/cat-main-001/sellableItems' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Listar itens não vendíveis

Obtenha itens bloqueados e o motivo de cada um. Use este endpoint para diagnosticar por que um item não aparece no app.Restrições possíveis:
  • CATEGORY_PAUSED — Categoria pausada.
  • ITEM_PAUSED — Item pausado.
  • ITEM_PRICE_MISSING — Item sem preço.
  • OPTION_GROUP_WITHOUT_AVAILABLE_OPTIONS — Grupo obrigatório sem opções disponíveis.
  • OPTION_PAUSED — Complemento pausado.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/catalogs/cat-main-001/unsellableItems' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Atualizar preço de item

Mude o preço de um item globalmente ou por contexto.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items/price' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemId": "550e8400-e29b-41d4-a716-446655440000",
    "price": {"value": 26.00},
    "priceByCatalog": [
      {
        "value": 29.00,
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Atualizar status de item

Pause ou reative um item globalmente ou por contexto.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items/status' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "AVAILABLE",
    "statusByCatalog": [
      {
        "status": "UNAVAILABLE",
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Atualizar código externo de item

Mude o código POS de um item globalmente ou por contexto.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items/externalCode' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemId": "550e8400-e29b-41d4-a716-446655440000",
    "externalCode": "BURGER_NEW_001",
    "externalCodeByCatalog": [
      {
        "externalCode": "BURGER_WL_001",
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Complementos

Atualizar preço de complemento

Mude o preço de uma opção globalmente ou por contexto.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/options/price' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "optionId": "opt-coke-001",
    "price": {"value": 8.50},
    "priceByCatalog": [
      {
        "value": 9.00,
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Atualizar status de complemento

Pause ou reative uma opção de complemento.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/options/status' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "optionId": "opt-coke-001",
    "status": "UNAVAILABLE",
    "statusByCatalog": [
      {
        "status": "AVAILABLE",
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Atualizar código externo de complemento

Mude o código POS de uma opção.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/options/externalCode' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "optionId": "opt-coke-001",
    "externalCode": "COKE_NEW_001",
    "externalCodeByCatalog": [
      {
        "externalCode": "COKE_WL_001",
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Operações em lote

Atualizar preços em lote

Atualize preços de itens e complementos em lote. Use externalCode ou productId para identificar recursos. Inclua catalogContext para atualizar apenas um contexto específico.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/products/price' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "externalCode": "BURGER_001",
      "price": {"value": 27.00},
      "resources": ["ITEM"]
    }
  ]'
Resposta:
{
  "batchId": "batch-id-001",
  "url": "/v2.0/merchants/YOUR_MERCHANT_ID/batch/batch-id-001"
}

Atualizar status em lote

Atualize status de itens e complementos em lote.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/products/status' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "externalCode": "BURGER_001",
      "status": "UNAVAILABLE",
      "resources": ["ITEM"]
    }
  ]'

Verificar status de operação em lote

Acompanhe o progresso de uma operação em lote. Operações de lote rodam de forma assíncrona — consulte este endpoint até batchStatus ser COMPLETED.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/batch/batch-id-001' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Resposta:
{
  "batchStatus": "COMPLETED",
  "results": [
    {
      "resourceId": "resource-id-001",
      "result": "SUCCESS"
    }
  ]
}

Inventário

Criar inventário

Defina a quantidade máxima vendível de um produto.
curl --request POST \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/inventory' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "productId": "prod-cake-001",
    "quantity": 10
  }'

Obter inventário

Obtenha o inventário atual de um produto.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/inventory/prod-cake-001' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Resposta:
{
  "productId": "prod-cake-001",
  "quantity": 8
}

Deletar inventário

Remove o limite de inventário de um ou mais produtos.
curl --request POST \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/inventory/batchDelete' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "productIds": ["prod-cake-001"]
  }'

Imagens

Upload de imagem

Envia uma imagem em base64. Formatos suportados: jpg, jpeg, png. Tamanho máximo: 5 MB.
curl --request POST \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/image/upload' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }'
Resposta:
{
  "imagePath": "merchant-id/202311161149_abc123.png"
}
Você pode reutilizar o imagePath em múltiplos itens e produtos. Endpoints PUT e POST também aceitam imagens em base64 diretamente no payload.

Tratamento de erros

Veja Erros e troubleshooting para a referência completa de códigos HTTP, diagnóstico de problemas comuns e boas práticas.
Esta página foi útil?
Avalie sua experiência no novo Developer portal:
Nesta página
Endpoints
Catálogos
Listar catálogos
Categorias
Listar categorias
Criar categoria
Itens
Criar ou atualizar item
Listar itens da categoria
Obter item específico
Listar itens à venda
Listar itens não vendíveis
Atualizar preço de item
Atualizar status de item
Atualizar código externo de item
Complementos
Atualizar preço de complemento
Atualizar status de complemento
Atualizar código externo de complemento
Operações em lote
Atualizar preços em lote
Atualizar status em lote
Verificar status de operação em lote
Inventário
Criar inventário
Obter inventário
Deletar inventário
Imagens
Upload de imagem
Tratamento de erros
Conteúdo lido0%