Dépannage

La plupart des problèmes se ramènent à une poignée de causes. Ils sont classés ici selon la fréquence à laquelle les marchands les rencontrent, et chacun a sa solution.

« J’ai tout connecté mais rien ne se synchronise »

C’est presque toujours l’une de deux causes, et chacune se vérifie rapidement.

1. Le cron ne s’exécute pas. La synchronisation passe par une file d’attente en arrière-plan : sans cron, rien n’est envoyé. L’extension vous prévient toutefois : la carte Mailchimp du Dashboard de l’admin passe à Background sync paused, et la tuile System status du Cron Monitor nomme la tâche planifiée bloquée. Pour confirmer, ouvrez l’onglet Queue Monitor (Marketing → Intuit Mailchimp → Dashboard) : si Pending ne cesse d’augmenter sans jamais se vider, le cron est en cause. Demandez à votre hébergeur de confirmer que le cron de Magento est bien planifié ; une fois qu’il s’exécute, l’onglet Cron Monitor affiche chaque tâche en vert.

2. Votre base de données est en dessous du minimum requis. L’extension nécessite MySQL 8.0+ ou MariaDB 10.6+ pour la synchronisation en arrière-plan. Si le cron s’exécute et que Pending ne se vide toujours pas, vérifiez la version de votre base de données et mettez-la à niveau si elle est en dessous du minimum.

L’installation ou la mise à niveau échoue (erreurs setup:upgrade ou di:compile)

Lors d’une installation avec Composer, celui-ci applique les prérequis pour vous (Magento 2.4.6+, PHP 8.1 à 8.4, MySQL 8.0+ ou MariaDB 10.6+) : un refus net signifie donc que l’environnement doit atteindre ce socle minimal. Une installation zip de l’extension seule compile et fonctionne ; PulseCore est facultatif et n’est pas embarqué. Ajoutez les paquets PulseCore et Pulse bridge uniquement si vous voulez les parcours Pulse, chacun décompressé sous app/code, puis relancez la même séquence d’installation. setup:upgrade ajoute des colonnes à quelques tables du cœur de Magento, les boutiques volumineuses devraient donc l’exécuter pendant une fenêtre de maintenance. Si une compilation échoue après une mise à jour, passez au dernier correctif publié puis relancez setup:upgrade, di:compile et cache:flush. Installation contient le pas-à-pas complet.

Ce que signifient les libellés de statut

Les commandes et les clients affichent l’éventail complet des statuts dans leurs grilles ; la grille des produits n’affiche que Synced ou Not in Mailchimp, l’état complet d’un produit se trouvant dans l’Entity Queue et dans l’onglet Mailchimp du produit lui-même :

Pourquoi « Not in Mailchimp » ? Ce n’est pas une erreur : l’enregistrement était hors du périmètre de synchronisation. Sa vue de boutique n’est pas connectée, il est plus ancien que votre fenêtre de synchronisation, ou il s’agit d’une commande historique en dehors de votre sélection de revenus confirmés. Par défaut, les revenus confirmés correspondent aux statuts processing, complete et closed : cette sélection détermine quelles commandes historiques sont importées et quelles commandes comptent dans les revenus et la valeur vie client. Les nouvelles commandes se synchronisent au fil de l’eau et restent à jour à chaque changement de statut.

Erreurs « Invalid email », mais impossible de trouver ce client

Mailchimp rejette les adresses qui semblent factices ou mal formées. Les vrais e-mails d’invités se synchronisent sans problème ; seules les adresses invalides sont exclues, et c’est voulu. Pour en corriger une, ouvrez la commande et corrigez l’e-mail de facturation, puis ouvrez l’Entity Queue et cliquez sur Retry sur la ligne de la commande : une ligne encore en Error continue de réessayer d’elle-même et récupère la correction, tandis qu’une ligne en Action needed attend votre Retry. Sur les boutiques de test, les données d’exemple contiennent souvent des e-mails fictifs que Mailchimp rejettera : c’est attendu, ce n’est pas un défaut.

Problèmes de connexion

• Une bannière indique « Mailchimp is disconnected » : la solution accompagne le message. La bannière embarque son propre bouton Reconnect to Mailchimp, et un clic rétablit la liaison. Si vous avez un jour besoin du chemin plus complet, basculez Configuration sur la vue de boutique et ouvrez Manage Connection : déconnectez depuis l’onglet Manage, reconnectez via l’assistant, puis vérifiez que la vue de boutique pointe toujours vers la bonne audience.
• L’en-tête affiche toujours « Let’s connect » après l’ajout d’un compte : l’en-tête de la configuration continue d’afficher son bouton Log in to Mailchimp, car ajouter un compte et connecter une vue de boutique sont deux étapes distinctes. Basculez la portée sur une vue de boutique, puis choisissez Connect store.
• « Connect store » n’affiche aucune boutique : soit aucun compte n’est encore connecté, soit chaque boutique Mailchimp est déjà liée à une autre vue de boutique. Ajoutez un compte, ou créez une nouvelle boutique dans Mailchimp.
• La fenêtre de connexion n’aboutit jamais : autorisez les popups pour votre domaine d’admin, et assurez-vous que votre serveur peut joindre Mailchimp en HTTPS.

« Ma clé API est signalée comme invalide, alors qu’elle est toute neuve »

Vérifiez d’abord le format : une clé Mailchimp se termine par le suffixe de son centre de données (par exemple -us21), générez donc une clé neuve et collez-la en entier. Si la clé est réellement valide, le journal sous var/log enregistre chaque appel de validation avec la clé masquée : une ligne avec HTTP 401 signifie que Mailchimp a rejeté la clé elle-même, tandis qu’une erreur de transport sans code de statut signifie que votre serveur n’a pas pu joindre Mailchimp ; demandez alors à votre hébergeur d’autoriser le HTTPS sortant vers <dc>.api.mailchimp.com. Une clé qui devient invalide plus tard se repère sur la page Mailchimp accounts : l’indicateur de santé du compte change dans l’heure, et Update key la corrige sur place, sans déconnecter la boutique. Connecter votre compte Mailchimp détaille chaque étape.

Les tags n’apparaissent pas sur les contacts

Les tags de catégorie s’appliquent à chaque commande synchronisée dès l’instant où vous les activez, et une resynchronisation applique aussi les tags à votre historique de commandes : les tags ne sont jamais dupliqués, la resynchronisation est donc toujours sans risque. Les achats en invité sont taggués eux aussi lorsque Update Audience Members from Guest Orders est activé. Tags, champs de données et segmentation explique comment chaque tag est construit.

Champs d’achat vides sur des contacts plus anciens

Les champs de données d’achat sont créés automatiquement lors de la première synchronisation d’un contact. S’ils apparaissent vides sur des contacts qui étaient déjà dans votre audience, Rebuild merge fields (ou une resynchronisation) les remplit. Tags, champs de données et segmentation explique ce que chaque champ suit.

« Les revenus de campagne dans Mailchimp ne correspondent pas à ma boutique »

Une chute soudaine à 0 $ sur toutes les campagnes signifie que les commandes n’atteignent plus Mailchimp : vérifiez d’abord le Queue Monitor et le Cron Monitor. Le choix des commandes prises en compte est un paramètre : Order Statuses to Sync (Configuration → Ecommerce Sync) décide de ce qui compte dans les revenus, et les annulations sont envoyées avec des totaux remis à zéro, elles ne les gonflent donc jamais. Un crédit attribué à la mauvaise campagne est exclu par conception : l’extension n’assigne jamais de campagne à une commande ; l’attribution relève du suivi des clics de Mailchimp lui-même. Pour lire l’attribution que votre boutique a enregistrée, campagne par campagne, et la prouver face au Dashboard, ouvrez Le rapport Campaign Performance. Quand les chiffres divergent malgré tout, chaque surface mesure une tranche différente, et Pourquoi vos chiffres diffèrent de ceux de Mailchimp en donne le détail complet.

Les produits semblent incorrects dans Mailchimp : images manquantes, prix étranges, détails obsolètes

Corrigez d’abord les données du catalogue : un produit sans image dans le rôle Base se synchronise sans image, et le prix provient de la portée de vue de boutique que vous modifiez. Puis renvoyez le produit : Push Now, dans l’onglet Mailchimp du produit, le remet en file à priorité temps réel, et l’action de masse Push to Mailchimp envoie toujours, même quand rien n’a changé dans Magento. En ligne de commande, bin/magento mailchimp:resync --force fait de même ; sans --force, la commande ne fait que prévisualiser ce qui serait renvoyé. Le détail de la ligne dans l’Entity Queue montre la charge utile exacte qui est partie, consultez-le donc peu après l’envoi. Les prix se synchronisent comme le prix final du catalogue, sans taxe ajoutée, et Mailchimp affiche un seul prix de vente actif par produit, ce qui est attendu. Les cartes cadeaux Adobe Commerce portent un prix représentatif (le plus petit montant configuré, ou le minimum du montant libre), et un produit de type personnalisé à prix nul retombe à 0,00. Les totaux de commande et les prix de ligne proviennent toujours des montants réellement payés : une carte cadeau à montant libre est donc déclarée au montant exact choisi par l’acheteur. Comment fonctionne la synchronisation explique ce qui est envoyé et quand.

Les prix ont changé dans Magento mais Mailchimp affiche toujours les anciens

Quand la boutique en ligne facture le nouveau prix et que Mailchimp garde l’ancien, la cause habituelle tient à la façon dont le prix a été écrit. L’extension repère qu’un produit a changé en surveillant sa date de dernière modification, et toutes les façons de fixer un prix ne font pas bouger cette date. L’import de produits de Magento, l’API standard d’enregistrement des produits et l’action de masse Mettre à jour les attributs de l’admin la font tous avancer : les prix écrits par ces voies atteignent Mailchimp en une minute environ. L’API de Magento dédiée aux prix spéciaux en masse ne la fait pas bouger, pas plus que tout ce qui écrit directement dans la base de données : ces changements sont donc invisibles pour l’extension, sans erreur ni avertissement. Pour vérifier, ouvrez le produit et comparez sa date Last Updated au Last Sync affiché sur son onglet Mailchimp, ainsi qu’au moment où le prix a réellement changé : un nouveau prix à côté d’un Last Updated ancien confirme le diagnostic. Orientez votre ERP, PIM ou outil de repricing vers une voie qui met la date à jour, puis utilisez Push Now, dans l’onglet Mailchimp du produit, ou l’action de masse Push to Mailchimp, pour corriger ce qui se trouve déjà dans Mailchimp. Si des intégrations écrivent vos prix, cela vaut la peine de le confirmer avec ceux qui les ont construites.

Les champs de données mappés arrivent vides ou cessent de se mettre à jour

Les mappages personnalisés vivent dans la grille Data fields (Configuration → Contact Sync) et se modifient à la portée de la vue de boutique, car chaque vue de boutique correspond à sa propre audience. Créez d’abord le champ d’audience dans Mailchimp : la liste déroulante ne propose que les balises de fusion qui existent dans cette audience, une faute de frappe ne peut donc jamais être enregistrée. Enregistrer un vrai changement remet en file chaque contact concerné, et Rebuild merge fields force le même rafraîchissement, ce qui remplit aussi les champs vides sur les contacts antérieurs au mappage. Si un champ cesse discrètement de se mettre à jour, la cause habituelle est que sa balise a été supprimée dans Mailchimp : recréez-la côté Mailchimp ou videz la ligne. Tags, champs de données et segmentation couvre chaque champ.

Les invités n’apparaissent pas après avoir abandonné leur panier

Mailchimp a besoin d’une adresse e-mail pour envoyer une relance, et l’extension en capture une dès l’instant où un invité la saisit quelque part : au moment du paiement, dans un encart newsletter, ou en arrivant depuis un lien de campagne. Si les paniers d’invités n’apparaissent pas, vérifiez que la vue de boutique est connectée ; un invité qui n’a jamais communiqué d’e-mail nulle part ne peut pas être relancé, et tous les autres paniers circulent d’eux-mêmes. Récupérer les paniers abandonnés montre le parcours complet.

« Mon automatisation de panier abandonné n’envoie jamais d’e-mail »

Les e-mails de récupération sont envoyés par votre automatisation Mailchimp, pas par l’extension : commencez donc par le panneau Abandoned Carts du Dashboard. Si les paniers sont bien comptés mais que rien ne part, suivez le lien Set up automation du panneau pour finaliser l’automatisation dans Mailchimp. Si le compteur Abandoned du panneau reste à 0, ouvrez le Cron Monitor (les paniers passent par la voie Boost) et le Queue Monitor, et vérifiez que cette vue de boutique est connectée. Une commande finalisée retire aussitôt son panier de Mailchimp, les acheteurs ne reçoivent donc jamais de relance pour un article déjà acheté, et les liens de récupération des clients enregistrés mènent volontairement à la page de connexion. Récupérer les paniers abandonnés parcourt tout le trajet.

L’interrupteur du Pixel refuse de s’activer

L’interrupteur ne bascule qu’une fois l’activation confirmée par Mailchimp : s’il reste éteint, la fenêtre de l’extension vous en donne la raison et nomme la vue de boutique concernée. Le cas courant est celui de deux vues de boutique qui partagent la même adresse web : chaque Pixel vit sur son propre domaine, une seule des deux vues le porte donc. Les événements comportementaux continuent, quoi qu’il arrive, de circuler côté serveur pour chaque vue de boutique, vos segments et vos parcours client continuent donc de fonctionner. Le Pixel Mailchimp et les événements comportementaux donne les détails.

Le Pixel est actif mais rien ne se déclenche sur la boutique en ligne

Ouvrez la boutique en ligne avec les outils de développement de votre navigateur : la page vous indique lequel des trois comportements connus vous observez. Si votre bannière de consentement aux cookies n’a pas encore été acceptée, le Pixel est retenu volontairement : acceptez-la et le script s’injecte en une seconde environ. Si la console affiche une violation de Content-Security-Policy citant chimpstatic.com ou mcjs.prd.a.intuit.com, le blocage vient d’une CSP définie en dehors de Magento : ajoutez-y les deux hôtes à script-src et connect-src. S’il s’agit d’une différence de hachage de script inline sur la page de paiement, mettez l’extension à jour : chaque version embarque le hachage approuvé courant. Les événements côté serveur continuent de circuler quoi qu’il arrive, dans l’onglet Events Tracking. Le Pixel Mailchimp et les événements comportementaux explique les deux moitiés.

La case d’abonnement ne s’affiche pas

Trois vérifications rapides : videz le cache de Magento ; regardez si le Pixel est actif sur cette vue de boutique (la case de la page de paiement s’efface volontairement, pour que la page de confirmation ne porte aucune invite en double) ; et vérifiez que Sync Newsletter Subscribers est activé dans les paramètres Contact Sync, car c’est lui qui rend disponibles les surfaces d’opt-in. Développer votre audience couvre les deux cases.

Les désabonnements effectués dans Mailchimp n’atteignent pas Magento

Les webhooks s’enregistrent d’eux-mêmes lors du Go Live, commencez donc par la surface d’audit : ouvrez Webhooks depuis le menu d’exploitation, cliquez sur Check Webhooks et choisissez la vue de boutique. Une boutique saine affiche « Webhooks are active » ; si elle propose Register à la place, cliquez dessus (ou Re-register si l’URL de votre boutique a changé). Quand l’enregistrement échoue, la fenêtre en explique la raison, et le cas courant est que Mailchimp ne parvient pas à joindre l’URL de votre boutique (pare-feu, mode maintenance, ou site de préproduction protégé par mot de passe) : rendez-la accessible publiquement et enregistrez de nouveau. Les désabonnements s’appliquent dès leur arrivée ; les changements de profil nécessitent aussi que Sync Newsletter Subscribers soit activé. Désabonnements et consentement couvre le flux dans les deux sens.

Les e-mails de confirmation arrivent en double, ou les abonnés restent en attente

Le Double Opt-In se règle dans Mailchimp : la ligne Double Opt-In de Configuration → Contact Sync est en lecture seule et reflète le réglage de votre audience, qui se trouve dans Mailchimp sous Audience → Settings → Audience name and defaults. Lorsqu’il est activé, Mailchimp envoie le seul e-mail de confirmation et pilote l’étape de confirmation. Laissez le réglage « Need to Confirm » de la Newsletter de Magento désactivé, sauf si vous voulez délibérément un second e-mail de confirmation : avec les deux activés, les abonnés reçoivent deux e-mails et restent en attente jusqu’à ce qu’ils cliquent sur le lien de Mailchimp. Si un client se réabonne mais ne réapparaît jamais, l’API Log montre l’entrée verrouillée pour conformité : Mailchimp protège les contacts qui se sont désabonnés via un lien de campagne, et ils se réinscrivent via un formulaire d’inscription hébergé par Mailchimp. Désabonnements et consentement explique le consentement dans les deux directions.

Nous avons changé de domaine et la synchronisation s’est mise en pause

Elle s’est mise en pause à dessein : c’est la protection qui empêche une boutique déplacée ou clonée d’écrire au mauvais endroit. Quand l’adresse de votre boutique change, après un changement de domaine, une migration de serveur ou un environnement copié, l’extension met cette vue de boutique en pause et une bannière d’admin explique ce qui s’est passé. Déconnectez puis reconnectez la vue de boutique et la synchronisation reprend ; Connecter votre compte Mailchimp détaille les étapes de connexion. Avant de le faire, ce qui se passe si vous déconnectez ou désinstallez explique ce que cela supprime et ce qui revient.

Une bannière indique que notre boutique Mailchimp liée a été supprimée dans Mailchimp

Rien n’est perdu : la synchronisation n’écrit jamais vers une boutique absente, et les changements en file attendent en toute sécurité au statut Pending. Soit vous restaurez la boutique côté Mailchimp (une vérification de santé horaire lève la pause d’elle-même), soit vous basculez Configuration sur la vue de boutique concernée, vous déconnectez depuis la fenêtre de connexion et vous reconnectez via le Setup Wizard ; les données se resynchronisent automatiquement. Si une boutique Mailchimp existe déjà sur le même domaine au moment de la reconnexion, l’assistant propose de l’archiver et d’en créer une neuve, sans toucher à votre audience. Tout est-il bien connecté et synchronisé ? rassemble tous les signaux de connexion au même endroit. Avant de le faire, ce qui se passe si vous déconnectez ou désinstallez explique ce que cela supprime et ce qui revient.

L’activité récente se synchronise mais l’historique stagne (ou l’inverse)

Boost s’exécute dans son propre groupe cron (ebizmarts_mailchimp_boost) et Backfill dans le groupe principal de l’extension (ebizmarts_mailchimp), et aucun des deux n’est le groupe par défaut de Magento. Un hébergeur qui restreint le cron à certains groupes peut démarrer une voie et pas l’autre : demandez donc à votre hébergeur de confirmer que le cron de Magento exécute tous les groupes ; le Cron Monitor montre l’état de chaque groupe, vous voyez donc exactement lequel attend. Comment s’exécute le moteur de synchronisation explique les deux voies.

« Mon audience est bien plus grande que ma liste d’abonnés » (nombre de contacts et facturation)

Le volume de contacts est prévisualisé avant toute synchronisation : le Setup Wizard affiche une estimation pour les choix que vous faites, et c’est cette estimation qu’il faut retenir, car elle compte tous les contacts qui seront créés, abonnés compris. La fenêtre d’historique que vous choisissez (3, 12, 24, 36 ou 48 mois, ou tout l’historique) borne l’historique des commandes et des paniers ainsi que les clients importés avec lui ; elle ne borne pas les abonnés à la newsletter, qui se synchronisent intégralement quelle que soit la fenêtre. Sync Customers ne synchronise jamais que les clients ayant passé une commande, jamais toute votre base de clients, et Default Subscription Status for Synced Customers décide s’ils arrivent comme abonnés ou non-abonnés. Si l’audience est déjà plus grande que souhaité, archivez des contacts dans Mailchimp : les contacts archivés ne sont pas facturés et reviennent d’eux-mêmes si l’acheteur commande à nouveau. Comment fonctionne la synchronisation explique exactement qui se synchronise et quand.

Une règle promotionnelle est bloquée sur « Action needed »

Vérifiez d’abord que Sync Promo Rules & Codes et Enable Ecommerce Sync sont tous deux sur Yes (Configuration → Ecommerce Sync). Quand Mailchimp décline une règle (remise nulle, dates manquantes, nom manquant), seule cette règle attend : ouvrez l’onglet Entity Queue, filtrez la colonne Status sur « Action needed » et lisez le Status Message pour connaître la raison exacte. Corrigez la Cart Price Rule dans Magento, puis cliquez sur le lien Retry de la ligne : réenregistrer la règle ne suffit pas à relancer la ligne. Tout le reste continue de se synchroniser pendant ce temps. Garder un œil sur votre synchronisation montre comment lire la file.

Un produit affiche « Not supported » dans l’Entity Queue

Ce statut ambre n’apparaît que pour un produit de type personnalisé (une carte cadeau Adobe Commerce ou un type issu d’une extension tierce) auquel il manque son SKU ou son nom : rien n’a été envoyé, et le Status Message nomme le type de produit. Les produits de type personnalisé dotés d’un SKU et d’un nom se synchronisent automatiquement avec une charge utile au mieux des données disponibles, consignée dans l’API Log sous generic_type_fallback. Ajoutez le SKU ou le nom manquant, puis utilisez le Retry de la ligne dans l’Entity Queue (ou lancez Resync All Data depuis Manage Connection, dans l’onglet Manage) ; réenregistrer le produit ne suffit pas à débloquer la ligne. Une commande contenant ce produit se place en « Action needed » en nommant ses SKU ; une fois le produit corrigé synchronisé, utilisez Retry sur la ligne de la commande. Resynchronisation et outils en ligne de commande donne les détails.

Toujours bloqué ?

Ouvrez le Queue Monitor, trouvez l’enregistrement qui ne se synchronise pas et lisez l’erreur Mailchimp complète ; elle nomme généralement la solution. Si vous restez bloqué, le support ebizmarts est à un e-mail de vous : joignez votre version de Magento, la version de votre base de données, la version de l’extension et une capture d’écran de l’erreur.