
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).
- Se aparecer um bloco grande chamado “Finalizar compra” / “Checkout”, com as seções de contato, endereço e pagamento editáveis no editor, a sua loja usa o checkout em blocos. É o padrão nas instalações mais recentes do WooCommerce.
- Se aparecer só o shortcode
(ou um bloco “Shortcode clássico”), a loja usa o checkout clássico.
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:
- adicionar, editar, reordenar e desativar campos de cobrança, entrega e campos adicionais;
- usar cerca de 20 tipos de campo no checkout clássico (texto, número, telefone, e-mail, seleção, múltipla seleção, caixa de seleção, data, hora, URL, título, parágrafo e outros);
- usar 10 tipos de campo no checkout em blocos (texto, número, área de texto, seleção, rádio, caixa de seleção, e-mail, URL, parágrafo e título);
- validar e-mail, telefone e URL.
Como fazer, na prática
- Instale e ative o plugin em Plugins > Adicionar novo.
- Vá em WooCommerce > Checkout Form.
- 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).
- 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. - 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:
- id: precisa ter um “namespace”, no formato
nome-do-plugin/nome-do-campo. - location:
contact(junto com o e-mail),address(aparece nos endereços de entrega e cobrança e fica salvo no cliente e no pedido) ouorder(uma seção de informações adicionais do pedido). - type:
text(padrão),select,checkboxoudate.
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
- “Colei o código e o campo não aparece.” Quase sempre é o código do checkout clássico rodando em uma loja com checkout em blocos (ou o contrário). Volte ao passo 1.
- Campo aparece, mas o valor some. No clássico, faltou a parte que salva no pedido. Confira também se o name do campo não tem espaços nem acentos.
- Dois plugins mexendo no checkout. Um editor de campos junto com um plugin que substitui o checkout inteiro pode gerar conflito. Use um de cada vez e teste em ambiente de homologação. Se for usar o Fluid Checkout, veja no guia de checkout em etapas no WooCommerce como ele convive com os campos brasileiros.
- Campos demais. Cada campo obrigatório extra é um motivo a mais para o cliente desistir. Peça só o que você realmente usa.
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.