Never arm the reliable-purchase fallback from a render that already fired the purchase

The standard order-received render consumes the pending-purchase session
marker while emitting the purchase inline (wp_head), and woocommerce_thankyou
fires remember_order() later in the same request - re-seeding the marker and
re-arming the fallback for the very order the page just tracked. With "Do not
flag orders as being tracked" on (which disables every tracked-order
suppressor by design), the session endpoint then delivered the same purchase
a second time after page load.

remember_order() now bails when the request already pushed the purchase, and
on_thankyou() raises that request-scoped flag after a successful push so the
customized-page path is covered by the same guard. Also corrects the
handlePendingPurchase comment that claimed the browser guard stops a re-push
in the do-not-flag case - that branch skips the guard by design.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: duracelltomi

CHANGELOG.md

@@ -84,7 +84,7 @@ Major rewrite of the plugin - please read the announcement post on gtm4wp.com be
 
 #### Purchase tracking
 
-* Added: new "Reliable purchase tracking" option (WooCommerce → Purchase tracking) for the most common cause of a missing `purchase` event. When the customer lands on a heavily customized thank-you page, or on the order-pay page instead of the order received page, the purchase event is now emitted on the next page they view in the same browser session. The placed order is remembered server-side (on `woocommerce_payment_complete`, the order-status change and `woocommerce_thankyou`) and de-duplicated with the existing order-tracked flag, browser cookie and order-age guards, so it is never counted twice. Off by default (experimental). It cannot capture orders where the buyer pays via an asynchronous gateway and never returns to the site - that case needs server-side tracking.
+* Added: new "Reliable purchase tracking" option (WooCommerce → Purchase tracking) for the most common cause of a missing `purchase` event. When the customer lands on a heavily customized thank-you page, or on the order-pay page instead of the order received page, the purchase event is now emitted on the next page they view in the same browser session. The placed order is remembered server-side (on `woocommerce_payment_complete`, the order-status change and `woocommerce_thankyou`) and de-duplicated with the existing order-tracked flag, browser cookie and order-age guards, so it is never counted twice - and a page view that already carries the purchase event never arms the fallback in the first place, so the two cannot fire together on the same thank-you page even when the "Do not flag orders as being tracked" testing option has switched those guards off. Off by default (experimental). It cannot capture orders where the buyer pays via an asynchronous gateway and never returns to the site - that case needs server-side tracking.
 * Added: new "Order statuses that trigger the purchase event" setting. The purchase now fires at order *placement* for the configured statuses (default: Processing, On hold, Completed), so Cash on Delivery (Processing) and bank transfer (On hold) orders are tracked at checkout even though payment clears later. Filterable via the new `gtm4wp_purchase_trackable_statuses` filter.
 * Added: new "Custom order received (thank-you) page" option that fires the purchase event on a bespoke confirmation page - resolving the order from the current session - for themes or plugins that do not use the standard WooCommerce order received endpoint.
 * Added: GA4 / Google Ads Enhanced Conversions user data is now included on the `purchase` event - SHA-256 hashed email, phone and name plus the plaintext address components Google expects - built from the order so guest checkouts are covered too. The phone number is converted to E.164 against the order's billing country before hashing, as Google requires, and is left out entirely when it cannot be placed in E.164 with confidence rather than sent as a hash that could never match. Opt-in through the existing "Customer data in data layer" option.

js/frontend/gtm4wp-visitor-data.js

@@ -475,8 +475,10 @@ import {
 		// no state change, so this authenticated POST is what performs it. Only when the
 		// browser guard is in use (flag !== false); the "Do not flag orders as being
 		// tracked" case writes no order-tracked state anywhere, so it also sends no
-		// beacon — the server marker then lingers, but its only reader is this same
-		// resolver and the client's per-order guard already stops a re-push.
+		// beacon — the server marker then lingers with NO guard against a re-push
+		// (this branch skips the browser guard too). That is the option's contract:
+		// it asks for purchases to stay re-trackable, and the marker's only reader
+		// is this resolver, reached only while an event cookie is present.
 		if ( useGuard && confirmUrl ) {
 			fireConfirmBeacon( confirmUrl );
 		}

readme.txt

@@ -332,7 +332,7 @@ Major rewrite of the plugin. Please read the announcement post on gtm4wp.com bef
 
 **WooCommerce - Purchase tracking**
 
-* Added: new "Reliable purchase tracking" option (WooCommerce → Purchase tracking) for the most common cause of a missing `purchase` event. When the customer lands on a heavily customized thank-you page, or on the order-pay page instead of the order received page, the purchase event is now emitted on the next page they view in the same browser session. The placed order is remembered server-side (on `woocommerce_payment_complete`, the order-status change and `woocommerce_thankyou`) and de-duplicated with the existing order-tracked flag, browser cookie and order-age guards, so it is never counted twice. Off by default (experimental). It cannot capture orders where the buyer pays via an asynchronous gateway and never returns to the site - that case needs server-side tracking.
+* Added: new "Reliable purchase tracking" option (WooCommerce → Purchase tracking) for the most common cause of a missing `purchase` event. When the customer lands on a heavily customized thank-you page, or on the order-pay page instead of the order received page, the purchase event is now emitted on the next page they view in the same browser session. The placed order is remembered server-side (on `woocommerce_payment_complete`, the order-status change and `woocommerce_thankyou`) and de-duplicated with the existing order-tracked flag, browser cookie and order-age guards, so it is never counted twice - and a page view that already carries the purchase event never arms the fallback in the first place, so the two cannot fire together on the same thank-you page even when the "Do not flag orders as being tracked" testing option has switched those guards off. Off by default (experimental). It cannot capture orders where the buyer pays via an asynchronous gateway and never returns to the site - that case needs server-side tracking.
 * Added: new "Order statuses that trigger the purchase event" setting. The purchase now fires at order *placement* for the configured statuses (default: Processing, On hold, Completed), so Cash on Delivery (Processing) and bank transfer (On hold) orders are tracked at checkout even though payment clears later. Filterable via the new `gtm4wp_purchase_trackable_statuses` filter.
 * Added: new "Custom order received (thank-you) page" option that fires the purchase event on a bespoke confirmation page - resolving the order from the current session - for themes or plugins that do not use the standard WooCommerce order received endpoint.
 * Added: GA4 / Google Ads Enhanced Conversions user data is now included on the `purchase` event - SHA-256 hashed email, phone and name plus the plaintext address components Google expects - built from the order so guest checkouts are covered too. The phone number is converted to E.164 against the order's billing country before hashing, as Google requires, and is left out entirely when it cannot be placed in E.164 with confidence rather than sent as a hash that could never match. Opt-in through the existing "Customer data in data layer" option.

src/Modules/WooCommerce/PurchaseTracking.php

@@ -133,6 +133,13 @@ public function on_thankyou( $order_id ): void {
 			$this->script_tag->print_script_block( $script_tag );
 
 			$this->product_data->flag_order_tracked( $order );
+
+			// Mark the purchase as handled for THIS request, exactly like the
+			// order-received page path does. remember_order() runs on this same
+			// woocommerce_thankyou hook right after this callback, and without the
+			// flag it would re-arm the reliable-purchase fallback for the very
+			// order whose purchase this page already carries.
+			$GLOBALS['gtm4wp_woocommerce_purchase_data_pushed'] = true;
 		}
 	}
 
@@ -151,6 +158,22 @@ public function on_thankyou( $order_id ): void {
 	 * @return void
 	 */
 	public function remember_order( $order_id ): void {
+		/*
+		The render that emits the purchase inline sets this flag (the standard
+		order-received page in PageDataLayer::add_order_received_data(), the
+		on_thankyou fallback above, and the any-page session fallback). Seeding
+		the marker from such a request would re-arm the reliable-purchase
+		fallback for an order whose purchase this very page already carries:
+		the standard order-received render consumes the marker in wp_head and
+		this hook fires later in the template body, so without this guard the
+		session endpoint delivered the same purchase a second time after page
+		load whenever nothing else suppressed it ("Do not flag orders as being
+		tracked" disables every one of those suppressors by design).
+		*/
+		if ( ! empty( $GLOBALS['gtm4wp_woocommerce_purchase_data_pushed'] ) ) {
+			return;
+		}
+
 		$order_id = absint( $order_id );
 		if ( $order_id <= 0 ) {
 			return;

tests/unit/Modules/PurchaseTrackingTest.php

@@ -395,6 +395,64 @@ public function test_remember_order_seeds_a_trackable_order_into_the_session():
 		$this->assertSame( 1001, $session->sets[ ProductData::PENDING_PURCHASE_SESSION_KEY ] ?? null, 'A placed, trackable order must be remembered for the next-page fallback.' );
 	}
 
+	/**
+	 * Double-purchase regression: the standard order-received render consumes the
+	 * pending-purchase marker while emitting the purchase inline (wp_head), and
+	 * woocommerce_thankyou fires remember_order() later in the same request (the
+	 * template body). Re-seeding there re-armed the reliable-purchase fallback for
+	 * the very order the page already tracked, and the session endpoint then
+	 * delivered the same purchase a second time after page load whenever the
+	 * "Do not flag orders as being tracked" option had disabled the tracked-order
+	 * suppressors. A request that already pushed the purchase must never seed.
+	 */
+	public function test_remember_order_skips_when_the_purchase_was_already_pushed_this_request(): void {
+		$GLOBALS['gtm4wp_woocommerce_purchase_data_pushed'] = true;
+
+		$session = $this->stub_wc_with_session();
+		Functions\when( 'wc_get_order' )->justReturn( $this->make_order() );
+
+		$this->make_tracking()->remember_order( 1001 );
+
+		$this->assertArrayNotHasKey( ProductData::PENDING_PURCHASE_SESSION_KEY, $session->sets, 'A request that already emitted the purchase inline must not re-arm the reliable-purchase fallback.' );
+	}
+
+	/**
+	 * The customized-page half of the same regression: on_thankyou() pushes the
+	 * purchase inline, and remember_order() runs on the SAME woocommerce_thankyou
+	 * hook right after it. The push must raise the request-scoped flag so the
+	 * sequence cannot seed the fallback for the order it just tracked.
+	 */
+	public function test_on_thankyou_then_remember_order_does_not_seed_the_fallback(): void {
+		$session = $this->stub_wc_with_session();
+		$order   = $this->make_order();
+		Functions\when( 'wc_get_order' )->justReturn( $order );
+
+		$tracking = $this->make_tracking( array( GTM4WP_OPTION_INTEGRATE_WCTRACKECOMMERCE => true ) );
+
+		ob_start();
+		$tracking->on_thankyou( 1001 );
+		$output = (string) ob_get_clean();
+
+		$this->assertStringContainsString( '"event":"purchase"', $output, 'Precondition: the thank-you fallback must have pushed the purchase.' );
+
+		$tracking->remember_order( 1001 );
+
+		$this->assertArrayNotHasKey( ProductData::PENDING_PURCHASE_SESSION_KEY, $session->sets, 'The thank-you render that pushed the purchase must not re-arm the fallback on the same hook.' );
+	}
+
+	/**
+	 * The negative branch: when on_thankyou() bails without pushing (here: the
+	 * eligibility gauntlet rejects an already-tracked order), the flag must stay
+	 * down so the checkout-time seed hooks keep working unchanged.
+	 */
+	public function test_on_thankyou_leaves_the_flag_down_when_nothing_was_pushed(): void {
+		$order = $this->make_order( array( 'meta' => array( '_ga_tracked' => 1 ) ) );
+
+		$this->run_thankyou( array( GTM4WP_OPTION_INTEGRATE_WCTRACKECOMMERCE => true ), $order );
+
+		$this->assertArrayNotHasKey( 'gtm4wp_woocommerce_purchase_data_pushed', $GLOBALS, 'A bailed thank-you fallback must not claim the purchase was pushed.' );
+	}
+
 	public function test_remember_order_skips_a_non_trackable_status(): void {
 		$session = $this->stub_wc_with_session();
 		Functions\when( 'wc_get_order' )->justReturn( $this->make_order( array( 'status' => 'pending' ) ) );