Categorias do produto no checkout

Público: agências e times técnicos que mantêm o storefront de lojas Wake
Tipo de mudança: aditiva (não quebra integrações existentes)
Status: disponível em produção

1. O que mudou

O produto do pedido dentro do checkout passou a expor um novo campo GraphQL:

productCategories: [ProductCategory]

Ele traz a lista completa de categorias do item comprado, com a mesma estrutura que a query products já entregava na página de produto. Antes dessa mudança, o produto do checkout só oferecia category (um único nome, em texto) e googleCategory.

Nada foi removido ou renomeado. category e googleCategory continuam existindo, com o mesmo nome, tipo e valor de antes. Quem não pedir o campo novo não é afetado em nada.

2. Onde o campo está disponível

Importante para o planejamento de tagueamento: o campo existe no nó de pedido, que é o que alimenta o evento purchase. Ele não está disponível nos produtos do carrinho, então os eventos view_cart e begin_checkout não são cobertos por esta entrega. Se a loja precisar da hierarquia de categorias também nessas etapas, isso deve ser solicitado como uma nova demanda ao time da Wake.

Selecionar productCategories dentro de orders não exige selecionar checkout { products } na mesma query. As duas seleções são independentes.

3. Estrutura do tipo ProductCategory

Sobre o campo hierarchy

hierarchy é uma string única contendo o caminho da categoria, exatamente como está cadastrado no catálogo da loja. Não é um array e não existe navegação parent / children neste tipo.

O separador usado depende do cadastro da loja. Antes de escrever o parser, inspecione o valor real retornado pela sua loja (basta rodar a query no ambiente da loja e olhar a resposta) e implemente o split de acordo. Não assuma um separador fixo.

4. Como consultar

Na query checkout

query {
  checkout(checkoutId: "SEU_CHECKOUT_ID") {
    orders {
      products {
        productVariantId
        name
        quantity
        productCategories {
          id
          name
          hierarchy
          main
        }
      }
      kits {
        products {
          productVariantId
          productCategories {
            name
            hierarchy
            main
          }
        }
      }
    }
  }
}

Na mutation checkoutComplete (evento purchase)

mutation checkoutComplete($checkoutId: Uuid!, $comments: String, $paymentData: String!) {
  checkout {
    complete(checkoutId: $checkoutId, comments: $comments, paymentData: $paymentData) {
      orders {
        products {
          productVariantId
          name
          quantity
          value
          productCategories {
            name
            main
          }
        }
      }
    }
  }
}

Exemplo de resposta

{
  "productVariantId": 123456,
  "name": "Tênis Esportivo Feminino de Corrida",
  "quantity": 1,
  "value": 399.90,
  "productCategories": [
    { "name": "Calçados", "hierarchy": "/Calçados", "main": true },
    { "name": "Tênis",    "hierarchy": "/Calçados/Tênis", "main": false },
    { "name": "Corrida",  "hierarchy": "/Calçados/Tênis/Corrida", "main": false }
  ]
}

Os valores de hierarchy acima são ilustrativos. Confirme o formato real na sua loja (ver seção 3).

5. O que a agência precisa fazer

O campo está disponível na API, mas o storefront da loja não passa a usá-lo sozinho. É necessário ajustar o código do tema/template da loja. Passo a passo:

5.1. Incluir o campo na query/mutation do checkout

Localize no tema da loja o ponto onde a mutation checkoutComplete (ou a query checkout) é montada e acrescente o bloco productCategories dentro de orders { products { ... } }, conforme os exemplos da seção 4.

Se a loja usa o SDK oficial da Wake em TypeScript, atualize para a versão mais recente — a query e a tipagem de CheckoutCompleteData já incluem productCategories.

5.2. Ajustar a montagem do data layer

No script de eventos da loja (normalmente algo como event_manager.js no tema), a função que monta os items do evento purchase deve ler product.productCategories diretamente do item do pedido.

Remova o workaround anterior, se existir: era comum selecionar também checkout { products } e cruzar os dois arrays por productVariantId em JavaScript para conseguir a categoria. Isso deixa de ser necessário — o dado agora vem no próprio item do pedido.

5.3. Mapear para o GA4

O GA4 aceita até 5 níveis por item: item_category, item_category2, item_category3, item_category4, item_category5.

Sugestão de mapeamento, usando hierarchy da categoria principal (main: true):

function mapCategoriesToGa4(productCategories) {
  if (!productCategories || !productCategories.length) return {};

  // Usa a categoria principal; se não houver, usa a primeira da lista.
  const principal = productCategories.find(c => c.main) || productCategories[0];

  // ⚠️ Ajuste o separador conforme o valor real retornado pela sua loja.
  const niveis = (principal.hierarchy || principal.name || '')
    .split('/')
    .map(s => s.trim())
    .filter(Boolean)
    .slice(0, 5);

  const out = {};
  niveis.forEach((nivel, i) => {
    out[i === 0 ? 'item_category' : `item_category${i + 1}`] = nivel;
  });
  return out;
}

// Uso na montagem dos items do evento purchase
const items = order.products.map(p => ({
  item_id: String(p.productVariantId),
  item_name: p.name,
  price: p.value,
  quantity: p.quantity,
  ...mapCategoriesToGa4(p.productCategories),
}));

Alternativa: se a loja prefere usar a lista de categorias em vez do caminho, ordene productCategories conforme a regra de negócio da loja e mapeie os 5 primeiros nomes para item_category..item_category5. Escolha uma abordagem e mantenha a mesma em todos os eventos, para não gerar inconsistência nos relatórios.

5.4. Validar

1. Rode a query no ambiente da loja e confirme que productCategories vem preenchido.
2. Finalize um pedido de teste e verifique no DebugView do GA4 se o evento purchase chega com item_category, item_category2, etc.
3. Teste também com: produto de kit, produto em variante secundária (cor/tamanho que não é a padrão) e carrinho com mais de um vendedor (que gera mais de um pedido).

Documentações de referência:

https://wakecommerce.readme.io/update/docs/checkoutcomplete
https://wakecommerce.readme.io/update/docs/checkout-copy