Prevent duplicate failed order emails (#3418)

* Prevent duplicate failed order emails

When an order changes status from pending/on-hold to failed,
a failed-order email is triggered by core. In our webhooks code,
we also manually trigger these emails when certain Stripe processes
fail. This causes duplicate emails for some scenarios.

* Add changelog and readme entries
---------

Co-authored-by: Wesley Rosa <[email protected]>

Author: annemirasol

changelog.txt

@@ -1,6 +1,7 @@
 *** Changelog ***
 
 = 8.7.0 - xxxx-xx-xx =
+* Fix - Prevent duplicate failed-order emails from being sent.
 * Fix - Support custom name and description for Afterpay.
 * Fix - Link APM charge IDs in Order Details page to their Stripe dashboard payments page.
 * Fix - Fix Indian subscription processing by forcing the recreation of mandates during switches (upgrading/downgrading).

includes/abstracts/abstract-wc-stripe-payment-gateway.php

@@ -622,13 +622,32 @@ public function process_response( $response, $order ) {
 	 * @since 3.1.0
 	 * @version 4.0.0
 	 * @param int $order_id
-	 * @return null
+	 * @param array $status_update Optional. Use fields 'to' and 'from' to provide context
+	 *    when a status change has occurred for the order.
+	 * @return void
 	 */
-	public function send_failed_order_email( $order_id ) {
+	public function send_failed_order_email( $order_id, $status_update = [] ) {
 		$emails = WC()->mailer()->get_emails();
-		if ( ! empty( $emails ) && ! empty( $order_id ) && isset( $emails['WC_Email_Failed_Order'] ) ) {
-			$emails['WC_Email_Failed_Order']->trigger( $order_id );
+
+		if ( empty( $emails ) || empty( $order_id ) || ! isset( $emails['WC_Email_Failed_Order'] ) ) {
+			return;
+		}
+
+		// To prevent duplicate failed order emails, check if a status update
+		// will trigger its own failed order email.
+		if (
+			isset( $status_update['to'], $status_update['from'] ) &&
+			'failed' === $status_update['to'] &&
+			in_array( $status_update['from'], [ 'on-hold', 'pending' ], true )
+		) {
+			$callback  = [ $emails['WC_Email_Failed_Order'], 'trigger' ];
+			$hook_name = "woocommerce_order_status_{$status_update['from']}_to_failed_notification";
+			if ( has_action( $hook_name, $callback ) ) {
+				return;
+			}
 		}
+
+		$emails['WC_Email_Failed_Order']->trigger( $order_id );
 	}
 
 	/**

includes/class-wc-stripe-webhook-handler.php

@@ -966,15 +966,18 @@ public function process_payment_intent_success( $notification ) {
 				/* translators: 1) The error message that was received from Stripe. */
 				$message = sprintf( __( 'Stripe SCA authentication failed. Reason: %s', 'woocommerce-gateway-stripe' ), $error_message );
 
+				$status_update = [];
 				if ( ! $order->get_meta( '_stripe_status_final', false ) ) {
+					$status_update['from'] = $order->get_status();
+					$status_update['to']   = 'failed';
 					$order->update_status( 'failed', $message );
 				} else {
 					$order->add_order_note( $message );
 				}
 
 				do_action( 'wc_gateway_stripe_process_webhook_payment_error', $order, $notification );
 
-				$this->send_failed_order_email( $order_id );
+				$this->send_failed_order_email( $order_id, $status_update );
 				break;
 		}
 
@@ -1017,13 +1020,16 @@ public function process_setup_intent( $notification ) {
 			/* translators: 1) The error message that was received from Stripe. */
 			$message = sprintf( __( 'Stripe SCA authentication failed. Reason: %s', 'woocommerce-gateway-stripe' ), $error_message );
 
+			$status_update = [];
 			if ( ! $order->get_meta( '_stripe_status_final', false ) ) {
+				$status_update['from'] = $order->get_status();
+				$status_update['to']   = 'failed';
 				$order->update_status( 'failed', $message );
 			} else {
 				$order->add_order_note( $message );
 			}
 
-			$this->send_failed_order_email( $order_id );
+			$this->send_failed_order_email( $order_id, $status_update );
 		}
 
 		$this->unlock_order_payment( $order );

readme.txt

@@ -129,6 +129,7 @@ If you get stuck, you can ask for help in the Plugin Forum.
 == Changelog ==
 
 = 8.7.0 - xxxx-xx-xx =
+* Fix - Prevent duplicate failed-order emails from being sent.
 * Fix - Support custom name and description for Afterpay.
 * Fix - Link APM charge IDs in Order Details page to their Stripe dashboard payments page.
 * Fix - Fix Indian subscription processing by forcing the recreation of mandates during switches (upgrading/downgrading).