A maioria dos problemas se resume a um punhado de causas. Elas estão ordenadas aqui pela frequência com que os lojistas as encontram, e cada uma tem uma solução.
“Conectei tudo, mas nada sincroniza”
Quase sempre é uma de duas coisas, e ambas têm uma verificação rápida.
1. O cron não está rodando. A sincronização acontece por meio de uma fila em segundo plano, então, sem o cron, nada é enviado e nenhum erro aparece na tela. No admin, abra a aba Queue Monitor (Marketing → Intuit Mailchimp → Dashboard): se o Pending continuar subindo e nunca esvaziar, o cron é o culpado. Peça à sua hospedagem para confirmar que o cron do Magento está agendado; assim que ele rodar, a aba Cron Monitor mostra cada tarefa em verde.
2. Seu banco de dados está abaixo do mínimo. A extensão precisa de MySQL 8.0+ ou MariaDB 10.6+ para a sincronização em segundo plano. Se o cron está rodando e o Pending ainda não esvazia, verifique a versão do seu banco de dados e faça a atualização se estiver abaixo do mínimo.
A instalação ou atualização falha (erros de setup:upgrade ou di:compile)
Ao instalar com o Composer, ele garante os requisitos para você (Magento 2.4.6+, PHP 8.1 a 8.4, MySQL 8.0+ ou MariaDB 10.6+), então uma recusa limpa significa que o ambiente precisa atingir esse patamar. Se você instalar por zip, instale primeiro o pacote PulseCore incluído em app/code, senão o di:compile para em um erro de classe não encontrada. O setup:upgrade adiciona colunas a algumas tabelas centrais, então lojas grandes devem executá-lo dentro de uma janela de manutenção. Se uma compilação falhar após uma atualização, passe para o patch mais recente e execute novamente setup:upgrade, di:compile e cache:flush. A Instalação traz o passo a passo completo.
O que os rótulos de status significam
Cada pedido, cliente e produto exibe um status:
| Status | Significado | Você precisa agir? |
|---|---|---|
| Synced | Enviado ao Mailchimp | Não |
| Up to date | Nada mudou, então foi ignorado | Não |
| Pending | Aguardando a próxima execução do cron | Apenas verifique se o cron roda |
| Error | Um envio recente falhou; pode se corrigir sozinho | Verifique novamente em alguns minutos |
| Action needed | Falhou de vez após as novas tentativas | Corrija os dados e clique em Retry na Entity Queue |
| Not supported | Um produto de tipo personalizado está sem SKU ou nome; nada foi enviado | Adicione o SKU ou o nome e ressincronize (abaixo) |
| Not in Mailchimp | Nunca enviado; fora do escopo de sincronização | Só se você esperava que estivesse (abaixo) |
Por que “Not in Mailchimp”? Não é um erro: o registro estava fora do escopo de sincronização. A visualização de loja dele não está conectada, ele é mais antigo que a sua janela de sincronização, ou é um pedido histórico fora da sua seleção de receita confirmada. Por padrão, a receita confirmada abrange processing, complete e closed: essa seleção decide quais pedidos históricos são importados e quais pedidos contam para a receita e o valor vitalício. Os novos pedidos sincronizam conforme acontecem e permanecem atualizados a cada mudança de status.
Erros de “e-mail inválido”, mas não encontro esse cliente
Um checkout de visitante não tem conta de cliente, então o e-mail fica no pedido, não na grade de Customers. Procure em Sales → Orders.
O Mailchimp rejeita endereços que parecem falsos ou malformados. E-mails reais de visitantes sincronizam sem problema; apenas os inválidos são excluídos, de propósito. Para corrigir um deles, abra o pedido, corrija o e-mail de cobrança e salve (ele volta para a fila sozinho). Em lojas de teste, os dados de exemplo costumam trazer e-mails fictícios que o Mailchimp vai rejeitar; isso é esperado, não uma falha.
Problemas de conexão
- Um aviso diz “Mailchimp is disconnected”: a solução vem junto com a mensagem. O aviso traz o próprio botão Reconnect to Mailchimp, e um clique restaura o vínculo. Se algum dia precisar do caminho mais aprofundado, abra a página Mailchimp accounts (o menu de mais opções ⋯ na faixa de abas de operações), escolha Reconnect ali e depois confirme que a sua visualização de loja ainda aponta para o público certo.
- O cabeçalho diz “Not Connected” após adicionar uma conta: adicionar uma conta e conectar uma visualização de loja são dois passos separados. Mude o escopo para uma visualização de loja e depois escolha Connect store.
- “Connect store” não mostra nenhuma loja: ou nenhuma conta foi conectada ainda, ou toda loja do Mailchimp já está vinculada a outra visualização de loja. Adicione uma conta ou crie uma nova loja no Mailchimp.
- O popup de login não conclui: permita popups para o domínio do seu admin e verifique se o seu servidor consegue alcançar o Mailchimp por HTTPS.
“Diz que minha chave de API é inválida, mas a chave é novíssima”
Primeiro verifique o formato: uma chave do Mailchimp termina com o sufixo do seu data center (por exemplo, -us21), então gere uma chave nova e cole ela inteira. Se a chave é sem dúvida válida, o log em var/log registra cada chamada de validação com a chave mascarada: uma linha com HTTP 401 significa que o Mailchimp rejeitou a própria chave, enquanto um erro de transporte sem status significa que seu servidor não conseguiu alcançar o Mailchimp, então peça à sua hospedagem para liberar HTTPS de saída para <dc>.api.mailchimp.com. Uma chave que se torna inválida depois aparece na página Mailchimp accounts: o indicador de saúde da conta muda dentro de uma hora, e Update key resolve ali mesmo, sem desconectar a loja. Conecte sua conta do Mailchimp cobre cada passo.
As etiquetas não aparecem nos contatos
As etiquetas de categoria se aplicam a cada pedido que sincroniza a partir do momento em que você as ativa, e uma ressincronização também etiqueta o histórico dos seus pedidos: as etiquetas nunca são duplicadas, então ressincronizar é sempre seguro. Elas vão para compradores com conta de cliente; as compras de visitantes enriquecem os campos de dados de compra. Etiquetas, campos de dados e segmentação cobre como cada etiqueta é montada.
Campos de compra em branco em contatos mais antigos
Os campos de dados de compra são criados automaticamente na primeira sincronização de um contato. Se aparecerem em branco em contatos que já estavam no seu público, o Rebuild merge fields (ou uma ressincronização) os preenche. Etiquetas, campos de dados e segmentação explica o que cada campo registra.
“A receita de campanhas do Mailchimp não bate com a da minha loja”
Uma queda repentina para $0 em todas as campanhas significa que os pedidos pararam de chegar ao Mailchimp: verifique primeiro o Queue Monitor e o Cron Monitor. Quais pedidos contam é uma configuração: Order Statuses to Sync (Configuration → Ecommerce Sync) decide o que conta para a receita, e os cancelamentos são enviados com os totais zerados, então nunca a inflam. Crédito indo para a campanha errada foi eliminado por design: a extensão nunca atribui uma campanha a um pedido; a atribuição é o próprio rastreamento de cliques do Mailchimp. Quando os números ainda assim divergem, cada superfície mede uma fatia diferente, e Por que seus números diferem do Mailchimp traz o detalhamento completo.
Os produtos aparecem errados no Mailchimp: sem imagens, preços estranhos, detalhes desatualizados
Corrija primeiro os dados do catálogo: um produto sem imagem no papel Base sincroniza sem imagem, e o preço vem do escopo de visualização de loja que você edita. Depois envie de novo: Push Now na aba Mailchimp do produto o recoloca na fila com prioridade em tempo real, e a ação em massa Push to Mailchimp ou bin/magento mailchimp:resync sempre enviam, mesmo quando nada mudou no Magento. O detalhe da linha na Entity Queue mostra o payload exato que saiu, então confira logo após o envio. Os preços sincronizam como o preço final do catálogo, sem imposto adicionado, e o Mailchimp mostra um preço de venda ativo por produto, o que é esperado. Os gift cards do Adobe Commerce carregam um preço representativo (o menor valor configurado, ou o mínimo de valor aberto), e um produto de tipo personalizado com preço zero recai em 0.00. Os totais de pedido e os preços de linha sempre vêm dos valores efetivamente pagos, então um gift card de valor aberto é relatado com o valor exato que o comprador escolheu. Como funciona a sincronização explica o que é enviado e quando.
Os campos de dados mapeados chegam vazios ou param de atualizar
Os mapeamentos personalizados ficam na grade Data fields (Configuration → Contact Sync) e são editados no escopo de visualização de loja, porque cada visualização de loja mapeia para o seu próprio público. Crie primeiro o campo de público (merge field) no Mailchimp: o menu suspenso lista apenas as etiquetas que existem naquele público, então um erro de digitação nunca pode ser salvo. Salvar uma mudança real recoloca na fila cada contato afetado, e Rebuild merge fields força a mesma atualização, que também preenche campos que aparecem em branco em contatos anteriores ao mapeamento. Se um campo silenciosamente para de atualizar, a causa habitual é que a etiqueta dele foi excluída no Mailchimp: recrie-a lá ou limpe a linha. Etiquetas, campos de dados e segmentação cobre cada campo.
Visitantes não aparecem depois de abandonar carrinhos
O Mailchimp precisa de um endereço de e-mail para enviar um lembrete, e a extensão captura um assim que um visitante o digita em qualquer lugar: no checkout, em uma caixa de boletim informativo ou ao chegar por um link de campanha. Se os carrinhos de visitantes não aparecem, confirme que a visualização de loja está conectada; um visitante que nunca compartilhou um e-mail em lugar nenhum não pode ser lembrado, e todos os outros carrinhos fluem por conta própria. Recupere carrinhos abandonados mostra a jornada completa.
“Minha automação de carrinho abandonado nunca envia um e-mail”
Os e-mails de recuperação são enviados pela sua automação do Mailchimp, não pela extensão, então comece no painel Abandoned Carts do Dashboard: se os carrinhos estão sendo contados mas nada é enviado, siga o link Set up automation do painel para concluir a automação no Mailchimp. Se Total Carts permanecer em 0, abra o Cron Monitor (os carrinhos seguem pela lane Boost) e o Queue Monitor, e confirme que aquela visualização de loja está conectada. Um pedido concluído remove o carrinho dele do Mailchimp imediatamente, então os compradores nunca recebem um lembrete de algo que já compraram, e os links de recuperação para clientes registrados chegam à página de login por design. Recupere carrinhos abandonados percorre a jornada completa.
O botão do Pixel não liga
O botão só é ativado depois que o Mailchimp confirma a ativação, então, quando ele permanece desligado, o próprio popup da extensão informa o motivo e nomeia a visualização de loja envolvida. O caso comum são duas visualizações de loja compartilhando um mesmo endereço web: cada Pixel vive no seu próprio domínio, então uma das visões o carrega. Os eventos de comportamento continuam fluindo no lado do servidor para cada visualização de loja de qualquer forma, então os segmentos e as Jornadas do Cliente continuam funcionando. O Pixel do Mailchimp e eventos de comportamento tem os detalhes.
O Pixel está ativo, mas nada dispara na loja
Abra a loja com as ferramentas de desenvolvedor do seu navegador e a página informa qual dos três comportamentos conhecidos você está vendo. Se o seu aviso de consentimento de cookies ainda não foi aceito, o Pixel fica retido de propósito: aceite-o e o script é injetado em cerca de um segundo. Se o console mostrar uma violação de Content-Security-Policy citando chimpstatic.com ou mcjs.prd.a.intuit.com, o bloqueio vem de uma CSP definida fora do Magento: adicione os dois hosts a script-src e connect-src ali. Se for uma incompatibilidade de hash de script inline no checkout, atualize a extensão: cada versão traz o hash aprovado atual. Os eventos do lado do servidor continuam fluindo de qualquer forma, na aba Events Tracking. O Pixel do Mailchimp e eventos de comportamento explica as duas metades.
A caixa de seleção de inscrição não aparece
Três verificações rápidas: limpe o cache do Magento; veja se o Pixel está ativo naquela visualização de loja (a caixa de seleção do checkout sai de cena de propósito, para que a página de confirmação não traga prompts sobrepostos); e confirme que Sync Newsletter Subscribers está ativado nas configurações de Contact Sync, que é o que disponibiliza as superfícies de opt-in. Faça seu público crescer cobre as duas caixas de seleção.
Cancelamentos de assinatura feitos no Mailchimp não chegam ao Magento
Os webhooks se registram sozinhos durante o Go Live, então comece pela superfície de auditoria: abra Webhooks no menu de operações, clique em Check Webhooks e escolha a visualização de loja. Uma loja saudável mostra “Webhooks are active”; se ela oferecer Register, clique nele (ou em Re-register se a URL da sua loja mudou). Quando o registro falha, a janela explica o motivo, e o caso comum é o Mailchimp não conseguir alcançar a URL da sua loja (firewall, modo de manutenção, ou um site de staging protegido por senha): torne-a publicamente acessível e registre novamente. Os cancelamentos de assinatura se aplicam no momento em que chegam; as mudanças de perfil também precisam de Sync Newsletter Subscribers ativado. Cancelamento de assinatura e consentimento cobre o fluxo de mão dupla.
Os e-mails de confirmação chegam duas vezes, ou os contatos inscritos ficam em “pending”
Trate o botão Double Opt-In da extensão (Configuration → Contact Sync) como o único controle de confirmação: com ele ativado, o Mailchimp envia o único e-mail de confirmação e assume a etapa de confirmar. Deixe a configuração “Need to Confirm” do próprio Newsletter do Magento desativada, a menos que você queira deliberadamente um segundo e-mail de confirmação: com os dois ativados, os contatos inscritos recebem dois e-mails e permanecem pendentes até clicarem no link do Mailchimp. Se um cliente se inscreve de novo mas nunca reaparece, o API Log mostra a entrada bloqueada por conformidade: o Mailchimp protege contatos que cancelaram a assinatura por um link de campanha, e eles voltam por meio de um formulário de inscrição hospedado pelo Mailchimp. Cancelamento de assinatura e consentimento explica o consentimento nas duas direções.
Mudamos de domínio e a sincronização pausou
Ela pausou de propósito: essa é a proteção que evita que uma loja movida ou clonada escreva no lugar errado. Quando o endereço da sua loja muda, após uma mudança de domínio, uma migração de servidor ou um ambiente copiado, a extensão pausa aquela visualização de loja e um aviso no admin explica o que aconteceu. Desconecte e reconecte a visualização de loja e a sincronização é retomada; Conecte sua conta do Mailchimp percorre os passos de conexão.
Um aviso diz que nossa loja vinculada do Mailchimp foi excluída no Mailchimp
Nada é perdido: a sincronização nunca escreve contra uma loja ausente, e as mudanças na fila aguardam com segurança em Pending. Ou restaure a loja do lado do Mailchimp (uma verificação de saúde a cada hora libera a pausa sozinha), ou mude a Configuration para a visualização de loja afetada, desconecte pelo popup de conexão e reconecte pelo Setup Wizard; os dados ressincronizam automaticamente. Se já existir uma loja do Mailchimp no mesmo domínio quando você reconectar, o assistente se oferece para arquivá-la e criar uma nova, com o seu público intocado. Está conectado e sincronizando bem? mostra cada sinal de conexão em um só lugar.
A atividade nova sincroniza, mas o histórico trava (ou o contrário)
Boost e Backfill rodam cada um em seu próprio grupo de cron, então uma hospedagem que só roda o grupo padrão do Magento inicia apenas metade do motor. Peça à sua hospedagem para confirmar que o cron do Magento roda todos os grupos; o Cron Monitor mostra o estado de cada grupo, para você ver exatamente qual está esperando. Como o motor de sincronização funciona explica as duas lanes.
“Meu público é muito maior que minha lista de inscritos” (contagem de contatos e cobrança)
O volume de contatos é limitado por design e visualizado antes de qualquer sincronização: o Setup Wizard mostra uma estimativa para a janela de histórico que você escolher (3, 12, 24, 36 ou 48 meses, ou tudo), então uma janela mais curta limita a contagem. Sync Customers sincroniza apenas clientes que fizeram um pedido, nunca toda a sua base de clientes, e Default Subscription Status for Synced Customers decide se eles entram como inscritos ou não inscritos. Se o público já está maior do que você quer, arquive contatos no Mailchimp: contatos arquivados não são cobrados e voltam sozinhos se o comprador comprar de novo. Como funciona a sincronização explica exatamente quem sincroniza e quando.
Uma regra de promoção está travada em “Action needed”
Primeiro confirme que Sync Promo Rules & Codes e Enable Ecommerce Sync estão ambos como Yes (Configuration → Ecommerce Sync). Quando o Mailchimp recusa uma regra (um desconto zero, datas ausentes, um nome ausente), apenas aquela regra aguarda: abra a aba Entity Queue, filtre o Status por “Action needed” e leia o Status Message para o motivo exato. Corrija a Cart Price Rule no Magento e depois clique no link Retry da linha: apenas salvar a regra de novo não reativa a linha. Todo o resto continua sincronizando enquanto ela aguarda. Acompanhe sua sincronização mostra como ler a fila.
Um produto aparece como “Not supported” na Entity Queue
Esse status âmbar aparece apenas para um produto de tipo personalizado (um gift card do Adobe Commerce ou um tipo de uma extensão de terceiros) que está sem SKU ou sem nome: nada foi enviado, e o Status Message nomeia o tipo do produto. Produtos de tipo personalizado com SKU e nome sincronizam automaticamente com um payload de melhor esforço, registrado no API Log como generic_type_fallback. Adicione o SKU ou o nome ausente e depois use o Retry da linha na Entity Queue (ou execute Resync All Data em Manage Connection, na aba Manage); apenas salvar de novo não limpa a linha. Um pedido que contém o produto para em “Action needed” nomeando os SKUs dele; assim que o produto corrigido tiver sincronizado, use o Retry na linha do pedido. Ressincronizar e ferramentas de linha de comando tem os detalhes.
Ainda travado?
Abra o Queue Monitor, encontre o registro que não sincroniza e leia o erro completo do Mailchimp; ele geralmente indica a solução. Se você ainda estiver bloqueado, o suporte da ebizmarts está a um e-mail de distância: inclua a sua versão do Magento, a versão do banco de dados, a versão da extensão e uma captura de tela do erro.