Commit 94fcb2bb2a3 for woocommerce

commit 94fcb2bb2a33809430652a6b6e42fc434db92a11
Author: Taha Paksu <3295+tpaksu@users.noreply.github.com>
Date:   Thu Nov 19 00:29:19 2026 +0300

    Let stores skip the completed order email for fulfilled orders (#71022)

    * [WOOPLUG-7975] Let stores skip the completed order email for fulfilled orders

    * Add changefile(s) from automation for the following project(s): woocommerce

    * [WOOPLUG-7975] Read the stored fulfillment status in the completed order email check

    * [WOOPLUG-7975] Calculate the fulfillment status and skip only the automatic send

    * [WOOPLUG-7975] Re-read the order in the documented suppression callback

    ---------

    Co-authored-by: woocommercebot <woocommercebot@users.noreply.github.com>

diff --git a/docs/features/fulfillments/hooks.md b/docs/features/fulfillments/hooks.md
index 3fd85e7955a..4f6f5e69cb1 100644
--- a/docs/features/fulfillments/hooks.md
+++ b/docs/features/fulfillments/hooks.md
@@ -133,6 +133,37 @@ The fulfillment email templates expose the standard extension points below.
 | `woocommerce_email_fulfillment_items_args` | Template arguments array | Customize how fulfillment line items are rendered in the email templates. |
 | `woocommerce_get_email_fulfillment_items_table` | `string $html`, `WC_Order $order`, `Fulfillment $fulfillment` | Filter and return the rendered fulfillment items table HTML. |

+## Completed order email
+
+An order that ships in parts sends one fulfillment email per shipment, and WooCommerce still sends the order-level "Completed order" email when the order is marked complete. Both are kept on purpose: a fulfillment email covers a single shipment, the "Completed order" email covers the order as a whole. A store that would rather send only the fulfillment emails can opt out of the order-level one.
+
+| Hook | Parameters | Purpose |
+| --- | --- | --- |
+| `woocommerce_fulfillment_suppress_completed_order_email` | `bool $suppress`, `WC_Order $order` | Return true to skip the "Completed order" email for an order whose fulfillment status is `fulfilled`. Defaults to false, which sends both emails. |
+
+Only `true` skips the email, and only a fully fulfilled order is affected: a partially fulfilled order, or one with no fulfillments, still receives it. Only the email that follows the order being marked complete is skipped, so sending the "Completed order" email again, through the REST API or the `woocommerce/order-send-email` ability, still reaches the customer.
+
+The callback owns the decision of whether an order can do without its "Completed order" email, and it receives the order so it can decide per order rather than store-wide. That order is the instance the email carries, which can predate the order's last edit and hold an out-of-date fulfillment status, so a callback that depends on either should re-read the order with `wc_get_order( $order->get_id() )`. The example below skips the email for shipped orders and keeps it whenever the order holds a downloadable item, which is part of the check the email itself uses to decide whether to show download links:
+
+```php
+add_filter(
+    'woocommerce_fulfillment_suppress_completed_order_email',
+    function ( $suppress, $order ) {
+        // Read again, because the instance the email carries can predate the order's last edit.
+        $order = wc_get_order( $order->get_id() );
+
+        return $order && ! $order->has_downloadable_item();
+    },
+    10,
+    2
+);
+```
+
+Two things are worth checking before opting out of the email for every order:
+
+- **A fulfilled order has not necessarily emailed the customer.** Auto-fulfilled items (**Settings > Products > Auto-fulfill items**, on by default for downloadable products), fulfillments saved with the **Fulfillment notification** toggle off, the **Mark as fulfilled** bulk action on the orders list, and imported fulfillments all reach the `fulfilled` status without sending a fulfillment email. An order of downloadable products that goes straight from pending to completed can therefore end up with no email at all: whether its "Completed order" email goes out before or after its items are auto-fulfilled depends on whether the store defers transactional emails.
+- **The "Completed order" email is not always the only one carrying the order totals and the download links.** The "Processing order" email carries them as well, because access to downloads is granted after payment by default, so an order that passes through "Processing" has already sent both. An order that skips it has them in the "Completed order" email alone.
+
 ## Privacy filters

 When an order is anonymized, through the WordPress personal-data eraser or the automatic retention cleanup, WooCommerce clears the personal data stored on its fulfillments. This also runs on a store where the fulfillments feature has since been disabled, as long as its tables were created while it was on, since any tracking data they hold is still stored.
diff --git a/plugins/woocommerce/changelog/71022-wooplug-7975-suppress-completed-order-email b/plugins/woocommerce/changelog/71022-wooplug-7975-suppress-completed-order-email
new file mode 100644
index 00000000000..45c0a90e1b2
--- /dev/null
+++ b/plugins/woocommerce/changelog/71022-wooplug-7975-suppress-completed-order-email
@@ -0,0 +1,4 @@
+Significance: patch
+Type: add
+
+Add a filter that lets a store skip the Completed order email for orders that are fully fulfilled.
diff --git a/plugins/woocommerce/src/Admin/Features/Fulfillments/FulfillmentsManager.php b/plugins/woocommerce/src/Admin/Features/Fulfillments/FulfillmentsManager.php
index f68ae845917..58cd25274d1 100644
--- a/plugins/woocommerce/src/Admin/Features/Fulfillments/FulfillmentsManager.php
+++ b/plugins/woocommerce/src/Admin/Features/Fulfillments/FulfillmentsManager.php
@@ -41,6 +41,7 @@ class FulfillmentsManager {
 		$this->init_fulfillment_status_hooks();
 		$this->init_refund_hooks();
 		$this->init_email_template_tracking_hooks();
+		$this->init_completed_order_email_hooks();
 		$this->init_order_deletion_hooks();

 		if ( ! $this->fulfillment_order_notes ) {
@@ -95,6 +96,83 @@ class FulfillmentsManager {
 		}
 	}

+	/**
+	 * Hook the "Completed order" email so a store can opt out of it for fully fulfilled orders.
+	 *
+	 * @since 11.4.0
+	 */
+	private function init_completed_order_email_hooks(): void {
+		add_filter( 'woocommerce_email_enabled_customer_completed_order', array( $this, 'maybe_suppress_completed_order_email' ), 10, 2 );
+	}
+
+	/**
+	 * Skip the "Completed order" email for an order whose items have all been fulfilled.
+	 *
+	 * Opt-in only: the email is left as it is unless a store returns true from
+	 * `woocommerce_fulfillment_suppress_completed_order_email`.
+	 *
+	 * @internal For exclusive usage within this class, backwards compatibility not guaranteed.
+	 *
+	 * @since 11.4.0
+	 *
+	 * @param bool  $enabled Whether the email is enabled.
+	 * @param mixed $order   The order the email is about, when the email has one.
+	 * @return bool Whether the email is enabled.
+	 */
+	public function maybe_suppress_completed_order_email( $enabled, $order ): bool {
+		if ( ! $enabled || ! $order instanceof WC_Order ) {
+			return (bool) $enabled;
+		}
+
+		// Only the send that follows the order being completed, so that a resend still reaches the
+		// customer. The second action is the one deferred emails are sent on.
+		if ( ! doing_action( 'woocommerce_order_status_completed' ) && ! doing_action( 'woocommerce_send_queued_transactional_email' ) ) {
+			return (bool) $enabled;
+		}
+
+		/**
+		 * Filters whether the "Completed order" email is skipped for fully fulfilled orders.
+		 *
+		 * Returns false by default, which sends both emails, and only true skips the email. A
+		 * callback decides whether the order can do without the order-level email: reaching the
+		 * `fulfilled` status does not prove the customer was emailed, and an order that skips the
+		 * "Processing" status carries its totals and download links in this email alone.
+		 *
+		 * @since 11.4.0
+		 *
+		 * @param bool     $suppress Whether to skip the email for fully fulfilled orders.
+		 * @param WC_Order $order    The order the email is about.
+		 */
+		if ( true !== apply_filters( 'woocommerce_fulfillment_suppress_completed_order_email', false, $order ) ) {
+			return (bool) $enabled;
+		}
+
+		// The stored status can be out of date: the email can carry an instance read before the last
+		// fulfillment was saved, and it is not recalculated when the order's items change.
+		$stored_order = wc_get_order( $order->get_id() );
+		if ( ! $stored_order instanceof WC_Order ) {
+			return (bool) $enabled;
+		}
+
+		try {
+			/**
+			 * Fulfillments data store.
+			 *
+			 * @var \Automattic\WooCommerce\Admin\Features\Fulfillments\DataStore\FulfillmentsDataStore $fulfillments_data_store
+			 */
+			$fulfillments_data_store = \WC_Data_Store::load( 'order-fulfillment' );
+			$fulfillments            = $fulfillments_data_store->read_fulfillments( \WC_Order::class, (string) $stored_order->get_id() );
+		} catch ( \Throwable $e ) {
+			wc_get_logger()->error(
+				sprintf( 'Failed to load fulfillments for order %d: %s', $stored_order->get_id(), $e->getMessage() ),
+				array( 'source' => 'fulfillments' )
+			);
+			return (bool) $enabled;
+		}
+
+		return 'fulfilled' !== FulfillmentUtils::calculate_order_fulfillment_status( $stored_order, $fulfillments );
+	}
+
 	/**
 	 * Initialize order deletion hooks.
 	 *
diff --git a/plugins/woocommerce/tests/php/src/Admin/Features/Fulfillments/FulfillmentsManagerTest.php b/plugins/woocommerce/tests/php/src/Admin/Features/Fulfillments/FulfillmentsManagerTest.php
index 0475b150f12..3c0bea9c3d0 100644
--- a/plugins/woocommerce/tests/php/src/Admin/Features/Fulfillments/FulfillmentsManagerTest.php
+++ b/plugins/woocommerce/tests/php/src/Admin/Features/Fulfillments/FulfillmentsManagerTest.php
@@ -2,7 +2,10 @@

 namespace Automattic\WooCommerce\Tests\Admin\Features\Fulfillments;

+use Automattic\WooCommerce\Admin\Features\Fulfillments\Fulfillment;
 use Automattic\WooCommerce\Admin\Features\Fulfillments\FulfillmentsManager;
+use Automattic\WooCommerce\Admin\Features\Fulfillments\FulfillmentUtils;
+use Automattic\WooCommerce\Enums\OrderStatus;
 use Automattic\WooCommerce\RestApi\UnitTests\Helpers\OrderHelper;
 use Automattic\WooCommerce\Tests\Admin\Features\Fulfillments\Helpers\FulfillmentsHelper;
 use Automattic\WooCommerce\Testing\Tools\TestingContainer;
@@ -405,4 +408,385 @@ class FulfillmentsManagerTest extends \WC_Unit_Test_Case {
 			);
 		}
 	}
+
+	/**
+	 * @testdox The "Completed order" email check is hooked when fulfillments are active.
+	 */
+	public function test_completed_order_email_hook_is_registered(): void {
+		$this->assertNotFalse(
+			has_filter( 'woocommerce_email_enabled_customer_completed_order', array( $this->manager, 'maybe_suppress_completed_order_email' ) ),
+			'The "Completed order" email check should be hooked.'
+		);
+	}
+
+	/**
+	 * @testdox The "Completed order" email still sends for a fulfilled order when nothing opts out of it.
+	 */
+	public function test_completed_order_email_sends_for_fulfilled_order_by_default(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+
+		$this->assertSame( 'fulfilled', $order->get_meta( '_fulfillment_status', true ), 'The order should be fully fulfilled.' );
+		$this->assertTrue( $this->complete_order_and_email_sent( $order ), 'Both emails should send unless a store opts out.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email is skipped for a fulfilled order when a store opts out of it.
+	 */
+	public function test_completed_order_email_is_skipped_for_fulfilled_order_when_opted_out(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertFalse( $this->complete_order_and_email_sent( $order ), 'A fully fulfilled order should skip the email.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email still sends for a partially fulfilled order when a store opts out of it.
+	 */
+	public function test_completed_order_email_sends_for_partially_fulfilled_order_when_opted_out(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 1 );
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertSame( 'partially_fulfilled', $order->get_meta( '_fulfillment_status', true ), 'The order should be partially fulfilled.' );
+		$this->assertTrue( $this->complete_order_and_email_sent( $order ), 'An order with items left to ship should keep the email.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email still sends for an order without fulfillments when a store opts out of it.
+	 */
+	public function test_completed_order_email_sends_without_fulfillments_when_opted_out(): void {
+		$order = OrderHelper::create_order( get_current_user_id(), \WC_Helper_Product::create_simple_product() );
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertTrue( $this->complete_order_and_email_sent( $order ), 'An order with no fulfillments should keep the email.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email still sends for an order whose fulfillments are all unfulfilled.
+	 */
+	public function test_completed_order_email_sends_for_unfulfilled_order_when_opted_out(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4, false );
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertSame( 'unfulfilled', $order->get_meta( '_fulfillment_status', true ), 'The order should be unfulfilled.' );
+		$this->assertTrue( $this->complete_order_and_email_sent( $order ), 'An order whose shipments have not gone out should keep the email.' );
+	}
+
+	/**
+	 * @testdox Opting out never turns the "Completed order" email back on when the merchant disabled it.
+	 */
+	public function test_completed_order_email_stays_off_when_the_merchant_disabled_it(): void {
+		// Partially fulfilled, so the email would be reported as enabled again if the merchant's
+		// setting were not checked first.
+		$order = $this->create_order_with_fulfilled_quantity( 1 );
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertFalse( $this->complete_order_and_email_sent( $order, 'no' ), 'A disabled email should stay disabled.' );
+	}
+
+	/**
+	 * @testdox Only true opts out of the "Completed order" email, so a callback returning something else still sends it.
+	 */
+	public function test_completed_order_email_sends_when_the_filter_returns_a_truthy_value(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+		add_filter( 'woocommerce_fulfillment_suppress_completed_order_email', fn() => 'no' );
+
+		$this->assertTrue( $this->complete_order_and_email_sent( $order ), 'Only true should skip the email.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email still sends when an item was added after the order was fulfilled.
+	 */
+	public function test_completed_order_email_sends_when_an_item_was_added_after_the_order_was_fulfilled(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+		$this->opt_out_of_the_completed_order_email();
+
+		$order->add_product( \WC_Helper_Product::create_simple_product(), 1 );
+		$order->save();
+
+		$this->assertSame( 'fulfilled', $order->get_meta( '_fulfillment_status', true ), 'The stored status should still say fulfilled, which is what makes this worth checking.' );
+		$this->assertTrue( $this->complete_order_and_email_sent( $order ), 'An order holding an item that was never fulfilled should keep the email.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email still sends when another request added an item to the fulfilled order.
+	 */
+	public function test_completed_order_email_sends_when_another_request_added_an_item(): void {
+		$order      = $this->create_order_with_fulfilled_quantity( 4 );
+		$held_order = new WC_Order( $order->get_id() );
+
+		// Order items are read on first use, so this is what makes the held instance keep its own
+		// copy of them, as any caller that looked at the order before completing it would.
+		$this->assertCount( 1, $held_order->get_items(), 'The held instance starts with the order as it was.' );
+
+		// As a REST request editing the order would: an item that no fulfillment covers is added
+		// through another instance, after the one completing the order had read its items.
+		$edited_order = new WC_Order( $order->get_id() );
+		$edited_order->add_product( \WC_Helper_Product::create_simple_product(), 1 );
+		$edited_order->save();
+
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertCount( 2, wc_get_order( $order->get_id() )->get_items(), 'The stored order should hold the added item.' );
+		$this->assertTrue( $this->complete_order_and_email_sent( $held_order ), 'An order holding an item that was added elsewhere should keep the email.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email still sends when the order's fulfillments cannot be read.
+	 */
+	public function test_completed_order_email_sends_when_the_fulfillments_cannot_be_read(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+		$this->opt_out_of_the_completed_order_email();
+
+		// Named rather than removed, because an unknown data store silently falls back to the one
+		// for orders instead of failing.
+		add_filter(
+			'woocommerce_data_stores',
+			function ( $stores ) {
+				$stores['order-fulfillment'] = 'A_Fulfillments_Data_Store_That_Is_Not_Installed';
+				return $stores;
+			}
+		);
+
+		$this->assertTrue( $this->complete_order_and_email_sent( $order ), 'A fulfillment status that cannot be read should not cost the customer the email.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email is skipped for a fulfilled order when the caller completes an instance read before the fulfillment.
+	 */
+	public function test_completed_order_email_is_skipped_for_an_order_read_before_the_fulfillment(): void {
+		$order = OrderHelper::create_order( get_current_user_id(), \WC_Helper_Product::create_simple_product() );
+
+		// Stands for the instance a caller holds while it saves the last fulfillment and then
+		// completes the order. It is constructed directly so the order cache cannot refresh it.
+		$held_order = new WC_Order( $order->get_id() );
+
+		$this->fulfill_quantity( $order, 4 );
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertSame( 'no_fulfillments', FulfillmentUtils::get_order_fulfillment_status( $held_order ), 'The held instance should still carry the status it was read with.' );
+		$this->assertFalse( $this->complete_order_and_email_sent( $held_order ), 'A fully fulfilled order should skip the email even when the caller holds an older instance.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email still sends when the caller completes an instance read before the fulfillment was deleted.
+	 */
+	public function test_completed_order_email_sends_for_an_order_read_before_the_fulfillment_was_deleted(): void {
+		$order       = OrderHelper::create_order( get_current_user_id(), \WC_Helper_Product::create_simple_product() );
+		$fulfillment = $this->fulfill_quantity( $order, 4 );
+
+		// Read while the order was fulfilled, so the instance keeps a status the merchant has since
+		// undone. It is constructed directly so the order cache cannot refresh it.
+		$held_order = new WC_Order( $order->get_id() );
+
+		$fulfillment->delete();
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertSame( 'fulfilled', FulfillmentUtils::get_order_fulfillment_status( $held_order ), 'The held instance should still carry the status it was read with.' );
+		$this->assertTrue( $this->complete_order_and_email_sent( $held_order ), 'An order whose fulfillment was deleted should keep its email.' );
+	}
+
+	/**
+	 * @testdox Sending the "Completed order" email again for a fulfilled order still reaches the customer.
+	 */
+	public function test_completed_order_email_sends_on_a_resend_of_a_fulfilled_order(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertTrue( $this->resend_completed_order_email( $order ), 'A resend should reach the customer, so that the store is not told about a send that never happened.' );
+	}
+
+	/**
+	 * @testdox Opting out leaves the "Completed order" email alone when the email has no order, as on the settings screen.
+	 */
+	public function test_completed_order_email_is_untouched_without_an_order(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+		$this->opt_out_of_the_completed_order_email();
+
+		// Asked while the order is being completed, so that the check runs rather than bailing out
+		// because no email is being sent.
+		$enabled = null;
+		$probe   = function () use ( &$enabled ) {
+			$enabled = $this->manager->maybe_suppress_completed_order_email( true, null );
+		};
+		add_action( 'woocommerce_order_status_completed', $probe );
+		try {
+			$order->update_status( OrderStatus::COMPLETED );
+		} finally {
+			remove_action( 'woocommerce_order_status_completed', $probe );
+		}
+
+		$this->assertTrue( $enabled, 'Without an order the email setting should be reported as it is.' );
+	}
+
+	/**
+	 * @testdox The order is passed to the suppression filter so a callback can decide per order.
+	 */
+	public function test_suppression_filter_receives_the_order(): void {
+		$order           = $this->create_order_with_fulfilled_quantity( 4 );
+		$received_orders = array();
+
+		add_filter(
+			'woocommerce_fulfillment_suppress_completed_order_email',
+			function ( $suppress, $filtered_order ) use ( &$received_orders ) {
+				$received_orders[] = $filtered_order;
+				return $suppress;
+			},
+			10,
+			2
+		);
+
+		$this->complete_order_and_email_sent( $order );
+
+		$this->assertNotEmpty( $received_orders, 'The filter should run for the email.' );
+		$this->assertSame( $order, $received_orders[0], 'The filter should receive the instance the email carries.' );
+	}
+
+	/**
+	 * @testdox A deferred "Completed order" email still sends for a fulfilled order when nothing opts out of it.
+	 */
+	public function test_deferred_completed_order_email_sends_for_fulfilled_order_by_default(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+
+		$this->assertTrue( $this->send_queued_completed_order_email( $order ), 'A deferred email should send unless a store opts out.' );
+	}
+
+	/**
+	 * @testdox The "Completed order" email is skipped for a fulfilled order when it is sent from the deferred email queue.
+	 */
+	public function test_deferred_completed_order_email_is_skipped_for_fulfilled_order_when_opted_out(): void {
+		$order = $this->create_order_with_fulfilled_quantity( 4 );
+		$this->opt_out_of_the_completed_order_email();
+
+		$this->assertFalse( $this->send_queued_completed_order_email( $order ), 'A store that defers its emails should skip this one too.' );
+	}
+
+	/**
+	 * Opt the store out of the "Completed order" email for fully fulfilled orders.
+	 */
+	private function opt_out_of_the_completed_order_email(): void {
+		add_filter( 'woocommerce_fulfillment_suppress_completed_order_email', '__return_true' );
+	}
+
+	/**
+	 * Mark the order complete and report whether the "Completed order" email went out.
+	 *
+	 * @param WC_Order $order   The order to complete.
+	 * @param string   $setting The merchant's enabled setting for the email.
+	 * @return bool Whether the email was sent.
+	 */
+	private function complete_order_and_email_sent( WC_Order $order, string $setting = 'yes' ): bool {
+		// Pinned off so the email is sent in this request instead of being queued for later.
+		add_filter( 'woocommerce_defer_transactional_emails', '__return_false' );
+
+		return $this->completed_order_email_sent(
+			function () use ( $order ) {
+				$order->update_status( OrderStatus::COMPLETED );
+			},
+			$setting
+		);
+	}
+
+	/**
+	 * Send the "Completed order" email again for an order, as the REST order action and the
+	 * order-send-email ability both do, and report whether it went out.
+	 *
+	 * @param WC_Order $order The order to send the email for.
+	 * @return bool Whether the email was sent.
+	 */
+	private function resend_completed_order_email( WC_Order $order ): bool {
+		return $this->completed_order_email_sent(
+			function () use ( $order ) {
+				do_action( 'woocommerce_order_status_completed_notification', $order->get_id(), $order );
+			}
+		);
+	}
+
+	/**
+	 * Send the order's "Completed order" email the way the deferred email queue does, and report
+	 * whether it went out.
+	 *
+	 * @param WC_Order $order The order to send the email for.
+	 * @return bool Whether the email was sent.
+	 */
+	private function send_queued_completed_order_email( WC_Order $order ): bool {
+		return $this->completed_order_email_sent(
+			function () use ( $order ) {
+				do_action( 'woocommerce_send_queued_transactional_email', 'woocommerce_order_status_completed', array( $order->get_id(), $order ), '' );
+			}
+		);
+	}
+
+	/**
+	 * Run the given dispatch and report whether the "Completed order" email went out.
+	 *
+	 * @param callable $dispatch The call that should send the email.
+	 * @param string   $setting  The merchant's enabled setting for the email.
+	 * @return bool Whether the email was sent.
+	 */
+	private function completed_order_email_sent( callable $dispatch, string $setting = 'yes' ): bool {
+		// Hook-driven emails are off in tests, so nothing would be sent here whatever the
+		// suppression decides.
+		$this->enable_transactional_emails();
+
+		$email          = WC()->mailer()->get_emails()['WC_Email_Customer_Completed_Order'];
+		$email->enabled = $setting;
+
+		$sent    = false;
+		$capture = function ( $result, $email_id ) use ( &$sent ) {
+			if ( 'customer_completed_order' === $email_id ) {
+				$sent = (bool) $result;
+			}
+		};
+		add_action( 'woocommerce_email_sent', $capture, 10, 2 );
+
+		try {
+			$dispatch();
+		} finally {
+			remove_action( 'woocommerce_email_sent', $capture, 10 );
+		}
+
+		return $sent;
+	}
+
+	/**
+	 * Create an order of four units and fulfill the given quantity of them.
+	 *
+	 * @param int  $quantity Quantity to put in the fulfillment.
+	 * @param bool $fulfilled Whether the fulfillment itself has shipped.
+	 * @return WC_Order The order, re-read so it carries the recalculated fulfillment status.
+	 */
+	private function create_order_with_fulfilled_quantity( int $quantity, bool $fulfilled = true ): WC_Order {
+		$order = OrderHelper::create_order( get_current_user_id(), \WC_Helper_Product::create_simple_product() );
+		$this->fulfill_quantity( $order, $quantity, $fulfilled );
+
+		return wc_get_order( $order->get_id() );
+	}
+
+	/**
+	 * Create a fulfillment holding the given quantity of each item in the order.
+	 *
+	 * @param WC_Order $order     The order to fulfill.
+	 * @param int      $quantity  Quantity to put in the fulfillment.
+	 * @param bool     $fulfilled Whether the fulfillment itself has shipped.
+	 * @return Fulfillment The fulfillment that was created.
+	 */
+	private function fulfill_quantity( WC_Order $order, int $quantity, bool $fulfilled = true ): Fulfillment {
+		$items = array();
+		foreach ( $order->get_items() as $item_id => $item ) {
+			$items[] = array(
+				'item_id' => $item_id,
+				'qty'     => $quantity,
+			);
+		}
+
+		return FulfillmentsHelper::create_fulfillment(
+			array(
+				'entity_type'  => WC_Order::class,
+				'entity_id'    => $order->get_id(),
+				'status'       => $fulfilled ? 'fulfilled' : 'unfulfilled',
+				'is_fulfilled' => $fulfilled,
+			),
+			array( '_items' => $items )
+		);
+	}
 }