Où va exactement une commande entre le moment où un acheteur clique sur « Valider la commande » et celui où le colis part de l’entrepôt ? Pour un développeur qui prend en main sa première boutique WooCommerce, cette question mérite une réponse précise, parce que la quasi-totalité des personnalisations métier — envoi d’un email, déclenchement d’une synchronisation, mise à jour d’un stock externe — s’accroche à un moment précis de ce cycle, jamais au hasard.
WooCommerce structure ce parcours autour d’un nombre restreint de statuts natifs, chacun associé à des hooks spécifiques qui permettent d’intervenir sans modifier le cœur du logiciel. Comprendre cette cartographie évite l’erreur classique du développeur débutant : chercher à personnaliser une étape en modifiant directement un fichier du plugin, plutôt qu’en s’accrochant au bon hook au bon moment.
Les statuts natifs, dans l’ordre du parcours normal
Une commande WooCommerce prend l’un des statuts suivants, dans un ordre qui n’est pas figé mais qui suit une logique métier claire :
pending: commande créée, paiement non encore initiéon-hold: paiement en attente de confirmation (virement, chèque)processing: paiement reçu, commande à préparercompleted: commande préparée et expédiéecancelled: commande annulée avant paiement effectifrefunded: commande remboursée totalement ou partiellementfailed: tentative de paiement échouéecheckout-draft: commande créée par les blocs de paiement mais jamais soumise
Ce dernier statut, checkout-draft, mérite une attention particulière : il correspond aux paniers abandonnés au stade même du formulaire de paiement, une donnée précieuse pour comprendre où les acheteurs renoncent, mais qui ne doit jamais être confondue avec une commande réellement passée.
Les tables impliquées à chaque étape
Depuis la généralisation du High-Performance Order Storage, une commande et ses métadonnées vivent dans des tables dédiées plutôt que dans la table générique wp_posts partagée avec tous les autres contenus WordPress. La structure simplifiée du parcours de données ressemble à ceci :
wc_orders (données principales de la commande : statut, total, client)
├── wc_order_operational_data (données opérationnelles : date de paiement, IP, agent)
├── wc_order_addresses (adresses de facturation et de livraison)
├── wc_order_meta (métadonnées additionnelles, y compris celles des extensions)
└── wc_orders_meta appliqué aux remboursements associés (type de commande "shop_order_refund")
Un remboursement, contrairement à une idée répandue, n’est pas une simple modification de la commande d’origine : il crée un enregistrement de commande distinct, de type shop_order_refund, lié à la commande initiale. Cette distinction explique pourquoi un remboursement partiel peut coexister avec un statut de commande qui reste completed : la commande d’origine n’est jamais réécrite, elle est complétée par un enregistrement lié.
Les hooks qui accompagnent chaque transition
Chaque changement de statut déclenche des hooks génériques et des hooks spécifiques au statut atteint :
add_action( 'woocommerce_order_status_changed', function( $order_id, $ancien_statut, $nouveau_statut, $order ) {
error_log( sprintf( 'Commande %d : %s vers %s', $order_id, $ancien_statut, $nouveau_statut ) );
}, 10, 4 );
add_action( 'woocommerce_order_status_completed', function( $order_id ) {
// déclenché uniquement à l'entrée dans le statut "completed"
} );
Cette distinction entre hook générique et hook spécifique au statut atteint est fondamentale : le premier permet d’observer toutes les transitions, le second de n’agir que sur une transition précise, sans avoir à comparer manuellement l’ancien et le nouveau statut à chaque exécution.
Le remboursement, une étape à part entière
Le remboursement mérite d’être traité comme une étape du cycle de vie à part entière, pas comme une annulation rétroactive. Un remboursement complet via l’API de WooCommerce (wc_create_refund()) crée une transaction de remboursement, met à jour les totaux calculés de la commande d’origine, et peut déclencher, selon la passerelle de paiement utilisée, un appel réseau vers le prestataire de paiement pour restituer réellement les fonds — deux opérations distinctes qu’il ne faut pas confondre : l’enregistrement du remboursement côté WooCommerce, et le remboursement effectif côté prestataire de paiement.
Un statut de commande ne décrit jamais un simple libellé affiché au client : il conditionne quels hooks se déclenchent, quelles données se figent, et quelles actions restent encore possibles sur la commande.
Ce que cette cartographie ne couvre pas
Cette présentation du cycle de vie ne traite pas des extensions de fidélité qui ajoutent parfois leurs propres statuts personnalisés au-dessus de ce socle natif ; ce sujet mérite un traitement séparé, propre à chaque extension concernée.
En résumé
Le cycle de vie d’une commande WooCommerce suit un enchaînement de statuts précis, chacun associé à des tables et des hooks spécifiques. Comprendre cette cartographie, du panier abandonné au remboursement partiel, permet d’intervenir au bon moment sans jamais avoir à modifier le cœur du logiciel : chaque personnalisation métier trouve, quelque part dans ce cycle, le hook qui lui correspond exactement.
