🛒 Carrinho ajax no WooCommerce: 3 formas, do plugin ao código personalizado

O botão «Adicionar ao carrinho» no WooCommerce recarrega a página por predefinição a cada clique. Um cliente escolhe um produto, clica e espera. Um segundo e meio, dois, três. No telemóvel, os cinco. Cada atraso destes afasta uma parte do público: de acordo com o Baymard Institute, a taxa média de abandono de carrinho no comércio eletrónico ronda os 70%, e um carrinho lento é um dos fatores principais.

Um carrinho AJAX elimina o recarregamento. O produto é adicionado instantaneamente, o contador no cabeçalho atualiza sem a página piscar e o cliente permanece exatamente onde estava. Para uma loja, este é um caminho direto para a conversão: menos atrito, mais compras concluídas.

Pode criar um carrinho AJAX no WooCommerce de três formas. A seguir, cada uma delas: desde instalar um plugin num minuto até código personalizado em PHP e JavaScript.

💡 Visão geral rápida:

• Método 1: instalar um plugin gratuito, 2 cliques, funciona para produtos simples e variáveis
• Método 2: configuração nativa do WooCommerce, apenas arquivos, sem variações
• Método 3: PHP + JavaScript num tema filho, controlo total, endpoint moderno wc-ajax

O que é um carrinho AJAX e porque é que a sua loja precisa dele

Um carrinho WooCommerce normal funciona assim: o cliente clica em «Adicionar ao carrinho» → o navegador submete o formulário → o servidor processa-o → a página recarrega → o cliente vê o resultado. Uma cadeia de quatro passos, e pode perder uma pessoa em cada um deles.

Um carrinho AJAX altera a mecânica. O navegador envia um pedido assíncrono ao servidor, o servidor devolve JSON com os dados atualizados do carrinho e o JavaScript atualiza o contador e o mini-carrinho em tempo real. A página permanece no lugar. O cliente nem sequer se apercebe de que algo aconteceu: o produto já está no carrinho.

Da perspetiva da loja, a diferença é tangível. Um estudo da Google de 2023 mostrou que cada passo extra no funil de compra reduz a conversão em 10 a 15%. Ao remover o recarregamento, remove um passo. Além disso, a carga do servidor diminui: em vez de renderizar uma página completa, serve JSON leve.

Mas há uma nuance: o WooCommerce de origem ativa o AJAX apenas para as páginas de loja e categoria. Na página de produto individual e para produtos variáveis, o recarregamento mantém-se. É exatamente essa lacuna que vamos fechar.

Método 1: plugin Ajax add to cart for WooCommerce

O caminho mais rápido, o plugin gratuito Ajax Add to Cart for WooCommerce. Instala-se num minuto, não requer configuração, funciona logo após a ativação.

O plugin trata da adição por AJAX para produtos simples e variáveis em qualquer página: produto, arquivo, categoria. O mini-carrinho atualiza automaticamente. De acordo com o WordPress.org, mais de 10 000 instalações ativas, classificação de 4,7 em 5, compatibilidade com WordPress 7.0+ e versões recentes do WooCommerce. Atualizado regularmente: a versão mais recente, 2.6.5, saiu em junho de 2026.

Instalação:

• Vá a Administração do WordPress → Plugins → Adicionar Novo
• Pesquise por «Ajax add to cart for WooCommerce»
• Clique em «Instalar» e depois em «Ativar»

É tudo. Vá a qualquer página de produto e clique em «Adicionar ao carrinho»: sem recarregamento, produto adicionado. O plugin não requer configurações adicionais. Se precisar de desativar o AJAX para determinadas páginas, as definições do plugin têm um filtro correspondente.

Uma alternativa, o FunnelKit Cart (também gratuito). Além de um carrinho AJAX, oferece um painel lateral deslizante para o carrinho e upsells dentro dele. É um pouco mais pesado, mas para lojas focadas no valor médio da encomenda, justifica-se.

Método 2: configuração nativa do WooCommerce

O WooCommerce consegue fazer um carrinho AJAX de origem, mas com duas limitações. Funciona apenas em páginas de arquivo (loja, categorias, etiquetas) e não suporta produtos variáveis. Para a página de produto individual, o recarregamento mantém-se.

Se a sua loja vende apenas produtos simples e os clientes os adicionam ao carrinho a partir da montra da loja, isto é suficiente. Ativado com uma única caixa de seleção:

• Administração → WooCommerce → Configurações → Produtos → Geral
• No bloco «Comportamento ao adicionar ao carrinho», marque «Ativar botões de adicionar ao carrinho por AJAX nos arquivos»
• Guardar

Pronto. Na página de loja e nas páginas de categoria, o botão «Adicionar ao carrinho» funciona agora sem recarregamento. Mas visite uma página de produto individual e continua igual: um ciclo completo de recarregamento. Para a maioria das lojas, isto não é suficiente, por isso passemos ao terceiro método.

Método 3: PHP e JavaScript num tema filho

O controlo total sobre o carrinho AJAX vem com código personalizado. Você decide em que páginas o AJAX funciona, como os erros são tratados e o que o cliente vê após adicionar um produto.

Vamos escrever um handler no endpoint moderno wc-ajax; ele funciona bem com plugins de cache (WP Rocket, LiteSpeed Cache excluem ?wc-ajax= da cache por predefinição), ao contrário do antigo admin-ajax.php, que muitas vezes se comporta de forma imprevisível em sites com cache.

3.1 Tema filho

O código será colocado num tema filho: isto é uma garantia contra a perda de alterações quando o tema principal for atualizado. Se ainda não tem um tema filho, crie um ou use um plugin como o Code Snippets; permite-lhe adicionar código PHP sem editar ficheiros do tema.

Porque é que um tema filho é obrigatório: da próxima vez que o tema principal for atualizado, todas as suas edições no functions.php e nos ficheiros JS serão sobrescritas. Um tema filho vive separadamente e não é tocado pelas atualizações.

3.2 Carregar o JavaScript

No functions.php do tema filho, registamos e localizamos o script:

1
function sd_ajax_add_to_cart_script() {
2
    if (is_admin()) {
3
        return;
4
    }
5
 
6
    wp_register_script(
7
        'sd-ajax-add-to-cart',
8
        get_stylesheet_directory_uri() . '/js/ajax-add-to-cart.js',
9
        array('jquery', 'wc-add-to-cart'),
10
        '1.0',
11
        true
12
    );
13
    wp_enqueue_script('sd-ajax-add-to-cart');
14
 
15
    wp_localize_script('sd-ajax-add-to-cart', 'sdAjaxCart', array(
16
        'wc_ajax_url' => WC_AJAX::get_endpoint('sd_ajax_add_to_cart'),
17
        'nonce'       => wp_create_nonce('sd_ajax_cart_nonce'),
18
    ));
19
}
20
add_action('wp_enqueue_scripts', 'sd_ajax_add_to_cart_script');

Explicação. O wp_register_script regista o nosso futuro ficheiro JS com dependências do jQuery e do wc-add-to-cart nativo. O wp_localize_script passa dois parâmetros chave para o JavaScript: o URL do endpoint wc-ajax e uma chave nonce para proteção CSRF. Um nonce é uma assinatura criptográfica que o servidor verificará ao processar o pedido: sem ela, qualquer site externo poderia mexer no seu carrinho.

3.3 Handler JavaScript

Crie uma pasta js na raiz do tema filho e um ficheiro ajax-add-to-cart.js dentro dela:

1
jQuery(function ($) {
2
    $('form.cart').on('submit', function (e) {
3
        var $form = $(this);
4
        var $button = $form.find('.single_add_to_cart_button');
5
 
6
        if (!$button.length || $button.hasClass('disabled')) {
7
            return;
8
        }
9
 
10
        e.preventDefault();
11
 
12
        var data = {
13
            product_id: $form.find('input[name=product_id]').val() || $button.val(),
14
            quantity: $form.find('input[name=quantity]').val() || 1,
15
            variation_id: $form.find('input[name=variation_id]').val() || 0,
16
        };
17
 
18
        $button.removeClass('added').addClass('loading');
19
 
20
        $.ajax({
21
            type: 'POST',
22
            url: sdAjaxCart.wc_ajax_url,
23
            data: $.param(data) + '&nonce=' + sdAjaxCart.nonce,
24
            success: function (response) {
25
                if (response && response.error) {
26
                    window.location = response.product_url;
27
                    return;
28
                }
29
                $(document.body).trigger('added_to_cart', [
30
                    response.fragments,
31
                    response.cart_hash,
32
                    $button,
33
                ]);
34
            },
35
            complete: function () {
36
                $button.addClass('added').removeClass('loading');
37
            },
38
        });
39
    });
40
});

A diferença chave em relação a tutoriais desatualizados: usamos sdAjaxCart.wc_ajax_url (o endpoint wc-ajax) em vez de wc_add_to_cart_params.ajax_url (o antigo admin-ajax.php). O wc-ajax é automaticamente excluído pelos plugins de cache e não requer um hook wp_ajax_nopriv_ separado; o próprio WooCommerce trata de utilizadores autenticados e não autenticados.

3.4 Handler PHP

Adicione o seguinte ao functions.php do tema filho, logo após o primeiro bloco:

1
function sd_ajax_add_to_cart_handler() {
2
    if (!wp_verify_nonce($_POST['nonce'], 'sd_ajax_cart_nonce')) {
3
        wp_send_json_error(array('message' => 'Security error'), 403);
4
    }
5
 
6
    $product_id = apply_filters(
7
        'sd_ajax_add_to_cart_product_id',
8
        absint($_POST['product_id'])
9
    );
10
    $quantity = empty($_POST['quantity']) ? 1 : wc_stock_amount($_POST['quantity']);
11
    $variation_id = absint($_POST['variation_id']);
12
 
13
    $passed = apply_filters(
14
        'sd_ajax_add_to_cart_validation',
15
        true,
16
        $product_id,
17
        $quantity
18
    );
19
 
20
    $product_status = get_post_status($product_id);
21
 
22
    if ($passed && 'publish' === $product_status
23
        && WC()->cart->add_to_cart($product_id, $quantity, $variation_id)
24
    ) {
25
        do_action('sd_ajax_added_to_cart', $product_id);
26
 
27
        if ('yes' === get_option('woocommerce_cart_redirect_after_add')) {
28
            wc_add_to_cart_message(array($product_id => $quantity), true);
29
        }
30
 
31
        WC_AJAX::get_refreshed_fragments();
32
    } else {
33
        wp_send_json(array(
34
            'error'       => true,
35
            'product_url' => apply_filters(
36
                'sd_ajax_cart_redirect_after_error',
37
                get_permalink($product_id),
38
                $product_id
39
            ),
40
        ));
41
    }
42
 
43
    wp_die();
44
}
45
add_action('wc_ajax_sd_ajax_add_to_cart', 'sd_ajax_add_to_cart_handler');

O handler faz três coisas. Verifica o nonce: se o pedido veio de um site externo, devolve imediatamente um 403. Adiciona o produto ao carrinho através de WC()->cart->add_to_cart(), o método padrão do WooCommerce que trata do stock, variações e validação por si só. Chama WC_AJAX::get_refreshed_fragments(); este método devolve fragmentos HTML atualizados do mini-carrinho, que o nosso JavaScript irá captar.

O hook wc_ajax_sd_ajax_add_to_cart é um endpoint wc-ajax que o WooCommerce processa ignorando a maioria dos plugins de cache. Não são necessários wp_ajax_ / wp_ajax_nopriv_: o wc-ajax sabe por si próprio se o utilizador tem sessão iniciada ou não.

Erros comuns ao implementar um carrinho AJAX

Um carrinho AJAX avaria de forma previsível; quase sempre, a culpa é de três coisas. Eis o que verificar primeiro.

Conflito com plugins de cache. Se o mini-carrinho não atualiza ou atualiza com atraso, o plugin de cache guardou em cache a resposta AJAX. Solução: use o endpoint wc-ajax (é excluído da cache automaticamente) e certifique-se de que o WP Rocket / LiteSpeed Cache não estão a minificar o JS inline do carrinho. Nas definições de cache, encontre a diretiva «Delay JavaScript» e adicione /wc-ajax= às exclusões.

O tema não suporta fragmentos do WooCommerce. Alguns temas personalizam o mini-carrinho de tal forma que os seletores padrão do WooCommerce deixam de funcionar. Sintoma: o AJAX é executado, o produto está no carrinho, mas o contador no cabeçalho não atualiza. Corrige-se substituindo os seletores através do filtro woocommerce_add_to_cart_fragments.

Layout do botão em dispositivos móveis. Em dispositivos tácteis, o evento click dispara de forma diferente do que no desktop, por vezes com um atraso de 300 ms ou um disparo duplo. Se um produto for adicionado duas vezes no telemóvel, envolva o handler numa verificação da flag $button.hasClass('disabled'), como no código acima.

⁉️🤔 Perguntas frequentes

O carrinho AJAX funciona com produtos variáveis?

Sim. Tanto o plugin Ajax Add to Cart for WooCommerce como o código personalizado do método 3 tratam corretamente dos produtos variáveis. A variação é passada através de variation_id no corpo do pedido, e o WooCommerce substituirá o preço e os atributos corretos. A única condição: todos os atributos de variação obrigatórios devem estar selecionados antes de clicar no botão.

Preciso de limpar a cache depois de ativar o carrinho AJAX?

Absolutamente. Limpe a cache do site (plugin de cache → purgar tudo), a cache da CDN se for usada e a cache do navegador. As respostas AJAX podem ser guardadas em cache logo no primeiro pedido, e o mini-carrinho deixará de atualizar. Num site de produção, após ativar o AJAX, faça um ciclo completo: adicione um produto → verifique o contador → abra o carrinho → certifique-se de que o produto está lá.

Posso usar o antigo admin-ajax.php em vez do wc-ajax?

Tecnicamente, sim, mas não deve. O admin-ajax.php requer dois hooks (wp_ajax_ para utilizadores autenticados e wp_ajax_nopriv_ para visitantes), e os plugins de cache frequentemente bloqueiam ou guardam em cache este endpoint. O wc-ajax é o padrão moderno do WooCommerce; é mais fiável e mais simples de configurar. Se estiver a adaptar código de um tutorial antigo que usa admin-ajax.php, substitua-o por wc-ajax.

E se o contador do carrinho não atualizar após uma adição por AJAX?

Muito provavelmente, o tema usa uma marcação de mini-carrinho não padrão. O WooCommerce atualiza fragmentos através de seletores registados pelo filtro woocommerce_add_to_cart_fragments. Verifique o functions.php do tema à procura deste filtro e compare os seletores com a marcação real do mini-carrinho no inspetor do navegador. Se os seletores não corresponderem, corrija-os no filtro e o contador funcionará.

Resumo

Um carrinho AJAX não é decoração; é uma alavanca direta de conversão. Um minuto para instalar um plugin ou uma hora para código personalizado compensa através de um menor abandono de carrinho e mais compras concluídas. Escolha o método que se adequa às suas necessidades:

• Não tem tempo e precisa de resultados imediatos: instale o Ajax Add to Cart for WooCommerce, ative-o e vá testar a sua loja.
• Vende apenas produtos simples a partir da montra da loja: ative a configuração nativa do WooCommerce.
• Precisa de controlo total e fiabilidade num site com cache: opte pelo método 3 usando o endpoint wc-ajax e verificação de nonce.

Se a sua loja funciona com um tema de blocos ou usa Blocos WooCommerce para a página de produto, verifique a compatibilidade: os blocos renderizam o botão «Adicionar ao carrinho» via React, e os handlers jQuery padrão podem não se ligar. Nesses casos, um plugin é mais fiável.