Plugins Br

Como adicionar campos no checkout do WooCommerce (com e sem plugin)

Como adicionar campos no checkout do WooCommerce (com e sem plugin)

Precisa pedir o CPF, um ponto de referência para a entrega ou a data em que o cliente quer receber o pedido? Saber como adicionar campos no checkout do WooCommerce resolve isso, mas existe um detalhe que derruba muita gente: o caminho muda conforme a sua loja usa o checkout clássico (shortcode) ou o novo checkout em blocos. Um código que funciona em um simplesmente não aparece no outro.

Neste tutorial você vai descobrir primeiro qual checkout a sua loja usa e, depois, escolher entre três caminhos: plugin (sem código), código para o checkout em blocos e código para o checkout clássico.

Passo 1: descubra qual checkout a sua loja usa

Antes de instalar qualquer coisa, abra Páginas no painel do WordPress e edite a página Finalizar compra (ou Checkout).

Isso importa porque os filtros antigos, como woocommerce_checkout_fields, foram feitos para o checkout clássico. Para o checkout em blocos, o WooCommerce criou uma API própria, a Additional Checkout Fields API. Os plugins de edição de campos também costumam ter configurações separadas para cada tipo de checkout.

Passo 2: escolha o caminho

Caminho Funciona em Indicado para
Plugin editor de campos Clássico e blocos (depende do plugin) Quem não quer mexer em código e precisa de vários campos ou lógica condicional
Additional Checkout Fields API Somente checkout em blocos Desenvolvedores, 1 a 3 campos simples
Filtro woocommerce_checkout_fields Somente checkout clássico Lojas antigas ou temas que ainda usam o shortcode

Opção A: adicionar campos no checkout WooCommerce com plugin

O plugin mais usado para isso é o Checkout Field Editor (Checkout Manager) for WooCommerce, da ThemeHigh, com mais de 400 mil instalações ativas no diretório oficial. A versão gratuita já permite:

Como fazer, na prática

  1. Instale e ative o plugin em Plugins > Adicionar novo.
  2. Vá em WooCommerce > Checkout Form.
  3. Escolha a aba correspondente ao seu checkout (clássico ou blocos) e a seção: Billing (cobrança), Shipping (entrega) ou Additional (campos extras do pedido).
  4. Clique em Add field, escolha o tipo, defina o name (sem espaços nem acentos, por exemplo billing_referencia), o rótulo e se é obrigatório.
  5. Salve e faça um pedido de teste para conferir se o valor aparece nos detalhes do pedido.

Quando a versão Pro faz diferença

A versão paga acrescenta o que costuma aparecer em lojas mais complexas: campos condicionais (mostrar um campo só para determinado produto, categoria, forma de envio, forma de pagamento ou perfil de usuário), envio de arquivo, seletores de data e hora, validação com expressão regular, campos que alteram o preço e exibição dos dados na área Minha conta.

Um exemplo comum: pedir “Nome para gravação” apenas quando o carrinho tiver um produto personalizado. Sem lógica condicional, esse campo aparece para todo mundo e só atrapalha. Se a sua loja vende kits montáveis, vale ler também o guia sobre como criar um produto personalizável no WooCommerce.

Aqui na loja você encontra o Checkout Field Editor Pro para WooCommerce sob licença GPL. Se além dos campos você precisa de outros ajustes na loja (rótulos de preço, PDF, taxas por pagamento), veja também o guia do Booster for WooCommerce.

Opção B: código para o checkout em blocos

Se a sua loja usa o checkout em blocos e você precisa de poucos campos, a API oficial resolve com um trecho curto. Coloque o código em um plugin de snippets (como o Code Snippets) ou no functions.php de um tema filho. Nunca edite o tema principal, porque a próxima atualização apaga a alteração.

add_action( 'woocommerce_init', function () {
    if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
        return;
    }

    woocommerce_register_additional_checkout_field( array(
        'id'       => 'minha-loja/referencia',
        'label'    => 'Ponto de referência',
        'location' => 'address',
        'type'     => 'text',
        'required' => false,
    ) );
} );

Os pontos que você precisa entender:

Um exemplo com data de entrega preferida, aceitando apenas datas entre amanhã e daqui a 30 dias:

woocommerce_register_additional_checkout_field( array(
    'id'       => 'minha-loja/data-entrega',
    'label'    => 'Data preferida para entrega',
    'location' => 'order',
    'type'     => 'date',
    'required' => true,
    'min'      => 'P1D',
    'max'      => 'P30D',
) );

A API também aceita funções de validação e sanitização (validate_callback e sanitize_callback), úteis para conferir, por exemplo, se um número tem a quantidade certa de dígitos.

Opção C: código para o checkout clássico

No checkout por shortcode, o caminho é o filtro woocommerce_checkout_fields. O exemplo abaixo adiciona o mesmo campo de ponto de referência na seção de cobrança, salva no pedido e mostra no painel:

// 1. Adiciona o campo
add_filter( 'woocommerce_checkout_fields', function ( $fields ) {
    $fields['billing']['billing_referencia'] = array(
        'type'     => 'text',
        'label'    => 'Ponto de referência',
        'required' => false,
        'class'    => array( 'form-row-wide' ),
        'priority' => 65,
    );
    return $fields;
} );

// 2. Salva no pedido
add_action( 'woocommerce_checkout_create_order', function ( $order, $data ) {
    if ( ! empty( $_POST['billing_referencia'] ) ) {
        $order->update_meta_data(
            '_billing_referencia',
            sanitize_text_field( wp_unslash( $_POST['billing_referencia'] ) )
        );
    }
}, 10, 2 );

// 3. Mostra no admin do pedido
add_action( 'woocommerce_admin_order_data_after_billing_address', function ( $order ) {
    $ref = $order->get_meta( '_billing_referencia' );
    if ( $ref ) {
        echo '<p><strong>Ponto de referência:</strong> ' . esc_html( $ref ) . '</p>';
    }
} );

O priority controla a posição do campo: números menores sobem no formulário. Usar update_meta_data e get_meta no objeto do pedido (em vez de update_post_meta) mantém o código compatível com o armazenamento de pedidos de alto desempenho (HPOS).

E os campos brasileiros, como CPF, número e bairro?

Para CPF/CNPJ, número, bairro e celular, muitas lojas usam o plugin gratuito Brazilian Market on WooCommerce. Ele adiciona esses campos com máscara e funciona com gateways nacionais. Atenção, porém: no diretório oficial ele aparece sem atualização há bastante tempo e a página não menciona compatibilidade com o checkout em blocos. Se a sua loja usa blocos, teste com cuidado ou verifique se o seu gateway de pagamento já inclui os campos de CPF. Vários gateways brasileiros fazem isso.

Erros comuns ao adicionar campos no checkout

Esse último ponto merece atenção: campos em excesso estão entre as principais causas de desistência na finalização da compra. Depois de criar os seus campos, revise o formulário com o guia de 7 ajustes para reduzir o abandono de carrinho no WooCommerce. Se a loja ainda não abriu as vendas, passe também pelo checklist do WooCommerce antes de lançar.

Perguntas frequentes

Dá para adicionar campos no checkout WooCommerce sem plugin?

Sim, com os códigos das opções B (checkout em blocos) e C (checkout clássico). Para um ou dois campos simples, o código é suficiente. Para campos condicionais ou muitos campos, um plugin dá menos trabalho de manutenção.

Posso voltar do checkout em blocos para o clássico?

Pode. Basta editar a página de checkout e trocar o bloco “Finalizar compra” pelo shortcode

. Só faça isso se algum plugin essencial ainda não for compatível com blocos.

Os campos novos aparecem no e-mail do pedido?

Depende do método. Os plugins editores normalmente têm uma opção para exibir o campo nos e-mails. No código clássico, você precisa de um hook extra de e-mail. Faça sempre um pedido de teste e confira o e-mail recebido.

Vai testar mais de um plugin de checkout antes de decidir? Com o Passe de Acesso de 30 dias você baixa o Checkout Field Editor Pro, o Fluid Checkout PRO e outros plugins premium do catálogo pelo mesmo valor.

Sair da versão mobile