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 ) ) );