Commit d9acff65908 for woocommerce

commit d9acff6590865abcb9daa156c11cf058588bce9c
Author: Sergey Mitroshin <sergeymitr@gmail.com>
Date:   Tue Nov 17 20:01:01 2026 -0500

    UCP: Implement Cart handoff (#71052)

    Make UCP cart endpoints return handoff URL to transfer the cart session into the browser.

diff --git a/plugins/woocommerce/changelog/add-ucp-cart-continue-url b/plugins/woocommerce/changelog/add-ucp-cart-continue-url
new file mode 100644
index 00000000000..6efb8e25621
--- /dev/null
+++ b/plugins/woocommerce/changelog/add-ucp-cart-continue-url
@@ -0,0 +1,4 @@
+Significance: minor
+Type: add
+
+Add a checkout link to UCP cart responses so AI shopping agents can hand the cart to the buyer to complete the purchase.
diff --git a/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md b/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md
index d31f0cc44cb..74bd84df5d0 100644
--- a/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md
+++ b/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md
@@ -81,6 +81,7 @@
 - [woocommerce_store_api_rate_limit_options](#woocommerce_store_api_rate_limit_options)
 - [woocommerce_thankyou_order_failed_text](#woocommerce_thankyou_order_failed_text)
 - [woocommerce_thankyou_order_received_title](#woocommerce_thankyou_order_received_title)
+- [woocommerce_ucp_cart_continue_url](#woocommerce_ucp_cart_continue_url)
 - [woocommerce_ucp_idempotency_enabled](#woocommerce_ucp_idempotency_enabled)
 - [woocommerce_ucp_idempotency_retention_seconds](#woocommerce_ucp_idempotency_retention_seconds)
 - [woocommerce_ucp_idempotency_strict](#woocommerce_ucp_idempotency_strict)
@@ -2038,6 +2039,28 @@ apply_filters( 'woocommerce_thankyou_order_received_title', string $title, \WC_O

 ---

+## woocommerce_ucp_cart_continue_url
+
+
+Filters the URL a UCP cart hands the buyer for completing the purchase.
+
+```php
+apply_filters( 'woocommerce_ucp_cart_continue_url', string $continue_url, string $cart_id )
+```
+
+### Parameters
+
+| Argument | Type | Description |
+| -------- | ---- | ----------- |
+| $continue_url | string | Continue URL. |
+| $cart_id | string | Cart identifier. |
+
+### Source
+
+- [StoreApi/Utilities/Ucp/CartMapper.php](../../../../../../src/StoreApi/Utilities/Ucp/CartMapper.php)
+
+---
+
 ## woocommerce_ucp_idempotency_enabled


diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/Carts.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/Carts.php
index fee2b5d5f8d..91b77ceca73 100644
--- a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/Carts.php
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/Carts.php
@@ -60,7 +60,8 @@ class Carts extends AbstractCartRoute {
 	 * Create a cart.
 	 *
 	 * The id is minted from the session the cart was loaded into, so it is the token
-	 * that addresses this cart from now on.
+	 * that addresses this cart from now on — and, inside `continue_url`, the token
+	 * that lets the buyer's browser pick the same cart up.
 	 *
 	 * @param \WP_REST_Request $request Request object.
 	 *
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CartsCancel.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CartsCancel.php
index 0a6a4f982d5..27526caa8cc 100644
--- a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CartsCancel.php
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CartsCancel.php
@@ -78,6 +78,11 @@ class CartsCancel extends AbstractCartRoute {
 			)
 		);

+		// The cart is emptied below, so a handoff URL would point at nothing.
+		$data = $response->get_data();
+		unset( $data['continue_url'] );
+		$response->set_data( $data );
+
 		$this->cart_controller->empty_cart();
 		WC()->session->set( self::CANCELLED_SESSION_KEY, true );

diff --git a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CartMapper.php b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CartMapper.php
index ae7a5e03522..cf2700d0fdd 100644
--- a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CartMapper.php
+++ b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CartMapper.php
@@ -24,10 +24,11 @@ class CartMapper {
 	 */
 	public function build_cart( array $cart, string $cart_id, array $context = array() ): array {
 		$payload = array(
-			'id'         => $cart_id,
-			'currency'   => (string) $cart['totals']['currency_code'],
-			'line_items' => $this->line_items( (array) $cart['items'] ),
-			'totals'     => $this->totals( (array) $cart['totals'] ),
+			'id'           => $cart_id,
+			'currency'     => (string) $cart['totals']['currency_code'],
+			'line_items'   => $this->line_items( (array) $cart['items'] ),
+			'totals'       => $this->totals( (array) $cart['totals'] ),
+			'continue_url' => $this->continue_url( $cart_id ),
 		);

 		$expires_at = $this->expires_at( $cart_id );
@@ -181,6 +182,29 @@ class CartMapper {
 		return $messages;
 	}

+	/**
+	 * Build the URL that hands the cart to the buyer's own browser.
+	 *
+	 * `WC_Session_Handler` restores or clones the guest session named by the `session`
+	 * argument, so the shopper lands on checkout holding this cart.
+	 *
+	 * @param string $cart_id Cart identifier.
+	 * @return string
+	 */
+	private function continue_url( string $cart_id ): string {
+		$continue_url = add_query_arg( 'session', $cart_id, wc_get_cart_url() );
+
+		/**
+		 * Filters the URL a UCP cart hands the buyer for completing the purchase.
+		 *
+		 * @since 11.4.0
+		 *
+		 * @param string $continue_url Continue URL.
+		 * @param string $cart_id Cart identifier.
+		 */
+		return (string) apply_filters( 'woocommerce_ucp_cart_continue_url', $continue_url, $cart_id );
+	}
+
 	/**
 	 * Resolve the cart's expiry from its token.
 	 *
diff --git a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CheckoutMapper.php b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CheckoutMapper.php
index fac6bc9ecb7..ba75c8ae67f 100644
--- a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CheckoutMapper.php
+++ b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CheckoutMapper.php
@@ -32,6 +32,9 @@ class CheckoutMapper {
 		$missing  = $placed ? array() : $this->missing_requirements( $cart );
 		$messages = array_merge( $payload['messages'] ?? array(), $missing );

+		// A checkout carries its own `continue_url`, the payment page, only at escalation.
+		unset( $payload['continue_url'] );
+
 		if ( '' === $status ) {
 			$status = empty( $cart['items'] ) || ! empty( $cart['errors'] ) || ! empty( $missing ) ? self::STATUS_INCOMPLETE : self::STATUS_READY_FOR_COMPLETE;
 		}
diff --git a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCart.php b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCart.php
index 685c4936c35..2340fe0b0f4 100644
--- a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCart.php
+++ b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCart.php
@@ -428,6 +428,21 @@ class UcpCart extends UcpCartTestCase {
 		$this->assertNull( $this->total( $data['totals'], 'discount' ) );
 	}

+	/**
+	 * The cart hands the buyer a URL that restores the same cart in a browser.
+	 */
+	public function test_continue_url_carries_the_cart_token(): void {
+		wp_set_current_user( self::factory()->user->create( array( 'role' => 'customer' ) ) );
+		$data = $this->create_cart( array( $this->line_item( 0, 1 ) ) );
+
+		$query = array();
+		wp_parse_str( (string) wp_parse_url( $data['continue_url'], PHP_URL_QUERY ), $query );
+
+		// WC_Session_Handler restores or clones the guest session named by this token.
+		$this->assertSame( $data['id'], $query['session'] );
+		$this->assertStringStartsWith( wc_get_cart_url(), $data['continue_url'] );
+	}
+
 	/**
 	 * Line items outside the JSON document do not act.
 	 */
@@ -866,6 +881,7 @@ class UcpCart extends UcpCartTestCase {
 		$this->assertCount( 1, $data['line_items'] );
 		$this->assertSame( 2, $data['line_items'][0]['quantity'] );
 		$this->assertSame( 'CANCELED', $data['messages'][0]['code'] );
+		$this->assertArrayNotHasKey( 'continue_url', $data );

 		foreach ( array( 'GET', 'PUT' ) as $method ) {
 			$after = $this->request( $method, '/carts/' . $created['id'] )->get_data();
@@ -1064,8 +1080,8 @@ class UcpCart extends UcpCartTestCase {
 	/**
 	 * Cancelling a cart must not break a storefront session cloned from it.
 	 *
-	 * The marker lives in the WooCommerce session, which a storefront session cloned
-	 * from this token would carry too, so only the UCP routes may act on it.
+	 * The marker lives in the WooCommerce session, which the buyer's browser can
+	 * reach through `continue_url`, so only the UCP routes may act on it.
 	 */
 	public function test_cancelling_a_cart_leaves_the_storefront_session_usable(): void {
 		$created = $this->create_cart( array( $this->line_item( 0, 1 ) ) );