Checkout em blocos no WooCommerce: o que mudou e como se adaptar

O WooCommerce mudou a forma como o checkout funciona — e isso afeta qualquer loja nova ou que decida migrar. Desde a versão 8.3, lançada em novembro de 2023, o checkout em blocos (Cart and Checkout Blocks) é o padrão para instalações novas. Lojas que já existiam antes continuam com o checkout clássico, mas a tendência é que mais lojas migrem à medida que plugins e temas se adaptam.

Se você é dono de uma loja WooCommerce e já viu menções a “checkout blocks” ou “bloco de checkout” e não sabe o que isso muda na prática, este artigo responde. Vamos cobrir o que mudou, quais plugins já são compatíveis, como testar antes de mudar, e o que fazer se algo não funcionar (veja também nosso diagnóstico de checkout com erros para problemas específicos).

O que é o checkout em blocos (e por que o WooCommerce mudou)

O checkout em blocos substitui o formulário tradicional baseado em shortcode por um sistema construído com blocos do editor Gutenberg. Em vez de usar [woocommerce_checkout] na página, a loja passa a usar blocos como “Checkout”, “Informações de contato”, “Endereço de cobrança” e “Formas de pagamento”. A documentação oficial do WooCommerce descreve a estrutura desses blocos.

A mudança existe por dois motivos principais:

• Performance: o checkout em blocos usa a Store API para as interações de carrinho e checkout, carregando dados de forma mais modular. O efeito prático varia conforme o tema, os plugins e a hospedagem — o desempenho precisa ser medido na sua loja.
• Futuro: blocos são o padrão para lojas novas desde a versão 8.3 e a experiência incentivada pelo WooCommerce. Novos recursos de pagamento, express checkout e personalização estão sendo desenvolvidos prioritariamente para o checkout em blocos. O shortcode continua disponível e mantido, mas a direção estratégica do WooCommerce aponta para os blocos como foco principal de inovação.

Para lojas novas a partir da versão 8.3 do WooCommerce, o checkout em blocos já vem ativado por padrão. Lojas antigas não são afetadas automaticamente — o shortcode continua funcionando.

Checkout em blocos no WooCommerce: o que mudou na prática

A diferença principal não é visual — é arquitetural. Veja o que muda na prática:

Aspecto	Checkout clássico (shortcode)	Checkout em blocos
Como é construído	Shortcode [woocommerce_checkout] no editor	Blocos do Gutenberg (Checkout, Carrinho)
Personalização visual	Depende do tema e CSS customizado	Configurável pelo editor de blocos
Performance	Interações via shortcode (PHP)	Interações via Store API (o processamento no servidor continua)
Extensibilidade	Hooks PHP (filtros e ações)	API de blocos + JavaScript
Campos adicionais	Via woocommerce_checkout_fields	Via Additional Checkout Fields API (WC 8.9+)
Compatibilidade com plugins	Funciona com a maioria dos plugins antigos	Requer que plugins declarem compatibilidade
Versão mínima do WC	Qualquer versão	WC 8.3+ (padrão), WC 8.9+ para campos adicionais

O checkout em blocos funciona com temas clássicos e block themes (como Twenty Twenty-Five). Block themes oferecem mais controle visual pelo Editor do Site, mas não são obrigatórios. Não é necessário usar um block theme para ter o checkout em blocos.

O que muda na experiência do cliente

Do ponto de vista do comprador, as diferenças são sutis mas relevantes:

Campos de endereço

O checkout em blocos mantém os mesmos campos de endereço (nome, endereço, cidade, estado, CEP, telefone). A diferença está em como campos adicionais são tratados. No checkout clássico, plugins como o Brazilian Market on WooCommerce adicionavam CPF, CNPJ e número do endereço via filtros PHP. No checkout em blocos, esses campos precisam ser registrados pela Additional Checkout Fields API (disponível desde WC 8.9).

Para lojas brasileiras, plugins como o Brazilian Checkout Toolkit já registram CPF, CNPJ e outros campos brasileiros tanto no checkout clássico quanto no de blocos, usando a API oficial (veja detalhes na nossa configuração completa para o Brasil).

Pagamento

O checkout em blocos exige que gateways de pagamento declarem compatibilidade explicitamente. Gateways que não se integraram aos blocos podem simplesmente não aparecer como opção de pagamento — e, se todos os gateways ativos forem incompatíveis, o checkout mostra o aviso de que não há métodos de pagamento disponíveis (veja nosso guia de pagamentos no WooCommerce no Brasil para uma visão completa dos gateways).

Frete

Os métodos de frete nativos do WooCommerce funcionam nos dois checkouts. A diferença é que o checkout em blocos atualiza o frete em tempo real à medida que o cliente preenche o endereço, sem recarregar a página. Integrações com plugins de frete (Melhor Envio, Frenet, transportadoras) precisam ser validadas — verifique se declaram compatibilidade com blocos e teste o cálculo, as opções e os valores no staging antes de migrar. O Local Pickup dos blocos também tem configuração distinta da opção legada.

Layout

O layout do checkout em blocos é mais modular. Algumas seções (contato, endereço, pagamento, resumo) são blocos independentes que podem ser reordenadas ou ocultadas pelo editor do WordPress — mas nem todos os blocos são movíveis: nos totais, por exemplo, apenas o formulário de cupom pode ser removido. No checkout clássico, a ordem é fixa ou depende de customização via PHP.

Plugins que já declararam compatibilidade (e os que não declararam)

A compatibilidade é o ponto crítico da migração. Um plugin que não declarou compatibilidade pode simplesmente não funcionar no checkout em blocos. Desenvolvedores declaram compatibilidade via FeaturesUtil::declare_compatibility no arquivo principal do plugin.

Gateways de pagamento

Gateway	Compatível com blocos	Observação
Mercado Pago	Sim	Plugin oficial, v8.9.3+ (verificado em set/2026) — suporte nativo a blocos
PagBank Connect	Sim (restrição atual)	Suporte nativo ao checkout em blocos declarado; o plugin registra campos de CPF/CNPJ via Additional Checkout Fields API. Atenção: o cadastramento de novas contas está suspenso — somente lojas que já possuem Connect Key podem usar o plugin (verificado em set/2026)
Asaas	Não declarado	Sem menção a blocos na página oficial (v2.7.7, ago/2026) — verificar com o suporte antes de migrar
Stone/Pagar.me	Não confirmado	Documentação oficial consultada em set/2026 sem declaração de compatibilidade com blocos
Stripe	Sim	Suporte nativo ao checkout em blocos; usar versão atual do plugin
WooPayments	Sim (países suportados)	Não disponível para empresas no Brasil

Importante: se um gateway não declarou compatibilidade, ele pode simplesmente não aparecer como opção de pagamento no checkout em blocos — e, se todos os gateways ativos forem incompatíveis, o checkout mostra o aviso de que não há métodos de pagamento disponíveis, com opção de voltar ao checkout clássico em um clique.

Campos de checkout para Brasil

Plugin	Compatível com blocos	Observação
Brazilian Checkout Toolkit	Sim	Registra campos via Additional Checkout Fields API (WC 8.9+; o plugin recomenda 9.0+)
BuildsByLuke - Checkout Brasil	Sim	Suporte nativo via API de blocos (WC 8.9+), inclui validação de CNPJ alfanumérico
Brazilian Market on WooCommerce	Não	Sem atualizações desde fevereiro de 2024, incompatível com blocos

Outros plugins

Plugins de campos de checkout, upsell e customização variam na compatibilidade. A regra geral: verifique se o plugin declara compatibilidade com “Cart and Checkout Blocks” no changelog ou na página oficial no WordPress.org, confira a documentação do desenvolvedor e teste em staging antes de migrar. Atualização recente não garante compatibilidade funcional — o que importa é a declaração explícita (veja também nosso guia de tema e plugins essenciais para WooCommerce para critérios de escolha).

Como testar o checkout em blocos na sua loja

Antes de mudar qualquer coisa em produção, teste em ambiente controlado (veja também nosso checklist de lançamento de loja WooCommerce para uma conferência completa antes de abrir a loja).

1. Clone para staging

Copie sua loja para um ambiente de staging (a maioria dos provedores oferece isso). Nunca teste diretamente em produção.

2. Verifique a versão do WooCommerce

O checkout em blocos é padrão desde WC 8.3 (lançado em novembro de 2023), mas a Additional Checkout Fields API (necessária para campos customizados como CPF/CNPJ) ficou estável na versão 8.9. Verifique em WooCommerce > Status se sua versão é 8.9 ou superior.

3. Edite a página de Checkout

1. Vá em Páginas > Checkout e abra no editor de blocos
2. Se você vê um bloco “Checkout” com campos visuais, já está usando blocos
3. Se vê um shortcode [woocommerce_checkout], está no checkout clássico

Para migrar: selecione o bloco do shortcode, clique em “Transformar” na barra de ferramentas e escolha “Checkout”. Faça o mesmo na página do Carrinho.

4. Teste cada forma de pagamento

Faça um pedido de teste para cada gateway ativo. Verifique se:

• Todas as opções de pagamento aparecem
• O pagamento é processado corretamente
• O pedido aparece no painel com status correto

5. Verifique campos adicionais

Se sua loja usa campos customizados (CPF, CNPJ, número do endereço, bairro), confirme que eles aparecem no checkout em blocos e são salvos corretamente no pedido.

6. Teste em staging com plugins desativados

Se o checkout apresentar comportamento inesperado após a migração, teste em ambiente de staging copiando a loja para lá. Desative os plugins um por um e teste o checkout após cada desativação para identificar o conflito. Evite instalar o Health Check & Troubleshooting em produção — o plugin está na versão 1.7.1, afetado pela CVE-2025-64253, sem correção publicada até o momento.

Erros comuns na migração e como resolver

Gateway de pagamento não aparece

Causa: o plugin do gateway não declarou compatibilidade com blocos.

Solução: verifique se há atualização disponível. Se não houver, o WooCommerce pode mostrar uma opção para voltar ao checkout clássico no painel de configurações do bloco. Outra alternativa: entre em contato com o desenvolvedor do plugin e solicite suporte a blocos.

Campos customizados desapareceram

Causa: campos adicionados via woocommerce_checkout_fields (filtro PHP) não funcionam no checkout em blocos.

Solução: migre os campos para a Additional Checkout Fields API, disponível desde WC 8.9. Plugins como o Brazilian Checkout Toolkit ou o BuildsByLuke já fazem isso automaticamente para campos brasileiros.

Checkout trava ou mostra erro

Causa: conflito com cache (WP Rocket, Cloudflare APO, CDN) que interfere na atualização de nonces do Store API.

Solução: exclua /wp-json/wc/store/ do cache e não cacheie páginas que contenham blocos de checkout ou carrinho. O checkout em blocos atualiza nonces dinamicamente e camadas de cache podem bloquear isso.

Layout diferente do esperado

Causa: o tema injeta CSS que entra em conflito com o layout do checkout em blocos. A estrutura interna dos blocos pode variar entre versões.

Solução: use estilos globais do tema ou as opções de personalização disponíveis no Editor de Blocos. Evite CSS direcionado a classes internas como .wc-block-checkout ou .wc-block-components-* — o WooCommerce considera a estrutura interna dos blocos privada e pode mudar entre versões. Teste o checkout no tema que a loja usa para validar a aparência.

Pedido de teste criou registro no analytics

Causa: o checkout em blocos dispara eventos de analytics (como GA4) durante o teste.

Solução: exclua pedidos de teste depois de verificá-los. Não há marcação visual nativa que distinga pedidos de teste dos reais.

Perguntas frequentes

Minha loja já usa blocos de checkout?

Edite a página de Checkout no WordPress. Se você vê um bloco “Checkout” com configurações visuais, sim. Se vê um shortcode [woocommerce_checkout], não. Lojas novas a partir do WC 8.3 (novembro de 2023) já nascem com blocos.

Preciso migrar para blocos agora?

Não é obrigatório. O checkout clássico continua funcionando e o shortcode continua disponível e mantido, mas blocos são o padrão para lojas novas e a experiência incentivada pelo WooCommerce, então a migração pode ser vantajosa no médio prazo. Se você está montando uma loja do zero, veja nosso guia completo de como criar uma loja WooCommerce no Brasil para todas as etapas.

O checkout em blocos funciona com qualquer tema?

Sim. Não é necessário usar um block theme. O checkout em blocos funciona com temas clássicos e block themes. Block themes oferecem mais controle visual pelo Editor do Site, mas não são obrigatórios.

Meus plugins de personalização do checkout funcionam?

Depende. Plugins que usam filtros PHP como woocommerce_checkout_fields não funcionam no checkout em blocos. Verifique se o plugin declara compatibilidade com “Cart and Checkout Blocks” no changelog ou na página do plugin no WordPress.org. Se o checkout apresentar problemas depois da migração, veja nosso diagnóstico de checkout com erros para identificar a causa.

Como volto para o checkout clássico?

Edite a página de Checkout, selecione o bloco “Checkout”, clique em “Transformar” e escolha “Classic Shortcode”. Faça o mesmo na página do Carrinho. O WooCommerce também pode oferecer um botão de reversão automaticamente quando detecta plugins incompatíveis.

Campos de CPF e CNPJ funcionam no checkout em blocos?

Sim, desde que você use um plugin compatível com a Additional Checkout Fields API (WC 8.9+). O Brazilian Market on WooCommerce não é compatível — plugins como Brazilian Checkout Toolkit ou BuildsByLuke são alternativas atuais.

O checkout em blocos é mais rápido?

O efeito no desempenho varia conforme o tema, os plugins e a hospedagem. O checkout em blocos usa a Store API para as interações de carrinho e checkout, mas o processamento no servidor continua acontecendo. O desempenho precisa ser medido na sua loja — não há regra geral que se aplique a todos os cenários.

Posso usar os dois checkouts ao mesmo tempo?

Não. Uma loja pode ter apenas um checkout ativo — ou blocos, ou shortcode. Não é possível misturar os dois na mesma loja.

---

Se sua loja WooCommerce apresenta problemas de checkout, conflitos entre plugins ou dúvidas sobre migração para blocos, a Panacea pode ajudar. Solicitar análise inicial da minha loja.