Architecture d’un système de retours et remboursements WooCommerce

Une demande de retour, contrairement à une commande, n’a pas de représentation native dans WooCommerce : il n’existe pas de type d’objet dédié pour « ceci est une demande de retour en cours d’examen ». La plupart des boutiques bricolent ce suivi avec des statuts de commande détournés ou des e-mails échangés hors système, une approche qui tient jusqu’à ce que le volume de retours dépasse quelques dizaines par mois.

Ce schéma d’architecture, construit pour un client vendant du mobilier avec un taux de retour élevé, propose une structure claire : une entité de retour distincte de la commande, un cycle de statuts explicite, et un remboursement qui s’appuie sur l’API native de WooCommerce plutôt que sur un ajustement manuel du solde client. La logistique physique du retour — étiquette, transporteur, réception en entrepôt — n’est volontairement pas couverte ici.

Vue d’ensemble de l’architecture

L’entité centrale est un type de contenu personnalisé, demande_retour, distinct de la commande d’origine mais liée à elle par son identifiant. Ce choix évite de polluer le cycle de vie de la commande elle-même avec des statuts qui n’ont de sens que pour le retour, tout en gardant une traçabilité complète.

arborescence-fonctionnelle/
├── cpt/
│   └── demande_retour (type de contenu personnalisé)
│       ├── meta: _commande_origine_id
│       ├── meta: _articles_concernes (JSON)
│       ├── meta: _motif_retour
│       └── meta: _montant_rembourse
├── statuts/
│   ├── retour-demande      (client a soumis la demande)
│   ├── retour-approuve     (équipe support a validé)
│   ├── retour-recu         (entrepôt confirme réception)
│   └── retour-rembourse    (remboursement effectué)
├── portail-client/
│   └── endpoint "mes-retours" (woocommerce_account_menu_items)
└── notifications/
    ├── WC_Email_Demande_Retour_Recue
    ├── WC_Email_Retour_Approuve
    └── WC_Email_Remboursement_Effectue

Le cycle de statuts, colonne vertébrale du système

Chaque demande de retour traverse quatre statuts personnalisés, enregistrés comme des statuts de post classiques plutôt que comme des statuts de commande WooCommerce, ce qui évite toute confusion avec le cycle de vie de la commande d’origine, qui elle reste inchangée pendant toute la durée du traitement du retour.

Le déclenchement du remboursement

Une fois le retour marqué comme reçu par l’entrepôt, le passage au statut retour-rembourse déclenche l’appel à l’API native de remboursement de WooCommerce, wc_create_refund(), qui gère elle-même la synchronisation avec la passerelle de paiement d’origine lorsque celle-ci le permet, plutôt que de simuler un remboursement par un simple ajustement comptable.

add_action( 'transition_post_status', 'mr_declencher_remboursement', 10, 3 );

function mr_declencher_remboursement( $nouveau, $ancien, $post ) {
    if ( 'demande_retour' !== $post->post_type || 'retour-rembourse' !== $nouveau ) {
        return;
    }

    $commande_id = get_post_meta( $post->ID, '_commande_origine_id', true );
    $montant     = get_post_meta( $post->ID, '_montant_rembourse', true );

    wc_create_refund( array(
        'order_id' => $commande_id,
        'amount'   => $montant,
        'reason'   => 'Retour client validé, réf. ' . $post->ID,
    ) );
}

Le portail client

Côté client, un onglet « Mes retours » ajouté à l’espace compte liste les demandes en cours et leur statut, avec un bouton de soumission d’une nouvelle demande depuis l’historique de commandes. Le formulaire de soumission crée directement une entrée demande_retour au statut initial, sans passer par un échange d’e-mails préalable, ce qui structure dès le départ la donnée exploitée ensuite par le support.

• Historique de commandes enrichi d’un bouton « Demander un retour » sur les commandes éligibles
• Formulaire de motif et de photos jointes pour les articles défectueux
• Suivi de statut visible sans contact avec le support pour les cas simples

Le point d’articulation le plus délicat

Le calcul du montant remboursable, quand seule une partie des articles d’une commande est retournée, doit tenir compte de la répartition des frais de port et des éventuelles remises appliquées au niveau de la commande entière, pas seulement du prix unitaire de l’article. Ce calcul est isolé dans une fonction dédiée, testée indépendamment, plutôt que dispersé dans plusieurs points du code.

Un système de retours mal architecturé finit toujours par vivre dans la tête du support client, sous forme de règles non écrites. L’objectif d’une architecture dédiée est justement de sortir ces règles de leur tête pour les rendre visibles et cohérentes.

En résumé

Traiter les retours comme une entité à part entière, avec son propre cycle de statuts et son propre portail, plutôt que comme un ajustement manuel de commande, rend le processus auditable et scalable. Le remboursement s’appuie sur l’API native de WooCommerce, ce qui garantit une cohérence comptable que des manipulations manuelles répétées ne peuvent pas offrir sur la durée.