Combos

Combos são itens com até três níveis de customização: item principal, grupos de opções e customizações por opção. Use este guia para modelar combos na Catalog API v2.0.

Estrutura obrigatória

Todo combo exige:

type: "COMBO_V2" no item.
Um grupo principal com associationType: "MAIN" (apenas um por combo).
optionGroupType definido em todos os grupos.

Sem essas condições, o combo não aparece ao cliente e não é ofertado nas campanhas automáticas do iFood.

Hierarquia dos grupos

Combo hambúrguer e refrigerante (item COMBO_V2)
├── Escolha seu hambúrguer (grupo OFFER_UNIT, associationType: MAIN)
│   ├── Hambúrguer (opção)
│   │   ├── Deseja retirar ingrediente? (grupo INGREDIENTS, 3º nível)
│   │   │   ├── Sem tomate (opção, produto: prod-tomate)
│   │   │   └── Sem alface (opção, produto: prod-alface)
│   │   └── Qual o ponto da carne? (grupo SPECIFICATION, 3º nível)
│   │       ├── Ao ponto (opção, produto: prod-carne-ao-ponto)
│   │       ├── Médio (opção, produto: prod-carne-medio)
│   │       └── Bem-passado (opção, produto: prod-carne-bem-passado)
│   └── Hambúrguer de bacon (opção)
└── Escolha seu refrigerante (grupo OFFER_UNIT)
    ├── Laranja (opção, produto: prod-orange-soda)
    └── Uva (opção, produto: prod-grape-soda)

Apenas grupos do tipo SPECIFICATION e INGREDIENTS aparecem no terceiro nível.

Tipos de grupo

Tipo	Uso	Exemplo
`OFFER_UNIT`	Seleção entre itens	Escolha de hambúrguer
`SPECIFICATION`	Especificação de preparo	Ponto da carne
`INGREDIENTS`	Alteração de ingredientes	Com ou sem cebola
`CUTLERY`	Utensílios	Garfo, faca, guardanapo

Criar um combo

Crie o combo completo com PUT /items. Importante: todos os produtos referenciados em products, productId nas opções, e complementos do terceiro nível devem ser explicitamente definidos no array products — nenhum produto é criado automaticamente.Exemplo completo com um combo que inclui complementos no terceiro nível (ponto da carne e retirada de ingredientes):

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": "item-combo-burger",
      "type": "COMBO_V2",
      "status": "AVAILABLE",
      "externalCode": "combo_burger_001"
    },
    "products": [
      {
        "id": "prod-combo",
        "name": "Combo hamburger e refrigerante",
        "externalCode": "combo_prod_001",
        "optionGroups": [
          {"id": "og-burger-choice", "min": 1, "max": 1, "index": 0, "associationType": "MAIN"},
          {"id": "og-soda-choice", "min": 1, "max": 1, "index": 1}
        ]
      },
      {
        "id": "prod-salad-burger",
        "name": "Hambúrguer",
        "externalCode": "burger_salad",
        "optionGroups": [
          {"id": "og-remove-ingredients", "min": 0, "max": 2, "index": 0},
          {"id": "og-meat-doneness", "min": 0, "max": 1, "index": 1}
        ]
      },
      {"id": "prod-bacon-burger", "name": "Hamburger de bacon", "externalCode": "burger_bacon"},
      {"id": "prod-orange-soda", "name": "Refrigerante de laranja", "externalCode": "soda_orange"},
      {"id": "prod-grape-soda", "name": "Refrigerante de uva", "externalCode": "soda_grape"},
      {"id": "prod-tomate", "name": "Tomate", "externalCode": "ing_tomato"},
      {"id": "prod-alface", "name": "Alface", "externalCode": "ing_lettuce"},
      {"id": "prod-carne-ao-ponto", "name": "Carne ao ponto", "externalCode": "meat_rare"},
      {"id": "prod-carne-medio", "name": "Carne média", "externalCode": "meat_medium"},
      {"id": "prod-carne-bem-passado", "name": "Carne bem-passada", "externalCode": "meat_well_done"}
    ],
    "optionGroups": [
      {
        "id": "og-burger-choice",
        "name": "Escolha seu hamburger",
        "status": "AVAILABLE",
        "optionGroupType": "OFFER_UNIT",
        "optionIds": ["opt-salad", "opt-bacon"]
      },
      {
        "id": "og-soda-choice",
        "name": "Escolha seu refrigerante",
        "status": "AVAILABLE",
        "optionGroupType": "OFFER_UNIT",
        "optionIds": ["opt-orange", "opt-grape"]
      },
      {
        "id": "og-remove-ingredients",
        "name": "Deseja retirar ingrediente?",
        "status": "AVAILABLE",
        "optionGroupType": "INGREDIENTS",
        "optionIds": ["opt-remove-tomato", "opt-remove-lettuce"]
      },
      {
        "id": "og-meat-doneness",
        "name": "Qual o ponto da carne?",
        "status": "AVAILABLE",
        "optionGroupType": "SPECIFICATION",
        "optionIds": ["opt-rare", "opt-medium", "opt-well-done"]
      }
    ],
    "options": [
      {
        "id": "opt-salad",
        "productId": "prod-salad-burger",
        "status": "AVAILABLE",
        "index": 0,
        "price": {"value": 15.00}
      },
      {
        "id": "opt-bacon",
        "productId": "prod-bacon-burger",
        "status": "AVAILABLE",
        "index": 1,
        "price": {"value": 18.00}
      },
      {
        "id": "opt-orange",
        "productId": "prod-orange-soda",
        "status": "AVAILABLE",
        "index": 0,
        "price": {"value": 8.00}
      },
      {
        "id": "opt-grape",
        "productId": "prod-grape-soda",
        "status": "AVAILABLE",
        "index": 1,
        "price": {"value": 8.00}
      },
      {
        "id": "opt-remove-tomato",
        "productId": "prod-tomate",
        "status": "AVAILABLE",
        "price": {"value": 0.00}
      },
      {
        "id": "opt-remove-lettuce",
        "productId": "prod-alface",
        "status": "AVAILABLE",
        "price": {"value": 0.00}
      },
      {
        "id": "opt-rare",
        "productId": "prod-carne-ao-ponto",
        "status": "AVAILABLE",
        "price": {"value": 0.00}
      },
      {
        "id": "opt-medium",
        "productId": "prod-carne-medio",
        "status": "AVAILABLE",
        "price": {"value": 0.00}
      },
      {
        "id": "opt-well-done",
        "productId": "prod-carne-bem-passado",
        "status": "AVAILABLE",
        "price": {"value": 0.00}
      }
    ]
  }'

Resposta:

{
  "id": "item-combo-burger",
  "type": "COMBO_V2",
  "status": "AVAILABLE"
}

Grupo principal

O grupo com associationType: "MAIN" representa o produto central do combo. O iFood usa esse sinal para incluir o combo em campanhas automáticas de cross-sell. Defina apenas um grupo principal por combo — múltiplos MAIN geram erro.

Reutilizar grupos de complementos existentes

Você pode reaproveitar grupos de complementos já criados em outros itens simplesmente alterando o associationType na relação entre o grupo e o produto principal do combo. Isso evita duplicação e mantém a consistência entre itens.Exemplo: Se você já criou um grupo de bebidas (550e8400-e29b-41d4-a716-446655440010) usado em lanches normais, pode reutilizá-lo em um combo apenas incluindo-o na estrutura do combo e definindo o associationType apropriado:

{
  "products": [
    {
      "id": "prod-combo-burger",
      "name": "Combo Hambúrguer e Bebida",
      "optionGroups": [
        {"id": "og-burger-choice", "min": 1, "max": 1, "associationType": "MAIN"},
        {"id": "550e8400-e29b-41d4-a716-446655440010", "min": 1, "max": 1, "associationType": "OFFER_UNIT"}
      ]
    }
  ]
}

O campo associationType define como o grupo relaciona-se com o produto:

MAIN — Grupo principal (apenas um por combo)
OFFER_UNIT — Seleção adicional (venda cruzada)
Não incluir associationType — Padrão para terceiro nível (deve estar vazio)

Ao reutilizar um grupo, o optionGroupType já está definido no grupo original, então você não precisa redefini-lo.

Terceiro nível: customizações por opção

Para permitir customização após a escolha (ex.: escolher o ponto da carne depois de selecionar o hambúrguer), vincule grupos adicionais diretamente ao product da opção:

{
  "products": [
    {
      "id": "prod-salad-burger",
      "name": "Hambúrguer",
      "optionGroups": [
        {"id": "og-remove-ingredients", "min": 0, "max": 2, "index": 0},
        {"id": "og-meat-doneness", "min": 0, "max": 1, "index": 1}
      ]
    }
  ],
  "optionGroups": [
    {
      "id": "og-remove-ingredients",
      "name": "Deseja retirar ingrediente?",
      "status": "AVAILABLE",
      "optionGroupType": "INGREDIENTS",
      "optionIds": ["opt-remove-tomato", "opt-remove-lettuce"]
    },
    {
      "id": "og-meat-doneness",
      "name": "Qual o ponto da carne?",
      "status": "AVAILABLE",
      "optionGroupType": "SPECIFICATION",
      "optionIds": ["opt-rare", "opt-medium", "opt-well-done"]
    }
  ],
  "options": [
    {
      "id": "opt-remove-tomato",
      "productId": "prod-tomate",
      "status": "AVAILABLE",
      "price": {"value": 0.00}
    },
    {
      "id": "opt-remove-lettuce",
      "productId": "prod-alface",
      "status": "AVAILABLE",
      "price": {"value": 0.00}
    },
    {
      "id": "opt-rare",
      "productId": "prod-carne-ao-ponto",
      "status": "AVAILABLE",
      "price": {"value": 0.00}
    },
    {
      "id": "opt-medium",
      "productId": "prod-carne-medio",
      "status": "AVAILABLE",
      "price": {"value": 0.00}
    },
    {
      "id": "opt-well-done",
      "productId": "prod-carne-bem-passado",
      "status": "AVAILABLE",
      "price": {"value": 0.00}
    }
  ]
}

Exemplos de grupos do terceiro nível:

Grupo	Tipo	Opções de Exemplo
"Deseja retirar ingrediente?"	`INGREDIENTS`	Sem tomate, Sem alface, Sem cebola
"Qual o ponto da carne?"	`SPECIFICATION`	Ao ponto, Médio, Bem-passado
"Itens adicionais"	`INGREDIENTS`	Bacon extra, Queijo extra, Ovo

O terceiro nível só funciona para grupos dos tipos SPECIFICATION e INGREDIENTS.

Próximos passos

Modelar complementos simples — Gerenciar complementos.
Criar pizzas — Pizza usa uma estrutura semelhante, com grupos obrigatórios específicos.
Servir o combo em múltiplos canais — Multi-menu mostra como usar contextModifiers para oferecer o mesmo combo em diferentes canais.
Diagnosticar problemas — Erros e troubleshooting.

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página