Hooks do WooCommerce: customizar a loja sem editar templates

Atualizado em 19/06/2026

O WooCommerce é, antes de tudo, um plugin de WordPress — e por isso é construído sobre o mesmo sistema de actions e filters. A diferença é que o WooCommerce leva esse conceito ao extremo: as páginas de loja, produto, carrinho e checkout são montadas inteiramente por hooks. Em vez de escrever HTML fixo, os templates do plugin disparam do_action() em cada ponto e o próprio WooCommerce "se pendura" nesses pontos para imprimir o título, o preço, o botão de comprar e assim por diante. Para o desenvolvedor, isso é uma boa notícia: você customiza a loja se pendurando nos mesmos hooks, sem tocar em um único arquivo de template.

Por que NÃO sobrescrever templates

O WooCommerce permite copiar um arquivo de plugins/woocommerce/templates/ para seu-tema/woocommerce/ para sobrescrevê-lo. É um recurso legítimo, mas tem um custo alto: a sua cópia fica presa na versão atual do markup. Quando o plugin atualiza aquele template — e ele atualiza com frequência —, você não recebe as correções, e o WooCommerce passa a avisar que o seu override está desatualizado. Pior: mudanças estruturais podem quebrar o layout.

Por isso a recomendação oficial é clara: prefira hooks. Eles são a API pública e estável da loja. Você só deveria sobrescrever um template quando a mudança no markup for tão profunda que nenhum hook a permita — e, mesmo aí, mantendo o arquivo o mais enxuto possível.

Os hooks que montam a página de produto

A página de um produto é o exemplo mais didático. O template dispara, em ordem, woocommerce_before_main_content, depois entra no resumo do produto com woocommerce_single_product_summary (onde título, preço, resumo e botão são adicionados em prioridades diferentes) e, abaixo, woocommerce_after_single_product_summary (onde ficam as abas, produtos relacionados, etc.). Para inserir algo, basta escolher o hook e a prioridade correta:

<?php
/**
 * Plugin Name: Minhas Customizações WooCommerce
 */

// Sempre cheque se o WooCommerce está ativo antes de usar suas APIs.
if ( ! class_exists( 'WooCommerce' ) ) {
    return;
}

// 1) Aviso logo ABAIXO do preço (preço usa prioridade 10; usamos 15).
add_action( 'woocommerce_single_product_summary', 'dw_aviso_apos_preco', 15 );

function dw_aviso_apos_preco() {
    echo '<p class="dw-aviso">Frete grátis acima de R$ 199.</p>';
}

// 2) Selo de garantia DEPOIS do resumo do produto, como uma seção.
add_action( 'woocommerce_after_single_product_summary', 'dw_selo_garantia', 5 );

function dw_selo_garantia() {
    echo '<div class="dw-garantia">Garantia de 30 dias ou seu dinheiro de volta.</div>';
}

A tabela abaixo mostra as prioridades padrão dentro de woocommerce_single_product_summary. Escolher um número intermediário posiciona o seu conteúdo com precisão cirúrgica:

Filtrando os campos do checkout

O checkout é outro território de hooks. Para adicionar, remover ou ajustar campos, use o filtro woocommerce_checkout_fields. Como todo filter, ele recebe um valor — o array de campos — e precisa devolvê-lo. A estrutura é agrupada por seção (billing, shipping, account, order):

<?php
add_filter( 'woocommerce_checkout_fields', 'dw_ajusta_checkout' );

function dw_ajusta_checkout( $fields ) {
    // Torna o telefone opcional e muda o rótulo.
    if ( isset( $fields['billing']['billing_phone'] ) ) {
        $fields['billing']['billing_phone']['required'] = false;
        $fields['billing']['billing_phone']['label']    = 'Celular (WhatsApp)';
    }

    // Adiciona um campo personalizado de CPF/CNPJ.
    $fields['billing']['billing_documento'] = array(
        'label'       => 'CPF/CNPJ',
        'placeholder' => 'Somente números',
        'required'    => true,
        'class'       => array( 'form-row-wide' ),
        'priority'    => 25,
    );

    return $fields; // OBRIGATÓRIO: filter sem return zera os campos.
}

Adicionando uma taxa ou desconto no carrinho

Para alterar o total cobrado — uma taxa de embalagem, um desconto por região, um acréscimo de pagamento —, o hook é woocommerce_cart_calculate_fees. Ele dispara durante o cálculo do carrinho e te entrega o objeto do carrinho; você adiciona valores com $cart->add_fee() (um valor negativo funciona como desconto):

<?php
add_action( 'woocommerce_cart_calculate_fees', 'dw_taxa_e_desconto' );

function dw_taxa_e_desconto( $cart ) {
    // Evita rodar no admin (exceto em chamadas AJAX legítimas).
    if ( is_admin() && ! defined( 'DOING_AJAX' ) ) {
        return;
    }

    $subtotal = $cart->get_subtotal();

    // Desconto de 5% para carrinhos acima de R$ 500 (fee negativa).
    if ( $subtotal > 500 ) {
        $desconto = $subtotal * 0.05;
        $cart->add_fee( 'Desconto fidelidade', -$desconto );
    }

    // Taxa fixa de manuseio (o 3º parâmetro indica se é tributável).
    $cart->add_fee( 'Taxa de manuseio', 7.50, true );
}

Repare que esse callback roda a cada recálculo do carrinho — por isso evite consultas pesadas aqui e nunca chame $cart->add_fee() condicionalmente de forma instável, ou o valor "pisca" entre requisições AJAX.

Executando algo após a compra

Depois que o pedido é concluído e o cliente chega à página de obrigado, dispara o woocommerce_thankyou, que recebe o ID do pedido. É o ponto clássico para integrações: notificar um ERP, disparar um pixel de conversão, registrar uma assinatura. Como vimos no FAQ, trate-o como potencialmente repetível e proteja a ação com uma meta de controle:

<?php
add_action( 'woocommerce_thankyou', 'dw_apos_compra' );

function dw_apos_compra( $order_id ) {
    if ( ! $order_id ) {
        return;
    }

    $order = wc_get_order( $order_id ); // CRUD API, nunca get_post().
    if ( ! $order ) {
        return;
    }

    // Idempotência: só executa uma vez por pedido.
    if ( $order->get_meta( '_dw_integrado' ) === 'sim' ) {
        return;
    }

    // ... aqui vai a sua integração usando $order->get_total(), etc.

    $order->update_meta_data( '_dw_integrado', 'sim' );
    $order->save();
}

O acesso ao pedido aqui já usa a CRUD API do WooCommerce (wc_get_order()), e não get_post() — essencial para compatibilidade com o armazenamento moderno de pedidos.

Mapa rápido dos principais hooks

Boas práticas que evitam dor de cabeça

• Cheque o WooCommerce. Envolva o código em class_exists( 'WooCommerce' ) ou registre os hooks em woocommerce_loaded; assim o site não quebra se o plugin for desativado.
• Use a prioridade como régua. Não é só ordem de execução: nos hooks de saída de HTML, ela define onde o elemento aparece na tela.
• Filter sempre retorna. Vale para woocommerce_checkout_fields e qualquer outro: esquecer o return apaga o conteúdo filtrado.
• Mantenha tudo num plugin. Customizações de loja não pertencem ao functions.php do tema; um plugin próprio sobrevive à troca de tema.
• Escape a saída. Use esc_html(), esc_attr() e wp_kses_post() ao imprimir dados em hooks de exibição.

Dominar esses hooks resolve a maioria das customizações de uma loja sem nenhum override de template. Quando o assunto é manipular dados — ler e gravar produtos e pedidos por código —, o caminho correto é a CRUD API, tema do próximo artigo. Se a sua loja precisa de ajustes finos ou de uma integração sob medida, veja também os serviços de suporte e manutenção WooCommerce.