Commit f1617de5010 for woocommerce

commit f1617de50104280ce78c8a0005d2b5c0ff90efe3
Author: Sergey Mitroshin <sergeymitr@gmail.com>
Date:   Tue Nov 17 11:38:50 2026 -0500

    Add UCP Checkout endpoints (#70758)

    The PR adds the UCP Checkout endpoints as Store API routes under the `wc/ucp/v1` namespace:

    - `POST /wc/ucp/v1/checkout-sessions` creates a checkout from a `cart_id` or from `line_items`, with optional `buyer`, `billing_address` and `shipping_address`,
    - `GET /wc/ucp/v1/checkout-sessions/:id` reads a checkout,
    - `PUT /wc/ucp/v1/checkout-sessions/:id` replaces its line items and updates the buyer details,
    - `POST /wc/ucp/v1/checkout-sessions/:id/complete` hands the buyer over to the store to pay,
    - `POST /wc/ucp/v1/checkout-sessions/:id/cancel` cancels the checkout.

diff --git a/plugins/woocommerce/changelog/add-ucp-checkout-routes b/plugins/woocommerce/changelog/add-ucp-checkout-routes
new file mode 100644
index 00000000000..88e752f36a3
--- /dev/null
+++ b/plugins/woocommerce/changelog/add-ucp-checkout-routes
@@ -0,0 +1,4 @@
+Significance: minor
+Type: add
+
+Add UCP checkout endpoints so AI agents can start a checkout and hand the buyer a link to pay on the store.
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCartRoute.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCartRoute.php
index de4f807d8af..024066ba7da 100644
--- a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCartRoute.php
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCartRoute.php
@@ -3,11 +3,13 @@ declare( strict_types = 1 );

 namespace Automattic\WooCommerce\StoreApi\Routes\V1\Ucp;

+use Automattic\WooCommerce\Enums\OrderStatus;
 use Automattic\WooCommerce\StoreApi\Routes\V1\AbstractCartRoute as StoreApiCartRoute;
 use Automattic\WooCommerce\StoreApi\Exceptions\RouteException;
 use Automattic\WooCommerce\StoreApi\SessionHandler;
 use Automattic\WooCommerce\StoreApi\Utilities\CartTokenUtils;
 use Automattic\WooCommerce\StoreApi\Utilities\Ucp\CartMapper;
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\CheckoutMapper;
 use Automattic\WooCommerce\StoreApi\Utilities\Ucp\IdempotencyClaim;
 use Automattic\WooCommerce\StoreApi\Utilities\Ucp\Utils;

@@ -37,6 +39,13 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	 */
 	const CANCELLED_SESSION_KEY = 'ucp_cart_cancelled';

+	/**
+	 * Session key holding the checkout state: `created_at`, and once set `status`, `continue_url`, `order_id` and `fingerprint`.
+	 *
+	 * Its presence is what makes a cart session a checkout, so the cart routes read it too.
+	 */
+	const CHECKOUT_SESSION_KEY = 'ucp_checkout';
+
 	/**
 	 * Most lines one request may name.
 	 *
@@ -52,7 +61,16 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	 * @return array
 	 */
 	protected function ucp_metadata( string $status ): array {
-		return Utils::response_metadata( Utils::CAPABILITY_CART, $status );
+		return Utils::response_metadata( $this->capability(), $status );
+	}
+
+	/**
+	 * The capability this route answers for, named in every envelope it sends.
+	 *
+	 * @return string One of the Utils::CAPABILITY_* constants.
+	 */
+	protected function capability(): string {
+		return Utils::CAPABILITY_CART;
 	}

 	/**
@@ -70,12 +88,12 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	 * @return \WP_REST_Response
 	 */
 	public function get_response( \WP_REST_Request $request ) {
-		$refusal = Utils::refuse_non_json_payload( $request, Utils::CAPABILITY_CART );
+		$refusal = Utils::refuse_non_json_payload( $request, $this->capability() );
 		if ( null !== $refusal ) {
 			return $this->add_response_headers( $refusal );
 		}

-		$claim = IdempotencyClaim::for_request( $request, Utils::CAPABILITY_CART );
+		$claim = IdempotencyClaim::for_request( $request, $this->capability() );

 		if ( $claim instanceof \WP_REST_Response ) {
 			// The gate answers without reaching the parent, so it stamps the cache directive itself.
@@ -132,6 +150,27 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 		return $response;
 	}

+	/**
+	 * Sync the draft order with the cart after a write, unless it was handed off for payment.
+	 *
+	 * The buyer may be paying a pending or failed order, and a save would put this request's copy over theirs.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return void
+	 */
+	protected function cart_updated( \WP_REST_Request $request ) {
+		$order = $this->get_draft_order();
+
+		if ( $order && ! $order->has_status( OrderStatus::CHECKOUT_DRAFT ) ) {
+			return;
+		}
+
+		parent::cart_updated( $request );
+	}
+
 	/**
 	 * Put the request's cart token slot back the way it was found.
 	 *
@@ -154,13 +193,24 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	 * The parent picks the Store API session handler from a `Cart-Token` header. UCP
 	 * carries that token in the path, so it is promoted to the header first.
 	 *
+	 * The parent also lowers each line to the stock left before handling the request. No
+	 * human watches a UCP cart and `complete` carries no expected total, so a shortfall is
+	 * left in place for cart validation to report instead of being absorbed.
+	 *
 	 * @param \WP_REST_Request $request Request object.
 	 *
 	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
 	 *
+	 * @throws \RuntimeException When a previous cart session load failed.
+	 * @throws \Throwable When the cart cannot be loaded.
+	 *
 	 * @return void
 	 */
 	protected function load_cart_session( \WP_REST_Request $request ) {
+		if ( WC()->cart instanceof \WC_Cart && ! \WC_Cart_Session::are_updates_enabled_for_cart( WC()->cart ) ) {
+			throw new \RuntimeException( 'The cart is unavailable after its session failed to load.' );
+		}
+
 		$cart_id = $this->validated_cart_id( $request );

 		if ( '' === $cart_id ) {
@@ -190,7 +240,16 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 			$this->discard_preloaded_cart_session();
 		}

-		parent::load_cart_session( $request );
+		try {
+			$this->cart_controller->load_cart();
+		} catch ( \Throwable $error ) {
+			// The parent's flag: a later load in the same process must refuse, not reuse, this cart.
+			if ( WC()->cart instanceof \WC_Cart ) {
+				\WC_Cart_Session::set_updates_enabled_for_cart( WC()->cart, false );
+			}
+
+			throw $error;
+		}
 	}

 	/**
@@ -238,9 +297,10 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	}

 	/**
-	 * Dispatch the request, refusing a cart that was cancelled.
+	 * Dispatch the request, refusing a cart that was cancelled or that a checkout owns.
 	 *
-	 * Runs after the session is bound, so one check covers every id-bearing route.
+	 * Runs after the session is bound, so one check covers every id-bearing route. A live checkout's
+	 * cart is readable but changed only through the checkout routes, which close the buyer's order.
 	 *
 	 * @param \WP_REST_Request $request Request object.
 	 *
@@ -249,8 +309,20 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	 * @return \WP_REST_Response|\WP_Error
 	 */
 	protected function get_response_by_request_method( \WP_REST_Request $request ) {
-		if ( '' !== $this->route_cart_id( $request ) && $this->cart_is_cancelled() ) {
-			return $this->ucp_not_found();
+		if ( '' !== $this->route_cart_id( $request ) ) {
+			if ( $this->cart_is_cancelled() ) {
+				return $this->ucp_not_found();
+			}
+
+			$checkout = Utils::CAPABILITY_CART === $this->capability() ? $this->checkout_state() : null;
+
+			if ( null !== $checkout && $this->is_terminal( $checkout ) ) {
+				return $this->ucp_not_found();
+			}
+
+			if ( null !== $checkout && 'GET' !== $request->get_method() ) {
+				return $this->ucp_error( 'CONFLICT', __( 'This cart has become a checkout session, which the checkout routes manage.', 'woocommerce' ), 'recoverable', 409, '$.id' );
+			}
 		}

 		return parent::get_response_by_request_method( $request );
@@ -314,6 +386,50 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 		return $session ? (bool) $session->get( self::CANCELLED_SESSION_KEY ) : false;
 	}

+	/**
+	 * The bound session's checkout state, with the order filled in once the buyer has paid it.
+	 *
+	 * Paying happens in the browser, outside this session, so `completed` is read off the
+	 * order rather than stored. An order that can no longer be paid, such as one the hold-stock
+	 * timer cancelled, drops the hand-off so the status derives again.
+	 *
+	 * @return array<string, mixed>|null Null when the session holds no checkout.
+	 */
+	protected function checkout_state(): ?array {
+		$state = WC()->session ? WC()->session->get( self::CHECKOUT_SESSION_KEY ) : null;
+
+		if ( ! is_array( $state ) ) {
+			return null;
+		}
+
+		$order = empty( $state['order_id'] ) ? null : wc_get_order( (int) $state['order_id'] );
+
+		// Paid once is completed for good: a later refund or cancellation must not reopen the checkout.
+		if ( $order instanceof \WC_Order && ( $order->is_paid() || $order->get_date_paid() || $order->has_status( OrderStatus::REFUNDED ) ) ) {
+			$state['status'] = CheckoutMapper::STATUS_COMPLETED;
+			$state['order']  = array(
+				'id'            => (string) $order->get_id(),
+				'permalink_url' => $order->get_checkout_order_received_url(),
+			);
+		} elseif ( ! empty( $state['order_id'] ) && ! ( $order instanceof \WC_Order && $order->has_status( array( OrderStatus::PENDING, OrderStatus::FAILED, OrderStatus::ON_HOLD ) ) ) ) {
+			// Status list rather than needs_payment(): that is false for a zero-total order, and
+			// on-hold is a payment the buyer made that the store has yet to confirm.
+			unset( $state['status'], $state['continue_url'], $state['order_id'] );
+		}
+
+		return $state;
+	}
+
+	/**
+	 * Whether a checkout is completed or canceled.
+	 *
+	 * @param array<string, mixed> $state Checkout state.
+	 * @return bool
+	 */
+	protected function is_terminal( array $state ): bool {
+		return in_array( $state['status'] ?? '', array( CheckoutMapper::STATUS_COMPLETED, CheckoutMapper::STATUS_CANCELED ), true );
+	}
+
 	/**
 	 * Build a successful cart response.
 	 *
@@ -336,7 +452,7 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	 *
 	 * @return array
 	 */
-	private function cart_item_response(): array {
+	protected function cart_item_response(): array {
 		// Nested values are stdClass; decode through JSON for uniform array access.
 		return (array) json_decode( (string) wp_json_encode( $this->schema->get_item_response( $this->cart_controller->get_cart_for_response() ) ), true );
 	}
@@ -356,7 +472,7 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	 * @return \WP_REST_Response
 	 */
 	protected function ucp_error( string $code, string $message, string $severity, int $status, string $path = '$' ): \WP_REST_Response {
-		return Utils::error_response( Utils::CAPABILITY_CART, $code, $message, $severity, $status, $path );
+		return Utils::error_response( $this->capability(), $code, $message, $severity, $status, $path );
 	}

 	/**
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCheckoutRoute.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCheckoutRoute.php
new file mode 100644
index 00000000000..8072b3bde21
--- /dev/null
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCheckoutRoute.php
@@ -0,0 +1,464 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\StoreApi\Routes\V1\Ucp;
+
+use Automattic\WooCommerce\Enums\OrderStatus;
+use Automattic\WooCommerce\StoreApi\Schemas\V1\OrderSchema;
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\CheckoutMapper;
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\Utils;
+
+/**
+ * Shared behaviour of the UCP checkout routes.
+ *
+ * A checkout is a cart session promoted through `POST /checkout-sessions`, so its id is the
+ * cart id and every cart route rule applies: path-bound token session, no nonce, last-wins
+ * writes. The checkout's own state sits beside the cart in the WC session.
+ */
+abstract class AbstractCheckoutRoute extends AbstractCartRoute {
+	/**
+	 * The routes schema.
+	 *
+	 * @var string
+	 */
+	const SCHEMA_TYPE = 'ucp-checkout';
+
+	/**
+	 * The capability this route answers for.
+	 *
+	 * @return string
+	 */
+	protected function capability(): string {
+		return Utils::CAPABILITY_CHECKOUT;
+	}
+
+	/**
+	 * Build the `ucp` envelope, with the `payment_handlers` registry a checkout response requires.
+	 *
+	 * Empty: these routes take no payment, and `complete` hands the buyer to the store instead.
+	 *
+	 * @param string $status Response status, `success` or `error`.
+	 * @return array
+	 */
+	protected function ucp_metadata( string $status ): array {
+		$metadata                     = parent::ucp_metadata( $status );
+		$metadata['payment_handlers'] = new \stdClass();
+
+		return $metadata;
+	}
+
+	/**
+	 * Build the response for a checkout id that does not resolve.
+	 *
+	 * Unlike the cart routes, a 404: the checkout REST binding names it as a transport error.
+	 *
+	 * @return \WP_REST_Response
+	 */
+	protected function ucp_not_found(): \WP_REST_Response {
+		return $this->ucp_error( 'not_found', __( 'Checkout session not found.', 'woocommerce' ), 'unrecoverable', 404, '$.id' );
+	}
+
+	/**
+	 * Load the state of the checkout the route path names, refusing one that cannot be acted on.
+	 *
+	 * @param bool $for_update Whether the request changes the checkout, which a completed, canceled or paid-but-unconfirmed one refuses.
+	 * @return array<string, mixed>|\WP_REST_Response The state, or the 404/409 error response.
+	 */
+	protected function open_checkout( bool $for_update ) {
+		$state = $this->checkout_state();
+
+		if ( null === $state ) {
+			return $this->ucp_not_found();
+		}
+
+		if ( $for_update ) {
+			if ( $this->is_terminal( $state ) ) {
+				return $this->ucp_conflict();
+			}
+
+			if ( $this->awaits_confirmation( $state ) ) {
+				return $this->ucp_conflict( __( 'This checkout session is awaiting confirmation of a payment the buyer already made.', 'woocommerce' ) );
+			}
+		}
+
+		return $state;
+	}
+
+	/**
+	 * Whether the handed-off order holds a payment the store has yet to confirm, such as a bank transfer.
+	 *
+	 * The buyer paid in the browser, where the cart would have been emptied; this session was not, so
+	 * it is locked until the store accepts or cancels that payment, or a second order would be made.
+	 *
+	 * @param array<string, mixed> $state Checkout state.
+	 * @return bool
+	 */
+	protected function awaits_confirmation( array $state ): bool {
+		$order = empty( $state['order_id'] ) ? null : wc_get_order( (int) $state['order_id'] );
+
+		return $order instanceof \WC_Order && ! $order->has_status( $this->payable_statuses( $order ) );
+	}
+
+	/**
+	 * The statuses in which the payment page still takes an order, as `WC_Order::needs_payment()` lists them.
+	 *
+	 * @param \WC_Order $order The order.
+	 * @return array<string>
+	 */
+	protected function payable_statuses( \WC_Order $order ): array {
+		// phpcs:ignore WooCommerce.Commenting.CommentHooks.MissingHookComment -- Core's hook, documented in WC_Order::needs_payment().
+		return (array) apply_filters( 'woocommerce_valid_order_statuses_for_payment', array( OrderStatus::PENDING, OrderStatus::FAILED ), $order );
+	}
+
+	/**
+	 * Cancel the order handed to the buyer while its payment page would still take it, and forget the hand-off.
+	 *
+	 * Once the checkout changes or ends, that order no longer matches it and must not be paid.
+	 * The state is saved without the hand-off, unless the order was paid meanwhile and stays.
+	 *
+	 * @param array<string, mixed> $state Checkout state.
+	 * @param string               $note Order note explaining the cancellation.
+	 * @return array<string, mixed> The state without the hand-off, or unchanged, `order_id` included, when the order was paid meanwhile or could not be cancelled.
+	 */
+	protected function cancel_handed_off_order( array $state, string $note ): array {
+		$order = empty( $state['order_id'] ) ? null : wc_get_order( (int) $state['order_id'] );
+
+		if ( $order instanceof \WC_Order ) {
+			// Paid, or put on hold, since the request began: the checkout keeps its order and hand-off.
+			if ( ! $order->has_status( $this->payable_statuses( $order ) ) ) {
+				return $state;
+			}
+
+			// The payment page's own list, so a failed attempt the buyer could retry is closed too.
+			// A cancellation that did not save leaves the order payable, so the checkout goes on tracking it.
+			if ( ! $order->update_status( OrderStatus::CANCELLED, $note ) ) {
+				return $state;
+			}
+
+			if ( (int) $this->get_draft_order_id() === $order->get_id() ) {
+				$this->set_draft_order_id( 0 );
+			}
+		}
+
+		unset( $state['order_id'], $state['fingerprint'], $state['status'], $state['continue_url'] );
+		$this->save_checkout_state( $state );
+
+		return $state;
+	}
+
+	/**
+	 * Whether the handed-off order can still be paid, as it can after a cancellation that failed.
+	 *
+	 * @param array<string, mixed> $state Checkout state.
+	 * @return bool
+	 */
+	protected function hand_off_is_payable( array $state ): bool {
+		$order = empty( $state['order_id'] ) ? null : wc_get_order( (int) $state['order_id'] );
+
+		return $order instanceof \WC_Order && $order->has_status( $this->payable_statuses( $order ) );
+	}
+
+	/**
+	 * Refuse a request whose order was paid, or put on hold, while it ran, as if it had arrived a moment later.
+	 *
+	 * An order still payable is one that could not be cancelled, which a retry may yet do.
+	 *
+	 * @return \WP_REST_Response
+	 */
+	protected function refuse_kept_order(): \WP_REST_Response {
+		$refusal = $this->open_checkout( true );
+
+		if ( $refusal instanceof \WP_REST_Response ) {
+			return $refusal;
+		}
+
+		if ( $this->hand_off_is_payable( $refusal ) ) {
+			return $this->ucp_error( 'TRANSPORT_ERROR', __( 'The order handed off earlier could not be canceled. Please try again.', 'woocommerce' ), 'recoverable', 500 );
+		}
+
+		return $this->ucp_conflict();
+	}
+
+	/**
+	 * Fingerprint what a handed-off order is built from: cart contents and total, addresses and shipping choice.
+	 *
+	 * @return string
+	 */
+	protected function hand_off_fingerprint(): string {
+		return hash(
+			'sha256',
+			(string) wp_json_encode(
+				array(
+					$this->cart_controller->get_cart_instance()->get_cart_hash(),
+					WC()->customer->get_billing(),
+					WC()->customer->get_shipping(),
+					WC()->session->get( 'chosen_shipping_methods' ),
+				)
+			)
+		);
+	}
+
+	/**
+	 * Store the checkout state in the bound session.
+	 *
+	 * @param array<string, mixed> $state Checkout state.
+	 */
+	protected function save_checkout_state( array $state ): void {
+		unset( $state['order'] );
+		WC()->session->set( self::CHECKOUT_SESSION_KEY, $state );
+	}
+
+	/**
+	 * Build the response refusing a change to a checkout in a state that does not take one.
+	 *
+	 * @param string $message Why the change is refused; defaults to the checkout being completed or canceled.
+	 * @return \WP_REST_Response
+	 */
+	protected function ucp_conflict( string $message = '' ): \WP_REST_Response {
+		if ( '' === $message ) {
+			$message = __( 'This checkout session is already completed or canceled.', 'woocommerce' );
+		}
+
+		return $this->ucp_error( 'CONFLICT', $message, 'unrecoverable', 409, '$.status' );
+	}
+
+	/**
+	 * Build a successful checkout response.
+	 *
+	 * A paid checkout is read from its order: the cart session lives on and follows later price and stock changes.
+	 * So is one whose payment awaits the store's confirmation, which reads as `complete_in_progress`.
+	 * A cart changed behind a hand-off voids it for the read too, until an update or complete cancels the order.
+	 *
+	 * @param string               $checkout_id Checkout identifier.
+	 * @param array<string, mixed> $state Checkout state.
+	 * @param int                  $http_status HTTP status.
+	 * @param array|null           $cart Store API cart response already built for this request, or null to build it.
+	 * @return \WP_REST_Response
+	 */
+	protected function checkout_response( string $checkout_id, array $state, int $http_status = 200, ?array $cart = null ): \WP_REST_Response {
+		$order_id = (int) ( $state['order']['id'] ?? 0 );
+
+		if ( ! $order_id && $this->awaits_confirmation( $state ) ) {
+			// The buyer has paid, so the payment page must not be offered again while the store confirms.
+			$order_id        = (int) $state['order_id'];
+			$state['status'] = CheckoutMapper::STATUS_COMPLETE_IN_PROGRESS;
+			unset( $state['continue_url'] );
+		}
+
+		$order = $order_id ? wc_get_order( $order_id ) : null;
+
+		if ( $order instanceof \WC_Order ) {
+			$cart = $this->order_as_cart( $order );
+		} elseif ( ! empty( $state['continue_url'] ) && ( $state['fingerprint'] ?? '' ) !== $this->hand_off_fingerprint() ) {
+			unset( $state['status'], $state['continue_url'] );
+		}
+
+		return new \WP_REST_Response(
+			array_merge(
+				array( 'ucp' => $this->ucp_metadata( 'success' ) ),
+				( new CheckoutMapper() )->build_checkout( $cart ?? $this->cart_item_response(), $checkout_id, $state )
+			),
+			$http_status
+		);
+	}
+
+	/**
+	 * Build the Store API order response in the shape of a cart response, for the mappers to read.
+	 *
+	 * The order schema differs from the cart's where an order line is not a cart line: its ids,
+	 * its name, and a price that is the product's current one rather than the one paid.
+	 *
+	 * @param \WC_Order $order The paid or on-hold order.
+	 * @return array
+	 */
+	private function order_as_cart( \WC_Order $order ): array {
+		$cart     = (array) json_decode( (string) wp_json_encode( $this->schema_controller->get( OrderSchema::IDENTIFIER )->get_item_response( $order ) ), true );
+		$with_tax = 'incl' === get_option( 'woocommerce_tax_display_cart' );
+
+		foreach ( array_values( $order->get_items() ) as $index => $item ) {
+			if ( ! $item instanceof \WC_Order_Item_Product || ! isset( $cart['items'][ $index ] ) ) {
+				continue;
+			}
+
+			$line     = $cart['items'][ $index ];
+			$product  = $item->get_product();
+			$subtotal = (int) $line['totals']['line_subtotal'] + ( $with_tax ? (int) $line['totals']['line_subtotal_tax'] : 0 );
+
+			$line['id']              = $item->get_variation_id() ? $item->get_variation_id() : $item->get_product_id();
+			$line['key']             = (string) $item->get_id();
+			$line['prices']['price'] = (int) round( $subtotal / max( 1, (int) $item->get_quantity() ) );
+
+			// An order line's name already holds the attributes the mapper appends from `variation`.
+			if ( ! empty( $line['variation'] ) && $product instanceof \WC_Product ) {
+				$line['name'] = $product->get_title();
+			}
+
+			$cart['items'][ $index ] = $line;
+		}
+
+		// A cart's `total_items` is the subtotal before discounts; an order's is the sum after them.
+		$cart['totals']['total_items'] = $cart['totals']['subtotal'];
+		$cart['errors']                = array();
+
+		return $cart;
+	}
+
+	/**
+	 * Replace the cart lines with the request's `line_items`, when it sends them.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response|null An error response, or null when the lines were applied or left alone.
+	 */
+	protected function update_line_items( \WP_REST_Request $request ): ?\WP_REST_Response {
+		$line_items = Utils::json_param( $request, 'line_items' );
+
+		if ( null === $line_items ) {
+			return null;
+		}
+
+		$desired = $this->parse_line_items( $line_items );
+
+		return $desired instanceof \WP_REST_Response ? $desired : $this->apply_line_items( $desired );
+	}
+
+	/**
+	 * Apply the request's `buyer`, `billing_address` and `shipping_address` to the session customer.
+	 *
+	 * Only the fields sent are changed. Each address is sanitized and validated by the Store API
+	 * address schema, as `POST /cart/update-customer` does.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response|null An error response, or null when the customer was updated or left alone.
+	 */
+	protected function update_customer( \WP_REST_Request $request ): ?\WP_REST_Response {
+		$postal_fields = array(
+			'first_name'       => 'first_name',
+			'last_name'        => 'last_name',
+			'street_address'   => 'address_1',
+			'extended_address' => 'address_2',
+			'address_locality' => 'city',
+			'address_region'   => 'state',
+			'postal_code'      => 'postcode',
+			'address_country'  => 'country',
+			'phone_number'     => 'phone',
+		);
+
+		$billing_address = $this->pick_fields( Utils::json_param( $request, 'billing_address' ), $postal_fields );
+		$changes         = array(
+			'billing'  => array_merge(
+				$billing_address,
+				$this->pick_fields(
+					Utils::json_param( $request, 'buyer' ),
+					array(
+						'first_name'   => 'first_name',
+						'last_name'    => 'last_name',
+						'email'        => 'email',
+						'phone_number' => 'phone',
+					)
+				)
+			),
+			'shipping' => $this->pick_fields( Utils::json_param( $request, 'shipping_address' ), $postal_fields ),
+		);
+
+		if ( empty( $changes['billing'] ) && empty( $changes['shipping'] ) ) {
+			return null;
+		}
+
+		// As the Store API does: without shipping, taxes follow the billing address whatever the tax setting.
+		if ( empty( $changes['shipping'] ) && ! $this->cart_controller->get_cart_instance()->needs_shipping() ) {
+			$changes['shipping'] = $changes['billing'];
+		}
+
+		$customer = WC()->customer;
+		$changes  = $this->share_between_addresses( $changes, $customer, empty( $billing_address ) );
+		$props    = array();
+
+		foreach ( $changes as $type => $fields ) {
+			if ( empty( $fields ) ) {
+				continue;
+			}
+
+			$address_schema = 'billing' === $type ? $this->cart_schema->billing_address_schema : $this->cart_schema->shipping_address_schema;
+			$param          = $type . '_address';
+			$address        = $address_schema->sanitize_callback( array_merge( $address_schema->get_item_response( $customer ), $fields ), $request, $param );
+			$valid          = $address_schema->validate_callback( $address, $request, $param );
+
+			if ( true !== $valid ) {
+				$message = is_wp_error( $valid ) ? implode( ' ', $valid->get_error_messages() ) : __( 'Invalid address.', 'woocommerce' );
+
+				return $this->ucp_error( 'VALIDATION_ERROR', $message, 'recoverable', 400, '$.' . $param );
+			}
+
+			foreach ( $address as $key => $value ) {
+				$props[ $type . '_' . $key ] = $value;
+			}
+		}
+
+		$customer->set_props( $props );
+		$customer->save();
+		$this->cart_controller->calculate_totals();
+
+		return null;
+	}
+
+	/**
+	 * Let one address supply what the other lacks, as the storefront's "same address for billing" does.
+	 *
+	 * Billing follows a shipping change while the two still match and the request names no billing
+	 * address of its own. A name or phone held by only one address is copied to the other.
+	 *
+	 * @param array{billing: array<string, string>, shipping: array<string, string>} $changes Fields the request changes, per address.
+	 * @param \WC_Customer                                                           $customer The session customer, before the changes.
+	 * @param bool                                                                   $follow Whether billing may follow shipping.
+	 * @return array{billing: array<string, string>, shipping: array<string, string>}
+	 */
+	private function share_between_addresses( array $changes, \WC_Customer $customer, bool $follow ): array {
+		$billing  = $customer->get_billing();
+		$shipping = $customer->get_shipping();
+		$postal   = array_flip( array( 'address_1', 'address_2', 'city', 'state', 'postcode', 'country' ) );
+
+		if ( $follow && array_intersect_key( $billing, $postal ) === array_intersect_key( $shipping, $postal ) ) {
+			$changes['billing'] = array_merge( array_intersect_key( $changes['shipping'], $postal ), $changes['billing'] );
+		}
+
+		$billing  = array_merge( $billing, $changes['billing'] );
+		$shipping = array_merge( $shipping, $changes['shipping'] );
+
+		foreach ( array( 'first_name', 'last_name', 'phone' ) as $key ) {
+			if ( '' === (string) $billing[ $key ] && '' !== (string) $shipping[ $key ] ) {
+				$changes['billing'][ $key ] = (string) $shipping[ $key ];
+			} elseif ( '' === (string) $shipping[ $key ] && '' !== (string) $billing[ $key ] ) {
+				$changes['shipping'][ $key ] = (string) $billing[ $key ];
+			}
+		}
+
+		return $changes;
+	}
+
+	/**
+	 * Copy the scalar fields of a request object into WooCommerce field names.
+	 *
+	 * @param mixed                 $input Request object, ignored unless an array.
+	 * @param array<string, string> $map UCP field name to WooCommerce field name.
+	 * @return array<string, string>
+	 */
+	private function pick_fields( $input, array $map ): array {
+		$fields = array();
+
+		if ( is_array( $input ) ) {
+			foreach ( $map as $from => $to ) {
+				if ( isset( $input[ $from ] ) && is_scalar( $input[ $from ] ) ) {
+					$fields[ $to ] = (string) $input[ $from ];
+				}
+			}
+		}
+
+		return $fields;
+	}
+}
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessions.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessions.php
new file mode 100644
index 00000000000..ab1d9d61ede
--- /dev/null
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessions.php
@@ -0,0 +1,177 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\StoreApi\Routes\V1\Ucp;
+
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\Utils;
+
+/**
+ * UCP `POST /checkout-sessions` route.
+ */
+class CheckoutSessions extends AbstractCheckoutRoute {
+	/**
+	 * The route identifier.
+	 *
+	 * @var string
+	 */
+	const IDENTIFIER = 'ucp-checkout-sessions';
+
+	/**
+	 * Get the path of this REST route.
+	 *
+	 * @return string
+	 */
+	public function get_path() {
+		return self::get_path_regex();
+	}
+
+	/**
+	 * Get the path of this rest route.
+	 *
+	 * @return string
+	 */
+	public static function get_path_regex() {
+		return '/checkout-sessions';
+	}
+
+	/**
+	 * Get method arguments for this REST route.
+	 *
+	 * @return array An array of endpoints.
+	 */
+	public function get_args() {
+		return array(
+			array(
+				'methods'             => \WP_REST_Server::CREATABLE,
+				'callback'            => array( $this, 'get_response' ),
+				'permission_callback' => '__return_true',
+				'args'                => array(
+					'cart_id'          => array(
+						'description' => __( 'Cart to promote to a checkout. The checkout keeps its id.', 'woocommerce' ),
+						'type'        => 'string',
+					),
+					'line_items'       => array(
+						'description' => __( 'Items to check out, required when no cart_id is given.', 'woocommerce' ),
+						'type'        => 'array',
+					),
+					'buyer'            => array(
+						'description' => __( 'Buyer contact details.', 'woocommerce' ),
+						'type'        => 'object',
+					),
+					'billing_address'  => array(
+						'description' => __( 'Billing postal address.', 'woocommerce' ),
+						'type'        => 'object',
+					),
+					'shipping_address' => array(
+						'description' => __( 'Shipping postal address.', 'woocommerce' ),
+						'type'        => 'object',
+					),
+				),
+			),
+			'schema' => array( $this->schema, 'get_public_item_schema' ),
+		);
+	}
+
+	/**
+	 * Read the id of the cart to promote from the JSON body.
+	 *
+	 * Creation has no path id; the body's `cart_id` binds the session instead. Safe for the same
+	 * reason the path is: the id is a signed token, so it only reaches a cart this store handed out.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return string The cart id, or '' to start from a fresh session.
+	 */
+	protected function route_cart_id( \WP_REST_Request $request ): string {
+		$cart_id = Utils::json_param( $request, 'cart_id' );
+
+		return is_string( $cart_id ) ? $cart_id : '';
+	}
+
+	/**
+	 * Create a checkout, from an existing cart or from line items.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response
+	 */
+	protected function get_route_post_response( \WP_REST_Request $request ) {
+		$checkout_id = $this->route_cart_id( $request );
+
+		if ( '' !== $checkout_id ) {
+			// The cart is the source of truth, so `line_items` is ignored; an update can change it.
+			$state = $this->checkout_state();
+
+			if ( null !== $state ) {
+				// UCP's idempotent conversion: a cart that already is a checkout is returned as it stands, the body ignored.
+				return $this->is_terminal( $state ) ? $this->ucp_conflict() : $this->existing_checkout_response( $request, $checkout_id, $state );
+			}
+
+			if ( $this->cart_controller->get_cart_instance()->is_empty() ) {
+				return $this->ucp_not_found();
+			}
+		} else {
+			$line_items = Utils::json_param( $request, 'line_items' );
+
+			if ( ! is_array( $line_items ) || empty( $line_items ) ) {
+				return $this->ucp_error( 'VALIDATION_ERROR', __( 'line_items is required when no cart_id is given.', 'woocommerce' ), 'recoverable', 400, '$.line_items' );
+			}
+
+			$error = $this->update_line_items( $request );
+
+			if ( null !== $error ) {
+				return $error;
+			}
+
+			$checkout_id = $this->current_cart_id();
+
+			if ( '' === $checkout_id ) {
+				return $this->ucp_error( 'TRANSPORT_ERROR', __( 'The checkout session could not be created.', 'woocommerce' ), 'recoverable', 500 );
+			}
+		}
+
+		$error = $this->update_customer( $request );
+
+		if ( null !== $error ) {
+			return $error;
+		}
+
+		$state = array( 'created_at' => time() );
+		$this->save_checkout_state( $state );
+
+		return $this->checkout_response( $checkout_id, $state, 201 );
+	}
+
+	/**
+	 * Return a checkout that already exists, warning when the request tried to change it.
+	 *
+	 * @param \WP_REST_Request     $request Request object.
+	 * @param string               $checkout_id Checkout identifier.
+	 * @param array<string, mixed> $state Checkout state.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response
+	 */
+	private function existing_checkout_response( \WP_REST_Request $request, string $checkout_id, array $state ): \WP_REST_Response {
+		$response = $this->checkout_response( $checkout_id, $state );
+
+		if ( ! empty( array_diff_key( (array) $request->get_json_params(), array( 'cart_id' => true ) ) ) ) {
+			$data               = (array) $response->get_data();
+			$data['messages'][] = array(
+				'type'         => 'warning',
+				'code'         => 'FIELDS_IGNORED',
+				'content'      => __( 'This cart already is a checkout session, so it was returned unchanged and the other fields were ignored. Update the checkout session to change it.', 'woocommerce' ),
+				'path'         => '$',
+				'content_type' => 'plain',
+			);
+			$response->set_data( $data );
+		}
+
+		return $response;
+	}
+}
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsById.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsById.php
new file mode 100644
index 00000000000..f64ca7c7f21
--- /dev/null
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsById.php
@@ -0,0 +1,120 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\StoreApi\Routes\V1\Ucp;
+
+/**
+ * UCP `GET /checkout-sessions/{id}` and `PUT /checkout-sessions/{id}` route.
+ */
+class CheckoutSessionsById extends AbstractCheckoutRoute {
+	/**
+	 * The route identifier.
+	 *
+	 * @var string
+	 */
+	const IDENTIFIER = 'ucp-checkout-sessions-by-id';
+
+	/**
+	 * Get the path of this REST route.
+	 *
+	 * @return string
+	 */
+	public function get_path() {
+		return self::get_path_regex();
+	}
+
+	/**
+	 * Get the path of this rest route.
+	 *
+	 * @return string
+	 */
+	public static function get_path_regex() {
+		return '/checkout-sessions/(?P<id>[\w\-\.]+)';
+	}
+
+	/**
+	 * Get method arguments for this REST route.
+	 *
+	 * PUT only, as for carts: `line_items` is the complete desired state.
+	 *
+	 * @return array An array of endpoints.
+	 */
+	public function get_args() {
+		return array(
+			array(
+				'methods'             => \WP_REST_Server::READABLE,
+				'callback'            => array( $this, 'get_response' ),
+				'permission_callback' => '__return_true',
+			),
+			array(
+				'methods'             => 'PUT',
+				'callback'            => array( $this, 'get_response' ),
+				'permission_callback' => '__return_true',
+				'args'                => array(
+					'line_items'       => array(
+						'description' => __( 'The complete desired contents of the checkout.', 'woocommerce' ),
+						'type'        => 'array',
+					),
+					'buyer'            => array(
+						'description' => __( 'Buyer contact details.', 'woocommerce' ),
+						'type'        => 'object',
+					),
+					'billing_address'  => array(
+						'description' => __( 'Billing postal address.', 'woocommerce' ),
+						'type'        => 'object',
+					),
+					'shipping_address' => array(
+						'description' => __( 'Shipping postal address.', 'woocommerce' ),
+						'type'        => 'object',
+					),
+				),
+			),
+			'schema' => array( $this->schema, 'get_public_item_schema' ),
+		);
+	}
+
+	/**
+	 * Read a checkout.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response
+	 */
+	protected function get_route_response( \WP_REST_Request $request ) {
+		$state = $this->open_checkout( false );
+
+		return $state instanceof \WP_REST_Response ? $state : $this->checkout_response( $this->route_cart_id( $request ), $state );
+	}
+
+	/**
+	 * Update a checkout.
+	 *
+	 * A change drops an earlier escalation and cancels its unpaid order, which no longer
+	 * matches the cart, so the status is derived again and `complete` hands off afresh.
+	 * That holds for a request refused part-way too, while one that changes nothing keeps the hand-off.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response
+	 */
+	protected function get_route_update_response( \WP_REST_Request $request ) {
+		$state = $this->open_checkout( true );
+
+		if ( $state instanceof \WP_REST_Response ) {
+			return $state;
+		}
+
+		$error = $this->update_line_items( $request ) ?? $this->update_customer( $request );
+
+		if ( ( $state['fingerprint'] ?? '' ) !== $this->hand_off_fingerprint() ) {
+			$state = $this->cancel_handed_off_order( $state, __( 'UCP checkout session changed after payment was handed off.', 'woocommerce' ) );
+		}
+
+		// Read again, so an order paid while this request ran is reported as it now stands.
+		return $error ?? $this->checkout_response( $this->route_cart_id( $request ), $this->checkout_state() ?? $state );
+	}
+}
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsCancel.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsCancel.php
new file mode 100644
index 00000000000..864ffb66ffd
--- /dev/null
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsCancel.php
@@ -0,0 +1,83 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\StoreApi\Routes\V1\Ucp;
+
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\CheckoutMapper;
+
+/**
+ * UCP `POST /checkout-sessions/{id}/cancel` route.
+ */
+class CheckoutSessionsCancel extends AbstractCheckoutRoute {
+	/**
+	 * The route identifier.
+	 *
+	 * @var string
+	 */
+	const IDENTIFIER = 'ucp-checkout-sessions-cancel';
+
+	/**
+	 * Get the path of this REST route.
+	 *
+	 * @return string
+	 */
+	public function get_path() {
+		return self::get_path_regex();
+	}
+
+	/**
+	 * Get the path of this rest route.
+	 *
+	 * @return string
+	 */
+	public static function get_path_regex() {
+		return '/checkout-sessions/(?P<id>[\w\-\.]+)/cancel';
+	}
+
+	/**
+	 * Get method arguments for this REST route.
+	 *
+	 * @return array An array of endpoints.
+	 */
+	public function get_args() {
+		return array(
+			array(
+				'methods'             => \WP_REST_Server::CREATABLE,
+				'callback'            => array( $this, 'get_response' ),
+				'permission_callback' => '__return_true',
+			),
+			'schema' => array( $this->schema, 'get_public_item_schema' ),
+		);
+	}
+
+	/**
+	 * Cancel a checkout.
+	 *
+	 * The cart is kept, so the checkout goes on answering with its canceled payload. An order
+	 * handed to the buyer and still unpaid is cancelled too, so it can no longer be paid.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response
+	 */
+	protected function get_route_post_response( \WP_REST_Request $request ) {
+		$state = $this->open_checkout( true );
+
+		if ( $state instanceof \WP_REST_Response ) {
+			return $state;
+		}
+
+		$state = $this->cancel_handed_off_order( $state, __( 'UCP checkout session canceled.', 'woocommerce' ) );
+
+		if ( ! empty( $state['order_id'] ) ) {
+			return $this->refuse_kept_order();
+		}
+
+		$state['status'] = CheckoutMapper::STATUS_CANCELED;
+		$this->save_checkout_state( $state );
+
+		return $this->checkout_response( $this->route_cart_id( $request ), $state );
+	}
+}
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsComplete.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsComplete.php
new file mode 100644
index 00000000000..72e5eacba81
--- /dev/null
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsComplete.php
@@ -0,0 +1,198 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\StoreApi\Routes\V1\Ucp;
+
+use Automattic\WooCommerce\Checkout\Helpers\ReserveStockException;
+use Automattic\WooCommerce\Enums\OrderStatus;
+use Automattic\WooCommerce\StoreApi\Exceptions\RouteException;
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\CheckoutMapper;
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\Utils;
+
+/**
+ * UCP `POST /checkout-sessions/{id}/complete` route.
+ */
+class CheckoutSessionsComplete extends AbstractCheckoutRoute {
+	/**
+	 * The route identifier.
+	 *
+	 * @var string
+	 */
+	const IDENTIFIER = 'ucp-checkout-sessions-complete';
+
+	/**
+	 * Get the path of this REST route.
+	 *
+	 * @return string
+	 */
+	public function get_path() {
+		return self::get_path_regex();
+	}
+
+	/**
+	 * Get the path of this rest route.
+	 *
+	 * @return string
+	 */
+	public static function get_path_regex() {
+		return '/checkout-sessions/(?P<id>[\w\-\.]+)/complete';
+	}
+
+	/**
+	 * Get method arguments for this REST route.
+	 *
+	 * @return array An array of endpoints.
+	 */
+	public function get_args() {
+		return array(
+			array(
+				'methods'             => \WP_REST_Server::CREATABLE,
+				'callback'            => array( $this, 'get_response' ),
+				'permission_callback' => '__return_true',
+			),
+			'schema' => array( $this->schema, 'get_public_item_schema' ),
+		);
+	}
+
+	/**
+	 * Hand a ready checkout over to the buyer to pay in the browser.
+	 *
+	 * No payment is taken through the API, so `payment` is ignored. The cart becomes a pending
+	 * order, the Store API draft order of this session, and `continue_url` is its payment page.
+	 * Stock is held for the order first, as the Store API checkout does, because the payment
+	 * page trusts a pending order's stock to be held and checks nothing itself.
+	 * A cart with nothing to pay is refused: these routes complete no order, and the payment page takes no such order.
+	 * A checkout that is not ready yet is returned as it is, with messages naming what is missing.
+	 * So is one already handed off and unchanged since, with a warning: its order is not written to again.
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response
+	 */
+	protected function get_route_post_response( \WP_REST_Request $request ) {
+		$state = $this->open_checkout( true );
+
+		if ( $state instanceof \WP_REST_Response ) {
+			return $state;
+		}
+
+		$checkout_id = $this->route_cart_id( $request );
+		$cart        = $this->cart_item_response();
+		$order       = $this->get_draft_order();
+		unset( $state['status'], $state['continue_url'] );
+
+		// Taken before the hooks below run, so a cart one of them changes no longer matches the order.
+		$fingerprint = $this->hand_off_fingerprint();
+
+		// The cart or its addresses can change behind the checkout, through the Store API or a price edit, and
+		// a new order is then made for it: the one already handed off must not stay payable too.
+		if ( ! empty( $state['order_id'] ) && ( ! $order || $order->get_id() !== (int) $state['order_id'] || ( $state['fingerprint'] ?? '' ) !== $fingerprint ) ) {
+			$state = $this->cancel_handed_off_order( $state, __( 'UCP checkout session cart changed after payment was handed off.', 'woocommerce' ) );
+
+			if ( ! empty( $state['order_id'] ) ) {
+				return $this->refuse_kept_order();
+			}
+
+			$order = $this->get_draft_order();
+		}
+
+		if ( CheckoutMapper::STATUS_READY_FOR_COMPLETE !== ( new CheckoutMapper() )->build_checkout( $cart, $checkout_id, $state )['status'] ) {
+			// An order handed off while the checkout was ready, for stock since taken say, must not stay payable.
+			$state = $this->cancel_handed_off_order( $state, __( 'UCP checkout session is no longer ready to complete.', 'woocommerce' ) );
+
+			if ( $this->hand_off_is_payable( $state ) ) {
+				return $this->refuse_kept_order();
+			}
+
+			return $this->checkout_response( $checkout_id, $this->checkout_state() ?? $state, 200, $cart );
+		}
+
+		if ( ! $this->cart_controller->get_cart_instance()->needs_payment() ) {
+			return $this->ucp_error( 'payment_not_required', __( 'This checkout has nothing to pay, so it cannot be handed off for payment. It must be made on the store itself.', 'woocommerce' ), 'unrecoverable', 200 );
+		}
+
+		// Handed off already and unchanged. The buyer may be paying this order now, so it is not written to again.
+		if ( ! empty( $state['order_id'] ) ) {
+			return $this->already_handed_off_response( $checkout_id, $cart );
+		}
+
+		if ( $order ) {
+			$this->order_controller->update_order_from_cart( $order );
+		} else {
+			$order = $this->order_controller->create_order_from_cart();
+		}
+
+		if ( ! $order->get_id() ) {
+			return $this->ucp_error( 'TRANSPORT_ERROR', __( 'The order could not be created. Please try again.', 'woocommerce' ), 'recoverable', 500 );
+		}
+
+		// Remembered before the hold so a refused hold leaves a draft the next attempt reuses.
+		$this->set_draft_order_id( $order->get_id() );
+
+		// phpcs:ignore WooCommerce.Commenting.CommentHooks.MissingHookComment -- Store API hook, documented in Routes\V1\Checkout.
+		do_action( 'woocommerce_store_api_checkout_update_order_meta', $order );
+
+		try {
+			$this->order_controller->validate_order_before_payment( $order );
+		} catch ( RouteException $e ) {
+			// The order stays a draft, which the payment page refuses.
+			return $this->ucp_error( 'VALIDATION_ERROR', wp_specialchars_decode( $e->getMessage(), ENT_QUOTES ), 'recoverable', 200 );
+		}
+
+		try {
+			wc_reserve_stock_for_order( $order );
+		} catch ( ReserveStockException $e ) {
+			// The hold failed on stock another checkout took since the cart was last checked. The order
+			// stays a draft, which the payment page refuses.
+			return $this->ucp_error( Utils::cart_error_code( (string) $e->getErrorCode() ), wp_specialchars_decode( $e->getMessage(), ENT_QUOTES ), 'recoverable', 200, '$.line_items' );
+		}
+
+		// The payment page only takes an order awaiting payment, which a checkout draft is not.
+		$order->set_status( OrderStatus::PENDING );
+		$order->save();
+
+		// phpcs:ignore WooCommerce.Commenting.CommentHooks.MissingHookComment -- Store API hook, documented in Routes\V1\Checkout.
+		do_action( 'woocommerce_store_api_checkout_order_processed', $order );
+
+		$state = array_merge(
+			$state,
+			array(
+				'status'       => CheckoutMapper::STATUS_REQUIRES_ESCALATION,
+				'continue_url' => $order->get_checkout_payment_url(),
+				'order_id'     => $order->get_id(),
+				'fingerprint'  => $fingerprint,
+			)
+		);
+		$this->save_checkout_state( $state );
+
+		return $this->checkout_response( $checkout_id, $this->checkout_state() ?? $state, 200, $cart );
+	}
+
+	/**
+	 * Return a checkout whose payment was already handed off, as it stands, with a warning that nothing was done.
+	 *
+	 * @param string               $checkout_id Checkout identifier.
+	 * @param array<string, mixed> $cart Cart response.
+	 * @return \WP_REST_Response
+	 */
+	private function already_handed_off_response( string $checkout_id, array $cart ): \WP_REST_Response {
+		// Read again, so an order paid while this request ran is reported as it now stands.
+		$response = $this->checkout_response( $checkout_id, (array) $this->checkout_state(), 200, $cart );
+		$data     = (array) $response->get_data();
+
+		if ( ! empty( $data['continue_url'] ) ) {
+			$data['messages'][] = array(
+				'type'         => 'warning',
+				'code'         => 'ALREADY_HANDED_OFF',
+				'content'      => __( 'Payment for this checkout session was already handed off, so it was returned unchanged. Update the checkout session to change it, or send the buyer to the payment page.', 'woocommerce' ),
+				'path'         => '$.status',
+				'content_type' => 'plain',
+			);
+			$response->set_data( $data );
+		}
+
+		return $response;
+	}
+}
diff --git a/plugins/woocommerce/src/StoreApi/RoutesController.php b/plugins/woocommerce/src/StoreApi/RoutesController.php
index c854eb4d06a..5c8f1c659c6 100644
--- a/plugins/woocommerce/src/StoreApi/RoutesController.php
+++ b/plugins/woocommerce/src/StoreApi/RoutesController.php
@@ -92,6 +92,13 @@ class RoutesController {
 				Routes\V1\Ucp\CartsById::IDENTIFIER      => Routes\V1\Ucp\CartsById::class,
 				Routes\V1\Ucp\CartsCancel::IDENTIFIER    => Routes\V1\Ucp\CartsCancel::class,
 			],
+			'ucp_checkout'  => [
+				// Gated further by Utils::is_checkout_enabled().
+				Routes\V1\Ucp\CheckoutSessions::IDENTIFIER => Routes\V1\Ucp\CheckoutSessions::class,
+				Routes\V1\Ucp\CheckoutSessionsById::IDENTIFIER => Routes\V1\Ucp\CheckoutSessionsById::class,
+				Routes\V1\Ucp\CheckoutSessionsComplete::IDENTIFIER => Routes\V1\Ucp\CheckoutSessionsComplete::class,
+				Routes\V1\Ucp\CheckoutSessionsCancel::IDENTIFIER => Routes\V1\Ucp\CheckoutSessionsCancel::class,
+			],
 		];
 	}

@@ -109,6 +116,10 @@ class RoutesController {

 		if ( Utils::is_enabled() ) {
 			$this->register_routes( 'ucp', 'wc/ucp/v1' );
+
+			if ( Utils::is_checkout_enabled() ) {
+				$this->register_routes( 'ucp_checkout', 'wc/ucp/v1' );
+			}
 		}
 	}

diff --git a/plugins/woocommerce/src/StoreApi/SchemaController.php b/plugins/woocommerce/src/StoreApi/SchemaController.php
index 27df0aeb1bb..eb9e7dae8b1 100644
--- a/plugins/woocommerce/src/StoreApi/SchemaController.php
+++ b/plugins/woocommerce/src/StoreApi/SchemaController.php
@@ -63,6 +63,7 @@ class SchemaController {
 				Schemas\V1\Ucp\UcpProductSchema::IDENTIFIER => Schemas\V1\Ucp\UcpProductSchema::class,
 				Schemas\V1\Ucp\UcpCartSchema::IDENTIFIER   => Schemas\V1\Ucp\UcpCartSchema::class,
 				Schemas\V1\Ucp\UcpCartItemSchema::IDENTIFIER => Schemas\V1\Ucp\UcpCartItemSchema::class,
+				Schemas\V1\Ucp\UcpCheckoutSchema::IDENTIFIER => Schemas\V1\Ucp\UcpCheckoutSchema::class,
 			],
 		];
 	}
diff --git a/plugins/woocommerce/src/StoreApi/Schemas/V1/Ucp/UcpCheckoutSchema.php b/plugins/woocommerce/src/StoreApi/Schemas/V1/Ucp/UcpCheckoutSchema.php
new file mode 100644
index 00000000000..200f67ddddd
--- /dev/null
+++ b/plugins/woocommerce/src/StoreApi/Schemas/V1/Ucp/UcpCheckoutSchema.php
@@ -0,0 +1,28 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\StoreApi\Schemas\V1\Ucp;
+
+/**
+ * Cart schema the UCP checkout routes read from.
+ *
+ * A UCP checkout is a promoted cart, so it reads the same raw-string cart response as
+ * {@see UcpCartSchema}; the UCP checkout mapper reshapes it.
+ *
+ * @since 11.4.0
+ */
+class UcpCheckoutSchema extends UcpCartSchema {
+	/**
+	 * The schema item name.
+	 *
+	 * @var string
+	 */
+	protected $title = 'ucp-checkout';
+
+	/**
+	 * The schema item identifier.
+	 *
+	 * @var string
+	 */
+	const IDENTIFIER = 'ucp-checkout';
+}
diff --git a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CheckoutMapper.php b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CheckoutMapper.php
new file mode 100644
index 00000000000..fac6bc9ecb7
--- /dev/null
+++ b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/CheckoutMapper.php
@@ -0,0 +1,207 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\StoreApi\Utilities\Ucp;
+
+/**
+ * Maps a Store API cart response and the checkout state kept beside it onto the UCP checkout shape.
+ *
+ * Line items, totals, expiry and cart messages come from {@see CartMapper}, so a checkout prices
+ * exactly like the cart it was promoted from. A paid checkout is handed its order in that shape.
+ */
+class CheckoutMapper {
+	const STATUS_INCOMPLETE           = 'incomplete';
+	const STATUS_READY_FOR_COMPLETE   = 'ready_for_complete';
+	const STATUS_REQUIRES_ESCALATION  = 'requires_escalation';
+	const STATUS_COMPLETE_IN_PROGRESS = 'complete_in_progress';
+	const STATUS_COMPLETED            = 'completed';
+	const STATUS_CANCELED             = 'canceled';
+
+	/**
+	 * Build the UCP checkout payload, without the `ucp` envelope.
+	 *
+	 * @param array                $cart Store API cart response, as nested arrays.
+	 * @param string               $checkout_id Checkout identifier (a Store API cart token).
+	 * @param array<string, mixed> $state Stored `status` and `continue_url`, and the `order` once paid.
+	 * @return array
+	 */
+	public function build_checkout( array $cart, string $checkout_id, array $state ): array {
+		$payload  = ( new CartMapper() )->build_cart( $cart, $checkout_id );
+		$status   = (string) ( $state['status'] ?? '' );
+		$placed   = ! empty( $state['order'] ) || self::STATUS_COMPLETE_IN_PROGRESS === $status;
+		$missing  = $placed ? array() : $this->missing_requirements( $cart );
+		$messages = array_merge( $payload['messages'] ?? array(), $missing );
+
+		if ( '' === $status ) {
+			$status = empty( $cart['items'] ) || ! empty( $cart['errors'] ) || ! empty( $missing ) ? self::STATUS_INCOMPLETE : self::STATUS_READY_FOR_COMPLETE;
+		}
+
+		$payload['status'] = $status;
+		$payload['links']  = $this->policy_links();
+
+		$buyer = $this->buyer( (array) ( $cart['billing_address'] ?? array() ) );
+		if ( ! empty( $buyer ) ) {
+			$payload['buyer'] = $buyer;
+		}
+
+		if ( self::STATUS_REQUIRES_ESCALATION === $status && ! empty( $state['continue_url'] ) ) {
+			$payload['continue_url'] = (string) $state['continue_url'];
+			$messages[]              = array(
+				'type'         => 'error',
+				'code'         => 'ESCALATION_REQUIRED',
+				'content'      => __( 'Payment must be completed by the buyer at continue_url.', 'woocommerce' ),
+				'severity'     => 'requires_buyer_review',
+				'path'         => '$',
+				'content_type' => 'plain',
+			);
+		}
+
+		if ( ! empty( $state['order'] ) ) {
+			$payload['order'] = $state['order'];
+		}
+
+		unset( $payload['messages'] );
+		if ( ! empty( $messages ) ) {
+			$payload['messages'] = $messages;
+		}
+
+		return $payload;
+	}
+
+	/**
+	 * Report what the buyer still has to supply before the checkout can complete.
+	 *
+	 * @param array $cart Store API cart response.
+	 * @return array Error messages, empty when nothing is missing.
+	 */
+	private function missing_requirements( array $cart ): array {
+		$missing = array();
+
+		if ( '' === (string) ( $cart['billing_address']['email'] ?? '' ) ) {
+			$missing['$.buyer.email'] = __( 'A buyer email is required.', 'woocommerce' );
+		}
+
+		$billing_fields = $this->missing_address_fields( (array) ( $cart['billing_address'] ?? array() ) );
+		if ( ! empty( $billing_fields ) ) {
+			/* translators: %s: comma-separated list of address field labels. */
+			$missing['$.billing_address'] = sprintf( __( 'The billing address is missing: %s.', 'woocommerce' ), implode( ', ', $billing_fields ) );
+		}
+
+		if ( ! empty( $cart['needs_shipping'] ) ) {
+			$shipping_fields = $this->missing_address_fields( (array) ( $cart['shipping_address'] ?? array() ) );
+
+			if ( ! empty( $shipping_fields ) ) {
+				/* translators: %s: comma-separated list of address field labels. */
+				$missing['$.shipping_address'] = sprintf( __( 'The shipping address is missing: %s.', 'woocommerce' ), implode( ', ', $shipping_fields ) );
+			} elseif ( ! $this->has_shipping_option( $cart ) ) {
+				$missing['$.shipping_address'] = __( 'No shipping option is available for this shipping address.', 'woocommerce' );
+			}
+		}
+
+		$messages = array();
+		foreach ( $missing as $path => $content ) {
+			$messages[] = array(
+				'type'         => 'error',
+				'code'         => 'missing',
+				'content'      => $content,
+				'severity'     => 'recoverable',
+				'path'         => $path,
+				'content_type' => 'plain',
+			);
+		}
+
+		return $messages;
+	}
+
+	/**
+	 * Labels of the fields an address lacks, by the rules the Store API checkout validates an order's addresses with.
+	 *
+	 * @param array $address Store API address.
+	 * @return array<string>
+	 */
+	private function missing_address_fields( array $address ): array {
+		$locales = WC()->countries->get_country_locale();
+		$default = is_array( $locales['default'] ?? null ) ? $locales['default'] : WC()->countries->get_default_address_fields();
+		$country = (array) ( $locales[ (string) ( $address['country'] ?? '' ) ] ?? array() );
+		$labels  = array();
+
+		foreach ( $default as $key => $field ) {
+			$field = wp_parse_args( (array) ( $country[ $key ] ?? array() ), (array) $field );
+
+			if ( wc_string_to_bool( $field['required'] ?? false ) && ! wc_string_to_bool( $field['hidden'] ?? false ) && '' === trim( (string) ( $address[ $key ] ?? '' ) ) ) {
+				$labels[] = (string) ( $field['label'] ?? $key );
+			}
+		}
+
+		return $labels;
+	}
+
+	/**
+	 * Whether every shipping package of the cart has a rate selected.
+	 *
+	 * The payment page takes no shipping choice, so an order handed off without one ships for free.
+	 *
+	 * @param array $cart Store API cart response.
+	 * @return bool
+	 */
+	private function has_shipping_option( array $cart ): bool {
+		$packages = (array) ( $cart['shipping_rates'] ?? array() );
+
+		foreach ( $packages as $package ) {
+			if ( ! in_array( true, array_column( (array) ( $package['shipping_rates'] ?? array() ), 'selected' ), true ) ) {
+				return false;
+			}
+		}
+
+		return ! empty( $packages );
+	}
+
+	/**
+	 * Build the UCP buyer from the cart billing address.
+	 *
+	 * @param array $billing Store API billing address.
+	 * @return array<string, string> Only the fields that are set.
+	 */
+	private function buyer( array $billing ): array {
+		return array_filter(
+			array(
+				'first_name'   => (string) ( $billing['first_name'] ?? '' ),
+				'last_name'    => (string) ( $billing['last_name'] ?? '' ),
+				'email'        => (string) ( $billing['email'] ?? '' ),
+				'phone_number' => (string) ( $billing['phone'] ?? '' ),
+			),
+			static function ( string $value ): bool {
+				return '' !== $value;
+			}
+		);
+	}
+
+	/**
+	 * Build the legal links the platform has to show the buyer, for the policy pages that are published.
+	 *
+	 * @return array
+	 */
+	private function policy_links(): array {
+		$pages = array(
+			'privacy_policy'   => array( (int) get_option( 'wp_page_for_privacy_policy' ), __( 'Privacy policy', 'woocommerce' ) ),
+			'terms_of_service' => array( wc_terms_and_conditions_page_id(), __( 'Terms and conditions', 'woocommerce' ) ),
+			'refund_policy'    => array( wc_get_page_id( 'refund_returns' ), __( 'Refund and returns policy', 'woocommerce' ) ),
+		);
+
+		$links = array();
+		foreach ( $pages as $type => list( $page_id, $title ) ) {
+			// Unlike wc_get_page_permalink(), never falls back to the home page or links a draft:
+			// WooCommerce creates the refund page as a draft.
+			$url = $page_id > 0 && 'publish' === get_post_status( $page_id ) ? get_permalink( $page_id ) : false;
+			if ( is_string( $url ) && '' !== $url ) {
+				$links[] = array(
+					'type'  => $type,
+					'url'   => $url,
+					'title' => $title,
+				);
+			}
+		}
+
+		return $links;
+	}
+}
diff --git a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/Utils.php b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/Utils.php
index 72418f31c89..d0d13e372ea 100644
--- a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/Utils.php
+++ b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/Utils.php
@@ -34,6 +34,11 @@ class Utils {
 	 */
 	const CAPABILITY_CART = 'dev.ucp.shopping.cart';

+	/**
+	 * Capability served by the `/checkout-sessions` routes.
+	 */
+	const CAPABILITY_CHECKOUT = 'dev.ucp.shopping.checkout';
+
 	/**
 	 * Whether the UCP routes are registered.
 	 *
@@ -43,6 +48,17 @@ class Utils {
 		return FeaturesUtil::feature_is_enabled( self::FEATURE_ID );
 	}

+	/**
+	 * Whether the checkout routes are served.
+	 *
+	 * They take guest orders only and create no account, so a store that requires one serves none of them.
+	 *
+	 * @return bool
+	 */
+	public static function is_checkout_enabled(): bool {
+		return ! WC()->checkout()->is_registration_required();
+	}
+
 	/**
 	 * Build the `ucp` envelope every UCP response carries.
 	 *
@@ -64,12 +80,12 @@ class Utils {
 	}

 	/**
-	 * Spec and schema references for every capability these routes serve, keyed by capability name.
+	 * Spec and schema references for every capability the store serves, keyed by capability name.
 	 *
 	 * @return array
 	 */
 	public static function capability_declarations(): array {
-		return array(
+		$declarations = array(
 			self::CAPABILITY_CATALOG_SEARCH => array(
 				'version' => self::VERSION,
 				'spec'    => 'https://ucp.dev/' . self::VERSION . '/specification/catalog/search',
@@ -85,7 +101,18 @@ class Utils {
 				'spec'    => 'https://ucp.dev/' . self::VERSION . '/specification/cart',
 				'schema'  => 'https://ucp.dev/' . self::VERSION . '/schemas/shopping/cart.json',
 			),
+			self::CAPABILITY_CHECKOUT       => array(
+				'version' => self::VERSION,
+				'spec'    => 'https://ucp.dev/' . self::VERSION . '/specification/checkout',
+				'schema'  => 'https://ucp.dev/' . self::VERSION . '/schemas/shopping/checkout.json',
+			),
 		);
+
+		if ( ! self::is_checkout_enabled() ) {
+			unset( $declarations[ self::CAPABILITY_CHECKOUT ] );
+		}
+
+		return $declarations;
 	}

 	/**
@@ -183,7 +210,7 @@ class Utils {
 	 * differently — retry smaller, fix the quantity, or re-read the cart — stay apart
 	 * and the rest collapse.
 	 *
-	 * @param string $code Store API error code.
+	 * @param string $code Store API or stock reservation error code.
 	 * @param string $fallback UCP code for a cart error UCP has no closer name for.
 	 * @return string One of `out_of_stock`, `not_found`, `invalid_quantity` or the fallback.
 	 */
@@ -192,6 +219,8 @@ class Utils {
 			case 'woocommerce_rest_product_out_of_stock':
 			case 'woocommerce_rest_product_partially_out_of_stock':
 			case 'woocommerce_rest_product_too_many_in_cart':
+			case 'woocommerce_product_out_of_stock':
+			case 'woocommerce_product_not_enough_stock':
 				return 'out_of_stock';
 			case 'woocommerce_rest_cart_invalid_key':
 				return 'not_found';
diff --git a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCheckout.php b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCheckout.php
new file mode 100644
index 00000000000..c6b0a5948ae
--- /dev/null
+++ b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCheckout.php
@@ -0,0 +1,1011 @@
+<?php
+/**
+ * UCP Checkout Route Tests.
+ */
+
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\Tests\Blocks\StoreApi\Routes;
+
+use Automattic\WooCommerce\Enums\OrderStatus;
+use Automattic\WooCommerce\StoreApi\Routes\V1\Ucp\AbstractCheckoutRoute;
+use Automattic\WooCommerce\StoreApi\Utilities\Ucp\Utils;
+
+/**
+ * Tests for the /wc/ucp/v1/checkout-sessions endpoints.
+ */
+class UcpCheckout extends ControllerTestCase {
+	/**
+	 * Published product IDs shared by the class.
+	 *
+	 * @var int[]
+	 */
+	private static $product_ids = array();
+
+	/**
+	 * Option behind the `ucp` feature.
+	 */
+	private const FEATURE_OPTION = 'woocommerce_feature_ucp_enabled';
+
+	/**
+	 * The WC() singletons the harness set up, restored after each test.
+	 *
+	 * @var array{session: \WC_Session|null, customer: \WC_Customer|null, cart: \WC_Cart|null}
+	 */
+	private $wc_globals_backup = array();
+
+	/**
+	 * Create immutable fixtures before route registration starts.
+	 */
+	public static function wpSetUpBeforeClass(): void {
+		self::$product_ids = array_map(
+			static function ( $product ) {
+				return $product->get_id();
+			},
+			self::create_class_fixture_products(
+				array(
+					array(
+						'name'          => 'UCP Checkout Mug',
+						'regular_price' => '19.99',
+						'price'         => '19.99',
+					),
+					array(
+						'name'          => 'UCP Checkout Poster',
+						'regular_price' => '5.00',
+						'price'         => '5.00',
+					),
+				)
+			)
+		);
+	}
+
+	/**
+	 * Delete class fixtures.
+	 */
+	public static function wpTearDownAfterClass(): void {
+		self::delete_class_fixture_products( self::$product_ids );
+	}
+
+	/**
+	 * Enable the UCP routes and start from a fresh request.
+	 */
+	protected function setUp(): void {
+		parent::setUp();
+
+		update_option( self::FEATURE_OPTION, 'yes' );
+		$this->initialize_store_api_server();
+
+		$this->wc_globals_backup = array(
+			'session'  => WC()->session,
+			'customer' => WC()->customer,
+			'cart'     => WC()->cart,
+		);
+
+		$this->simulate_new_request();
+	}
+
+	/**
+	 * Restore the WC() singletons and the token slot.
+	 */
+	protected function tearDown(): void {
+		unset( $_SERVER['HTTP_CART_TOKEN'] );
+
+		if ( WC()->session ) {
+			WC()->session->set( AbstractCheckoutRoute::CHECKOUT_SESSION_KEY, null );
+			WC()->session->set( 'store_api_draft_order', null );
+		}
+
+		WC()->session  = $this->wc_globals_backup['session'];
+		WC()->customer = $this->wc_globals_backup['customer'];
+		WC()->cart     = $this->wc_globals_backup['cart'];
+		unset( $GLOBALS['wp_actions']['woocommerce_load_cart_from_session'], $GLOBALS['wp_actions']['woocommerce_after_calculate_totals'] );
+
+		parent::tearDown();
+	}
+
+	/**
+	 * Dispatch a request with a JSON body.
+	 *
+	 * @param string $method HTTP method.
+	 * @param string $path Route path under /wc/ucp/v1.
+	 * @param array  $body Request body.
+	 * @return \WP_REST_Response
+	 */
+	private function request( string $method, string $path, array $body = array() ) {
+		$request = new \WP_REST_Request( $method, '/wc/ucp/v1' . $path );
+		$request->set_header( 'content-type', 'application/json' );
+		// A write needs a key of its own; the key itself is the UcpIdempotency suite's concern.
+		$request->set_header( 'Idempotency-Key', wp_generate_uuid4() );
+		$request->set_body( wp_json_encode( $body ) );
+
+		return rest_get_server()->dispatch( $request );
+	}
+
+	/**
+	 * Persist the current session and drop the WC() singletons, as the end of a real request does.
+	 *
+	 * @param string $cart_token Cart token the next request carries, or '' for none.
+	 */
+	private function simulate_new_request( string $cart_token = '' ): void {
+		if ( WC()->session instanceof \WC_Session_Handler ) {
+			// save_data() is a no-op without a session cookie, which this suite never sends.
+			$has_cookie = new \ReflectionProperty( WC()->session, '_has_cookie' );
+			$has_cookie->setAccessible( true );
+			$has_cookie->setValue( WC()->session, true );
+		}
+
+		if ( WC()->session ) {
+			WC()->session->save_data();
+		}
+
+		if ( '' === $cart_token ) {
+			unset( $_SERVER['HTTP_CART_TOKEN'] );
+		} else {
+			$_SERVER['HTTP_CART_TOKEN'] = $cart_token;
+		}
+
+		WC()->session  = null;
+		WC()->customer = null;
+		WC()->cart     = null;
+		unset( $GLOBALS['wp_actions']['woocommerce_load_cart_from_session'], $GLOBALS['wp_actions']['woocommerce_after_calculate_totals'] );
+	}
+
+	/**
+	 * Build a UCP line item for one of the fixture products.
+	 *
+	 * @param int $index Fixture index.
+	 * @param int $quantity Quantity.
+	 * @return array
+	 */
+	private function line_item( int $index, int $quantity ): array {
+		return array(
+			'item'     => array( 'id' => (string) self::$product_ids[ $index ] ),
+			'quantity' => $quantity,
+		);
+	}
+
+	/**
+	 * Create a checkout holding one mug, or the given line item, with everything it needs to complete.
+	 *
+	 * @param array|null $line_item Line item to check out instead of the mug.
+	 * @return array The response data.
+	 */
+	private function create_ready_checkout( ?array $line_item = null ): array {
+		$response = $this->request(
+			'POST',
+			'/checkout-sessions',
+			array(
+				'line_items'       => array( $line_item ?? $this->line_item( 0, 1 ) ),
+				'buyer'            => array(
+					'email'        => 'buyer@example.com',
+					'first_name'   => 'Ada',
+					'last_name'    => 'Buyer',
+					'phone_number' => '5550100',
+				),
+				'shipping_address' => array(
+					'street_address'   => '1 Main St',
+					'address_locality' => 'San Francisco',
+					'address_region'   => 'CA',
+					'postal_code'      => '94103',
+					'address_country'  => 'US',
+				),
+			)
+		);
+
+		$this->assertSame( 201, $response->get_status() );
+
+		return $response->get_data();
+	}
+
+	/**
+	 * @testdox The checkout routes do not exist while the UCP feature is off.
+	 */
+	public function test_routes_are_not_registered_by_default(): void {
+		delete_option( self::FEATURE_OPTION );
+		$this->initialize_store_api_server();
+
+		$this->assertSame( 404, $this->request( 'POST', '/checkout-sessions' )->get_status() );
+		$this->assertSame( 'rest_no_route', $this->request( 'GET', '/checkout-sessions/abc' )->get_data()['code'] );
+	}
+
+	/**
+	 * @testdox Creating from line items applies the lines and the buyer, and derives the status.
+	 */
+	public function test_create_from_line_items(): void {
+		$data = $this->create_ready_checkout();
+
+		$this->assertSame( array( 'dev.ucp.shopping.checkout' ), array_keys( $data['ucp']['capabilities'] ) );
+		$this->assertInstanceOf( \stdClass::class, $data['ucp']['payment_handlers'], 'A checkout envelope must carry the payment_handlers registry.' );
+		$this->assertSame( 'ready_for_complete', $data['status'] );
+		$this->assertSame( 'buyer@example.com', $data['buyer']['email'] );
+		$this->assertSame( 1999, $data['line_items'][0]['item']['price'] );
+		$this->assertArrayNotHasKey( 'continue_url', $data );
+
+		$missing = $this->request( 'POST', '/checkout-sessions', array() );
+		$this->assertSame( 400, $missing->get_status(), 'line_items is required without a cart_id.' );
+	}
+
+	/**
+	 * @testdox Creating from a cart keeps the cart id and contents; a checkout without a buyer email is incomplete.
+	 */
+	public function test_create_from_cart_id(): void {
+		$cart = $this->request( 'POST', '/carts', array( 'line_items' => array( $this->line_item( 1, 3 ) ) ) )->get_data();
+		$this->simulate_new_request();
+
+		$response = $this->request( 'POST', '/checkout-sessions', array( 'cart_id' => $cart['id'] ) );
+		$data     = $response->get_data();
+
+		$this->assertSame( 201, $response->get_status() );
+		$this->assertSame( $cart['id'], $data['id'] );
+		$this->assertSame( 3, $data['line_items'][0]['quantity'] );
+		$this->assertSame( 'incomplete', $data['status'] );
+		$this->assertContains( '$.buyer.email', array_column( $data['messages'], 'path' ) );
+	}
+
+	/**
+	 * @testdox An id that never named a checkout is a 404, from the path or from cart_id.
+	 */
+	public function test_unknown_id_is_not_found(): void {
+		$get = $this->request( 'GET', '/checkout-sessions/not-a-token' );
+		$this->assertSame( 404, $get->get_status() );
+		$this->assertSame( 'not_found', $get->get_data()['messages'][0]['code'] );
+
+		$this->assertSame( 404, $this->request( 'POST', '/checkout-sessions', array( 'cart_id' => 'not-a-token' ) )->get_status() );
+
+		// A real cart that was never promoted is not a checkout.
+		$cart = $this->request( 'POST', '/carts', array( 'line_items' => array( $this->line_item( 0, 1 ) ) ) )->get_data();
+		$this->assertSame( 404, $this->request( 'GET', '/checkout-sessions/' . $cart['id'] )->get_status() );
+	}
+
+	/**
+	 * @testdox An update replaces the lines and cancels an order already handed off for the old ones.
+	 */
+	public function test_update_replaces_line_items(): void {
+		$created = $this->create_ready_checkout();
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		$handed_off = (int) WC()->session->get( 'store_api_draft_order' );
+
+		$data = $this->request( 'PUT', '/checkout-sessions/' . $created['id'], array( 'line_items' => array( $this->line_item( 1, 2 ) ) ) )->get_data();
+
+		$this->assertCount( 1, $data['line_items'] );
+		$this->assertSame( (string) self::$product_ids[1], $data['line_items'][0]['item']['id'] );
+		$this->assertSame( 2, $data['line_items'][0]['quantity'] );
+		$this->assertSame( 'ready_for_complete', $data['status'] );
+		$this->assertTrue( wc_get_order( $handed_off )->has_status( OrderStatus::CANCELLED ), 'An order for the old lines must no longer be payable.' );
+		$this->assertNotSame( $handed_off, (int) WC()->session->get( 'store_api_draft_order' ) );
+
+		// An order cancelled behind the checkout's back, as the hold-stock timer does, drops the hand-off.
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) )->update_status( OrderStatus::CANCELLED );
+		$this->assertSame( 'ready_for_complete', $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data()['status'] );
+	}
+
+	/**
+	 * @testdox An update that changes nothing keeps the hand-off, and one refused after changing the lines drops it.
+	 */
+	public function test_update_drops_the_hand_off_only_for_a_change(): void {
+		$created   = $this->create_ready_checkout();
+		$path      = '/checkout-sessions/' . $created['id'];
+		$completed = $this->request( 'POST', $path . '/complete' )->get_data();
+		$order_id  = (int) WC()->session->get( 'store_api_draft_order' );
+
+		foreach ( array( array(), array( 'line_items' => array( $this->line_item( 0, 1 ) ) ) ) as $body ) {
+			$this->simulate_new_request( $created['id'] );
+			$same = $this->request( 'PUT', $path, $body )->get_data();
+			$this->assertSame( $completed['continue_url'], $same['continue_url'] ?? null );
+			$this->assertTrue( wc_get_order( $order_id )->has_status( OrderStatus::PENDING ) );
+		}
+
+		$refused = $this->request(
+			'PUT',
+			$path,
+			array(
+				'line_items'       => array( $this->line_item( 1, 2 ) ),
+				'shipping_address' => array( 'address_country' => 'ZZ' ),
+			)
+		);
+
+		$this->assertSame( 400, $refused->get_status() );
+		$this->assertTrue( wc_get_order( $order_id )->has_status( OrderStatus::CANCELLED ), 'The lines changed, so the order for the old ones must not stay payable.' );
+		$this->assertArrayNotHasKey( 'continue_url', $this->request( 'GET', $path )->get_data() );
+
+		// A cart changed through the Store API after a hand-off makes it stale before the update arrives.
+		$this->request( 'POST', $path . '/complete' );
+		$stale = (int) WC()->session->get( 'store_api_draft_order' );
+		WC()->cart->set_quantity( (string) array_key_first( WC()->cart->get_cart() ), 3 );
+
+		$this->assertArrayNotHasKey( 'continue_url', $this->request( 'PUT', $path, array() )->get_data() );
+		$this->assertTrue( wc_get_order( $stale )->has_status( OrderStatus::CANCELLED ) );
+	}
+
+	/**
+	 * @testdox An order paid, or put on hold, while an update is under way stays the checkout's order.
+	 * @testWith ["processing", "completed"]
+	 *           ["on-hold", "complete_in_progress"]
+	 *
+	 * @param string $order_status Status the order moves to mid-request.
+	 * @param string $expected     Checkout status afterwards.
+	 */
+	public function test_update_keeps_an_order_paid_mid_request( string $order_status, string $expected ): void {
+		$created = $this->create_ready_checkout();
+		$path    = '/checkout-sessions/' . $created['id'];
+		$this->request( 'POST', $path . '/complete' );
+		$order_id = (int) WC()->session->get( 'store_api_draft_order' );
+
+		$pay = static function () use ( $order_id, $order_status ) {
+			wc_get_order( $order_id )->update_status( $order_status );
+		};
+		add_action( 'woocommerce_add_to_cart', $pay );
+		$updated = $this->request( 'PUT', $path, array( 'line_items' => array( $this->line_item( 1, 1 ) ) ) )->get_data();
+		remove_action( 'woocommerce_add_to_cart', $pay );
+		$this->assertSame( $expected, $updated['status'] );
+		$this->assertSame( (string) self::$product_ids[0], $updated['line_items'][0]['item']['id'], 'A paid checkout lists what was paid for, not the late change.' );
+
+		$this->assertSame( $expected, $this->request( 'GET', $path )->get_data()['status'] );
+		$this->assertSame( $order_id, (int) WC()->session->get( 'ucp_checkout' )['order_id'] );
+	}
+
+	/**
+	 * @testdox An order that could not be cancelled stays the checkout's order, so no second one is handed off beside it.
+	 */
+	public function test_failed_cancellation_keeps_the_hand_off(): void {
+		$created = $this->create_ready_checkout();
+		$path    = '/checkout-sessions/' . $created['id'];
+		$this->request( 'POST', $path . '/complete' );
+		$order_id = (int) WC()->session->get( 'store_api_draft_order' );
+		WC()->cart->set_quantity( (string) array_key_first( WC()->cart->get_cart() ), 2 );
+
+		$fail = static function ( $order ) {
+			if ( $order->has_status( OrderStatus::CANCELLED ) ) {
+				throw new \Exception( 'Save failed.' );
+			}
+		};
+		add_action( 'woocommerce_before_order_object_save', $fail );
+		$statuses = array(
+			$this->request( 'POST', $path . '/complete' )->get_status(),
+			$this->request( 'POST', $path . '/cancel' )->get_status(),
+		);
+		remove_action( 'woocommerce_before_order_object_save', $fail );
+
+		$this->assertSame( array( 500, 500 ), $statuses );
+		$this->assertTrue( wc_get_order( $order_id )->has_status( OrderStatus::PENDING ) );
+		$this->assertSame( $order_id, (int) WC()->session->get( 'ucp_checkout' )['order_id'] );
+		$this->assertCount(
+			1,
+			wc_get_orders(
+				array(
+					'status' => 'any',
+					'return' => 'ids',
+					'limit'  => -1,
+				)
+			)
+		);
+
+		$this->assertArrayHasKey( 'continue_url', $this->request( 'POST', $path . '/complete' )->get_data() );
+		$this->assertTrue( wc_get_order( $order_id )->has_status( OrderStatus::CANCELLED ), 'The retry cancels the order the failed attempt left payable.' );
+	}
+
+	/**
+	 * @testdox Completing again returns the hand-off unchanged with a warning, and no request that leaves it standing saves the order the buyer may be paying.
+	 */
+	public function test_complete_again_returns_the_hand_off_unchanged(): void {
+		$created = $this->create_ready_checkout();
+		$path    = '/checkout-sessions/' . $created['id'];
+		$first   = $this->request( 'POST', $path . '/complete' )->get_data();
+		$order   = wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) );
+		$order->update_status( OrderStatus::FAILED );
+		$processed = did_action( 'woocommerce_store_api_checkout_order_processed' );
+		$saves     = 0;
+		$count     = static function ( $saved ) use ( &$saves, $order ) {
+			$saves += (int) ( $saved->get_id() === $order->get_id() );
+		};
+
+		add_action( 'woocommerce_before_order_object_save', $count );
+		$second = $this->request( 'POST', $path . '/complete' )->get_data();
+		$this->request( 'PUT', $path, array() );
+		remove_action( 'woocommerce_before_order_object_save', $count );
+
+		$this->assertSame( 0, $saves, 'Neither a repeated complete nor an update that changes nothing saves the order.' );
+		$this->assertSame( $first['continue_url'], $second['continue_url'] );
+		$this->assertContains( 'ALREADY_HANDED_OFF', array_column( $second['messages'], 'code' ) );
+		$this->assertTrue( wc_get_order( $order->get_id() )->has_status( OrderStatus::FAILED ), 'A failed order the buyer may be retrying is not reset.' );
+		$this->assertSame( $processed, did_action( 'woocommerce_store_api_checkout_order_processed' ) );
+	}
+
+	/**
+	 * @testdox Completing a changed cart makes no second order when the first is paid while the request is under way.
+	 */
+	public function test_complete_stops_for_an_order_paid_mid_request(): void {
+		$created = $this->create_ready_checkout();
+		$path    = '/checkout-sessions/' . $created['id'];
+		$this->request( 'POST', $path . '/complete' );
+		$order_id = (int) WC()->session->get( 'store_api_draft_order' );
+		WC()->cart->set_quantity( (string) array_key_first( WC()->cart->get_cart() ), 2 );
+
+		// Fires while the cart response is built, after the checkout was found open.
+		$pay = static function ( $ids ) use ( $order_id ) {
+			wc_get_order( $order_id )->update_status( OrderStatus::PROCESSING );
+
+			return $ids;
+		};
+		add_filter( 'woocommerce_cart_crosssell_ids', $pay );
+		$response = $this->request( 'POST', $path . '/complete' );
+		remove_filter( 'woocommerce_cart_crosssell_ids', $pay );
+
+		$this->assertSame( 409, $response->get_status() );
+		$this->assertSame( $order_id, (int) WC()->session->get( 'ucp_checkout' )['order_id'] );
+		$this->assertSame( (string) $order_id, $this->request( 'GET', $path )->get_data()['order']['id'] );
+	}
+
+	/**
+	 * @testdox A paid checkout reads from its order, whatever happens to the product afterwards.
+	 */
+	public function test_completed_checkout_reads_from_the_order(): void {
+		$product = \WC_Helper_Product::create_simple_product(
+			true,
+			array(
+				'manage_stock'   => true,
+				'stock_quantity' => 1,
+				'regular_price'  => 10,
+				'price'          => 10,
+			)
+		);
+		$created = $this->create_ready_checkout(
+			array(
+				'item'     => array( 'id' => (string) $product->get_id() ),
+				'quantity' => 1,
+			)
+		);
+		$path    = '/checkout-sessions/' . $created['id'];
+		$this->request( 'POST', $path . '/complete' );
+
+		// Paying takes the last unit; the price is raised afterwards.
+		wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) )->payment_complete();
+		$product = wc_get_product( $product->get_id() );
+		$product->set_regular_price( '25' );
+		$product->save();
+		$this->simulate_new_request( $created['id'] );
+
+		$paid = $this->request( 'GET', $path )->get_data();
+
+		$this->assertSame( 'completed', $paid['status'] );
+		$this->assertSame( $created['totals'], $paid['totals'] );
+		$this->assertSame( $created['line_items'][0]['item'], $paid['line_items'][0]['item'] );
+		$this->assertSame( $created['line_items'][0]['totals'], $paid['line_items'][0]['totals'] );
+		$this->assertArrayNotHasKey( 'messages', $paid, 'The buyer\'s own purchase must not read as a stock problem.' );
+	}
+
+	/**
+	 * @testdox A checkout paid once stays completed when its order is later refunded or cancelled, so it cannot be completed again.
+	 * @testWith ["processing", "cancelled"]
+	 *           ["on-hold", "refunded"]
+	 *
+	 * @param string $paid_status The status the payment left the order in.
+	 * @param string $later_status The status the store moved it to afterwards.
+	 */
+	public function test_paid_checkout_stays_completed_after_a_refund_or_cancellation( string $paid_status, string $later_status ): void {
+		$created = $this->create_ready_checkout();
+		$path    = '/checkout-sessions/' . $created['id'];
+		$this->request( 'POST', $path . '/complete' );
+		$order = wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) );
+		$order->update_status( $paid_status );
+		$order->update_status( $later_status );
+		$this->simulate_new_request( $created['id'] );
+
+		$this->assertSame( 'completed', $this->request( 'GET', $path )->get_data()['status'] );
+		$this->assertSame( 409, $this->request( 'POST', $path . '/complete' )->get_status() );
+	}
+
+	/**
+	 * @testdox A promoted cart is read but not written through the cart routes while its checkout is live, and is no longer a cart afterwards.
+	 */
+	public function test_cart_writes_are_refused_once_promoted(): void {
+		$created = $this->create_ready_checkout();
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		$order_id = (int) WC()->session->get( 'store_api_draft_order' );
+
+		$read = $this->request( 'GET', '/carts/' . $created['id'] );
+		$this->assertSame( 200, $read->get_status() );
+		$this->assertSame( $created['line_items'], $read->get_data()['line_items'] );
+
+		foreach ( array( array( 'PUT', '', array( 'line_items' => array( $this->line_item( 1, 2 ) ) ) ), array( 'POST', '/cancel', array() ) ) as list( $method, $path, $body ) ) {
+			$response = $this->request( $method, '/carts/' . $created['id'] . $path, $body );
+			$this->assertSame( 409, $response->get_status(), $method . $path );
+			$this->assertContains( 'CONFLICT', array_column( $response->get_data()['messages'], 'code' ), $method . $path );
+		}
+
+		$this->assertTrue( wc_get_order( $order_id )->has_status( OrderStatus::PENDING ) );
+		$this->assertSame( 'requires_escalation', $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data()['status'] );
+
+		// Once the checkout ends the id is no longer a cart, while the checkout keeps reading back with its lines.
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/cancel' );
+		$gone = $this->request( 'GET', '/carts/' . $created['id'] );
+		$this->assertSame( 200, $gone->get_status() );
+		$this->assertSame( 'error', $gone->get_data()['ucp']['status'] );
+		$this->assertSame( 'not_found', $gone->get_data()['messages'][0]['code'] );
+		$canceled = $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data();
+		$this->assertSame( 'canceled', $canceled['status'] );
+		$this->assertSame( $created['line_items'], $canceled['line_items'] );
+	}
+
+	/**
+	 * @testdox A payment awaiting the store's confirmation locks the checkout against completing again, changing and canceling.
+	 */
+	public function test_payment_awaiting_confirmation_locks_the_checkout(): void {
+		$created = $this->create_ready_checkout();
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		$order = wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) );
+		$order->update_status( OrderStatus::ON_HOLD );
+
+		$writes = array(
+			array( 'POST', '/complete', array() ),
+			array( 'PUT', '', array( 'buyer' => array( 'email' => 'other@example.com' ) ) ),
+			array( 'POST', '/cancel', array() ),
+		);
+
+		foreach ( $writes as list( $method, $path, $body ) ) {
+			$response = $this->request( $method, '/checkout-sessions/' . $created['id'] . $path, $body );
+			$this->assertSame( 409, $response->get_status(), $method . $path );
+			$this->assertContains( 'CONFLICT', array_column( $response->get_data()['messages'], 'code' ), $method . $path );
+		}
+
+		$this->assertTrue( wc_get_order( $order->get_id() )->has_status( OrderStatus::ON_HOLD ) );
+		$this->assertCount(
+			1,
+			wc_get_orders(
+				array(
+					'status' => 'any',
+					'return' => 'ids',
+					'limit'  => -1,
+				)
+			),
+			'No second order may be made for a payment already on its way.'
+		);
+		$read = $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data();
+		$this->assertSame( 'complete_in_progress', $read['status'], 'A payment already made must not read as one still to make.' );
+		$this->assertArrayNotHasKey( 'continue_url', $read );
+		$this->assertNotContains( 'error', array_column( $read['messages'] ?? array(), 'type' ) );
+
+		$order->update_status( OrderStatus::PROCESSING );
+		$this->assertSame( 'completed', $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data()['status'] );
+	}
+
+	/**
+	 * @testdox A failed payment attempt the buyer could retry is cancelled when the checkout is canceled or changed.
+	 * @dataProvider provider_requests_that_drop_the_hand_off
+	 *
+	 * @param string $method Request method.
+	 * @param string $path   Route path after the checkout id.
+	 * @param array  $body   Request body.
+	 */
+	public function test_failed_order_is_cancelled_with_the_hand_off( string $method, string $path, array $body ): void {
+		$created = $this->create_ready_checkout();
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		$order = wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) );
+		$order->update_status( OrderStatus::FAILED );
+		$this->assertTrue( $order->needs_payment(), 'The payment page retries a failed order.' );
+
+		$this->assertSame( 200, $this->request( $method, '/checkout-sessions/' . $created['id'] . $path, $body )->get_status() );
+		$this->assertTrue( wc_get_order( $order->get_id() )->has_status( OrderStatus::CANCELLED ) );
+	}
+
+	/**
+	 * Requests that end the hand-off of an order.
+	 *
+	 * @return array<string, array{string, string, array}>
+	 */
+	public function provider_requests_that_drop_the_hand_off(): array {
+		return array(
+			'cancel' => array( 'POST', '/cancel', array() ),
+			'update' => array( 'PUT', '', array( 'buyer' => array( 'email' => 'other@example.com' ) ) ),
+		);
+	}
+
+	/**
+	 * @testdox Complete hands off a pending order's payment page, which a later request reads back, and paying it completes the checkout.
+	 */
+	public function test_complete_escalates_and_persists(): void {
+		$created = $this->create_ready_checkout();
+
+		$response = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete', array( 'payment' => array( 'instruments' => array() ) ) );
+		$data     = $response->get_data();
+
+		$this->assertSame( 200, $response->get_status() );
+		$this->assertSame( 'requires_escalation', $data['status'] );
+		$this->assertContains( 'ESCALATION_REQUIRED', array_column( $data['messages'], 'code' ) );
+
+		$order = wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) );
+		$this->assertInstanceOf( \WC_Order::class, $order );
+		$this->assertTrue( $order->has_status( OrderStatus::PENDING ), 'The payment page only accepts an order awaiting payment.' );
+		$this->assertSame( $order->get_checkout_payment_url(), $data['continue_url'] );
+
+		$this->simulate_new_request( $created['id'] );
+		$read_back = $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data();
+		$this->assertSame( 'requires_escalation', $read_back['status'] );
+		$this->assertSame( $data['continue_url'], $read_back['continue_url'] );
+
+		$order->set_status( OrderStatus::PROCESSING );
+		$order->save();
+
+		$paid = $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data();
+		$this->assertSame( 'completed', $paid['status'] );
+		$this->assertSame( (string) $order->get_id(), $paid['order']['id'] );
+		$this->assertSame( 409, $this->request( 'PUT', '/checkout-sessions/' . $created['id'], array() )->get_status() );
+	}
+
+	/**
+	 * @testdox Complete refuses a checkout with nothing to pay, which the payment page would not take, and makes no order.
+	 */
+	public function test_complete_refuses_a_free_checkout(): void {
+		$product = \WC_Helper_Product::create_simple_product(
+			true,
+			array(
+				'regular_price' => 0,
+				'price'         => 0,
+			)
+		);
+		$created = $this->create_ready_checkout(
+			array(
+				'item'     => array( 'id' => (string) $product->get_id() ),
+				'quantity' => 1,
+			)
+		);
+
+		$data = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+
+		$this->assertSame( 'payment_not_required', $data['messages'][0]['code'] );
+		$this->assertEmpty( WC()->session->get( 'store_api_draft_order' ) );
+	}
+
+	/**
+	 * @testdox A store that requires an account to check out serves no checkout route and declares no checkout capability.
+	 */
+	public function test_checkout_is_unavailable_when_an_account_is_required(): void {
+		add_filter( 'woocommerce_checkout_registration_required', '__return_true' );
+		$this->initialize_store_api_server();
+		$response     = $this->request( 'POST', '/checkout-sessions', array( 'line_items' => array( $this->line_item( 0, 1 ) ) ) );
+		$capabilities = array_keys( Utils::capability_declarations() );
+		remove_filter( 'woocommerce_checkout_registration_required', '__return_true' );
+
+		$this->assertSame( 'rest_no_route', $response->get_data()['code'] );
+		$this->assertNotContains( Utils::CAPABILITY_CHECKOUT, $capabilities );
+		$this->assertContains( Utils::CAPABILITY_CART, $capabilities );
+	}
+
+	/**
+	 * @testdox Completing again after the cart changed outside the checkout routes cancels the order first handed off.
+	 */
+	public function test_complete_cancels_the_order_a_changed_cart_left_behind(): void {
+		$created = $this->create_ready_checkout();
+		$first   = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+		$stale   = (int) WC()->session->get( 'store_api_draft_order' );
+
+		// As POST /wc/store/v1/cart/update-item does with the checkout id as its Cart-Token.
+		$cart = WC()->cart;
+		$cart->set_quantity( (string) array_key_first( $cart->get_cart() ), 2 );
+
+		// Until then a read shows the changed cart without the payment URL of the order it no longer matches.
+		$read = $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data();
+		$this->assertArrayNotHasKey( 'continue_url', $read );
+		$this->assertSame( 'ready_for_complete', $read['status'] );
+		$this->assertSame( 2, $read['line_items'][0]['quantity'] );
+
+		$second = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+
+		$this->assertSame( 'requires_escalation', $second['status'] );
+		$this->assertNotSame( $first['continue_url'], $second['continue_url'] );
+		$this->assertTrue( wc_get_order( $stale )->has_status( OrderStatus::CANCELLED ), 'The order for the old cart must no longer be payable.' );
+		$this->assertTrue( wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) )->has_status( OrderStatus::PENDING ) );
+	}
+
+	/**
+	 * @testdox A shipping address no shipping method serves leaves the checkout incomplete, so no order is handed off.
+	 */
+	public function test_address_without_a_shipping_option_is_not_ready(): void {
+		$zone = new \WC_Shipping_Zone();
+		$zone->set_zone_name( 'UCP US only' );
+		$zone->add_location( 'US', 'country' );
+		$zone->save();
+		$zone->add_shipping_method( 'flat_rate' );
+
+		try {
+			$created = $this->create_ready_checkout();
+			$this->assertSame( 'ready_for_complete', $created['status'], 'A served address picks up the default rate.' );
+
+			$unserved = array(
+				'street_address'   => '1 Front St',
+				'address_locality' => 'Toronto',
+				'address_region'   => 'ON',
+				'postal_code'      => 'M5V 2T6',
+				'address_country'  => 'CA',
+			);
+			$updated  = $this->request( 'PUT', '/checkout-sessions/' . $created['id'], array( 'shipping_address' => $unserved ) )->get_data();
+
+			$this->assertSame( 'incomplete', $updated['status'] );
+			$this->assertContains( '$.shipping_address', array_column( $updated['messages'], 'path' ) );
+
+			$completed = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+			$this->assertSame( 'incomplete', $completed['status'] );
+			$this->assertArrayNotHasKey( 'continue_url', $completed );
+		} finally {
+			$zone->delete();
+		}
+	}
+
+	/**
+	 * @testdox Billing follows the shipping address, and a checkout stays incomplete until the buyer's name and phone are known.
+	 */
+	public function test_billing_follows_shipping_and_is_required(): void {
+		$body    = array(
+			'line_items'       => array( $this->line_item( 0, 1 ) ),
+			'buyer'            => array( 'email' => 'buyer@example.com' ),
+			'shipping_address' => array(
+				'street_address'   => '1 Main St',
+				'address_locality' => 'San Francisco',
+				'address_region'   => 'CA',
+				'postal_code'      => '94103',
+				'address_country'  => 'US',
+			),
+		);
+		$created = $this->request( 'POST', '/checkout-sessions', $body )->get_data();
+
+		$this->assertSame( 'incomplete', $created['status'] );
+		$this->assertContains( '$.billing_address', array_column( $created['messages'], 'path' ) );
+
+		$buyer   = array(
+			'first_name'   => 'Ada',
+			'last_name'    => 'Buyer',
+			'phone_number' => '5550100',
+		);
+		$updated = $this->request( 'PUT', '/checkout-sessions/' . $created['id'], array( 'buyer' => $buyer ) )->get_data();
+		$this->assertSame( 'ready_for_complete', $updated['status'] );
+
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		$order = wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) );
+		$this->assertSame( '1 Main St', $order->get_billing_address_1() );
+		$this->assertSame( 'Ada', $order->get_shipping_first_name() );
+	}
+
+	/**
+	 * @testdox Complete refuses an order the Store API checkout validation refuses, and leaves it unpayable.
+	 */
+	public function test_complete_runs_checkout_validation(): void {
+		$refuse = static function ( $order, $errors ) {
+			$errors->add( 'refused', 'Refused by an extension.' );
+		};
+		add_action( 'woocommerce_checkout_validate_order_before_payment', $refuse, 10, 2 );
+
+		$created  = $this->create_ready_checkout();
+		$response = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+		remove_action( 'woocommerce_checkout_validate_order_before_payment', $refuse, 10 );
+
+		$this->assertSame( 'VALIDATION_ERROR', $response['messages'][0]['code'] );
+		$this->assertSame( 'Refused by an extension.', $response['messages'][0]['content'] );
+		$this->assertTrue( wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) )->has_status( OrderStatus::CHECKOUT_DRAFT ), 'The order must stay a draft, which the payment page refuses.' );
+	}
+
+	/**
+	 * @testdox Complete fires the Store API checkout actions, and reports an order a callback paid as completed.
+	 */
+	public function test_complete_fires_the_store_api_checkout_actions(): void {
+		$seen = array();
+		$meta = static function ( $order ) use ( &$seen ) {
+			$seen[] = 'meta:' . $order->get_status();
+		};
+		$pay  = static function ( $order ) use ( &$seen ) {
+			$seen[] = 'processed:' . $order->get_status();
+			$order->payment_complete();
+		};
+		add_action( 'woocommerce_store_api_checkout_update_order_meta', $meta );
+		add_action( 'woocommerce_store_api_checkout_order_processed', $pay );
+
+		$created = $this->create_ready_checkout();
+		$data    = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+		remove_action( 'woocommerce_store_api_checkout_update_order_meta', $meta );
+		remove_action( 'woocommerce_store_api_checkout_order_processed', $pay );
+
+		$this->assertSame( array( 'meta:checkout-draft', 'processed:pending' ), $seen );
+		$this->assertSame( 'completed', $data['status'] );
+		$this->assertArrayNotHasKey( 'continue_url', $data );
+	}
+
+	/**
+	 * @testdox A cart changed by a checkout action no longer matches the order handed off, so the next update drops it.
+	 */
+	public function test_cart_changed_by_a_checkout_action_makes_the_hand_off_stale(): void {
+		$change = static function () {
+			WC()->cart->set_quantity( (string) array_key_first( WC()->cart->get_cart() ), 2 );
+		};
+		add_action( 'woocommerce_store_api_checkout_order_processed', $change );
+		$created = $this->create_ready_checkout();
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		remove_action( 'woocommerce_store_api_checkout_order_processed', $change );
+		$order_id = (int) WC()->session->get( 'ucp_checkout' )['order_id'];
+
+		$this->assertArrayNotHasKey( 'continue_url', $this->request( 'PUT', '/checkout-sessions/' . $created['id'], array() )->get_data() );
+		$this->assertTrue( wc_get_order( $order_id )->has_status( OrderStatus::CANCELLED ) );
+	}
+
+	/**
+	 * @testdox Creating again from a cart that already is a checkout returns that checkout and changes nothing.
+	 */
+	public function test_create_from_an_existing_checkout_returns_it_unchanged(): void {
+		$created   = $this->create_ready_checkout();
+		$completed = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+
+		$body     = array(
+			'cart_id'          => $created['id'],
+			'shipping_address' => array( 'address_locality' => 'Oakland' ),
+		);
+		$response = $this->request( 'POST', '/checkout-sessions', $body );
+
+		$data = $response->get_data();
+
+		$this->assertSame( 200, $response->get_status() );
+		$this->assertSame( $completed['continue_url'], $data['continue_url'] );
+		$this->assertSame( 'San Francisco', WC()->customer->get_shipping_city() );
+		$this->assertContains( 'FIELDS_IGNORED', array_column( $data['messages'], 'code' ), 'The agent must learn its address was not applied.' );
+
+		$plain = $this->request( 'POST', '/checkout-sessions', array( 'cart_id' => $created['id'] ) )->get_data();
+		$this->assertEquals( $completed, $plain, 'A bare repeat has nothing ignored to warn about.' );
+	}
+
+	/**
+	 * @testdox Complete holds the order's stock, as the payment page trusts a pending order to have.
+	 */
+	public function test_complete_holds_stock(): void {
+		$product = \WC_Helper_Product::create_simple_product(
+			true,
+			array(
+				'manage_stock'   => true,
+				'stock_quantity' => 3,
+			)
+		);
+		$created = $this->create_ready_checkout(
+			array(
+				'item'     => array( 'id' => (string) $product->get_id() ),
+				'quantity' => 2,
+			)
+		);
+
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+
+		$this->assertSame( 2, wc_get_held_stock_quantity( $product ) );
+	}
+
+	/**
+	 * @testdox Complete refuses a checkout whose stock another order took first and hands over no payable order.
+	 */
+	public function test_complete_refuses_stock_it_cannot_hold(): void {
+		$product = \WC_Helper_Product::create_simple_product(
+			true,
+			array(
+				'manage_stock'   => true,
+				'stock_quantity' => 1,
+			)
+		);
+		$created = $this->create_ready_checkout(
+			array(
+				'item'     => array( 'id' => (string) $product->get_id() ),
+				'quantity' => 1,
+			)
+		);
+
+		// A rival checkout takes the last unit after this cart was checked and before its order is held.
+		$rival = wc_create_order();
+		$rival->add_product( $product, 1 );
+		$rival->save();
+		$hold_rival = static function () use ( $rival, &$hold_rival ) {
+			remove_action( 'woocommerce_order_before_calculate_totals', $hold_rival );
+			wc_reserve_stock_for_order( $rival );
+		};
+		add_action( 'woocommerce_order_before_calculate_totals', $hold_rival );
+		$response = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+
+		$this->assertSame( 200, $response->get_status() );
+		$this->assertSame( 'out_of_stock', $response->get_data()['messages'][0]['code'] );
+
+		$order = wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) );
+		$this->assertTrue( $order->has_status( OrderStatus::CHECKOUT_DRAFT ), 'A refused hold must not leave a payable order.' );
+		$this->assertSame( 0, wc_get_held_stock_quantity( $product, $rival->get_id() ) );
+	}
+
+	/**
+	 * @testdox Completing again cancels the order already handed off when its stock can no longer be held.
+	 */
+	public function test_complete_again_cancels_an_order_it_cannot_hold_stock_for(): void {
+		$product = \WC_Helper_Product::create_simple_product(
+			true,
+			array(
+				'manage_stock'   => true,
+				'stock_quantity' => 1,
+			)
+		);
+		$created = $this->create_ready_checkout(
+			array(
+				'item'     => array( 'id' => (string) $product->get_id() ),
+				'quantity' => 1,
+			)
+		);
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		$order = wc_get_order( (int) WC()->session->get( 'store_api_draft_order' ) );
+
+		// The hold lapses and a rival takes the unit.
+		wc_release_stock_for_order( $order );
+		$rival = wc_create_order();
+		$rival->add_product( $product, 1 );
+		$rival->save();
+		wc_reserve_stock_for_order( $rival );
+		$response = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+
+		$this->assertContains( 'out_of_stock', array_column( $response->get_data()['messages'], 'code' ) );
+		$this->assertTrue( wc_get_order( $order->get_id() )->has_status( OrderStatus::CANCELLED ) );
+		$this->assertArrayNotHasKey( 'continue_url', $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data() );
+	}
+
+	/**
+	 * @testdox Stock that ran short after the cart was built is reported, not absorbed by lowering the quantity.
+	 */
+	public function test_stock_shortfall_is_reported_not_absorbed(): void {
+		$product = \WC_Helper_Product::create_simple_product(
+			true,
+			array(
+				'manage_stock'   => true,
+				'stock_quantity' => 3,
+			)
+		);
+		$created = $this->create_ready_checkout(
+			array(
+				'item'     => array( 'id' => (string) $product->get_id() ),
+				'quantity' => 2,
+			)
+		);
+
+		wc_update_product_stock( $product, 1 );
+		$this->simulate_new_request( $created['id'] );
+
+		$read = $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data();
+		$this->assertSame( 2, $read['line_items'][0]['quantity'], 'The agent asked for 2 and must still see 2.' );
+		$this->assertSame( 'incomplete', $read['status'] );
+		$this->assertContains( 'out_of_stock', array_column( $read['messages'], 'code' ) );
+
+		$completed = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+		$this->assertSame( 'incomplete', $completed['status'] );
+		$this->assertArrayNotHasKey( 'continue_url', $completed );
+		$this->assertEmpty( WC()->session->get( 'store_api_draft_order' ) );
+	}
+
+	/**
+	 * @testdox Complete leaves an incomplete checkout as it is and creates no order.
+	 */
+	public function test_complete_refuses_an_incomplete_checkout(): void {
+		$created = $this->request( 'POST', '/checkout-sessions', array( 'line_items' => array( $this->line_item( 0, 1 ) ) ) )->get_data();
+
+		$data = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' )->get_data();
+
+		$this->assertSame( 'incomplete', $data['status'] );
+		$this->assertArrayNotHasKey( 'continue_url', $data );
+		$this->assertEmpty( WC()->session->get( 'store_api_draft_order' ) );
+	}
+
+	/**
+	 * @testdox A canceled checkout keeps answering as canceled and refuses further changes.
+	 */
+	public function test_cancel_then_conflict(): void {
+		$created = $this->create_ready_checkout();
+		$this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/complete' );
+		$order_id = (int) WC()->session->get( 'store_api_draft_order' );
+
+		$cancel = $this->request( 'POST', '/checkout-sessions/' . $created['id'] . '/cancel' );
+		$this->assertSame( 200, $cancel->get_status() );
+		$this->assertSame( 'canceled', $cancel->get_data()['status'] );
+		$this->assertTrue( wc_get_order( $order_id )->has_status( OrderStatus::CANCELLED ), 'The handed-off order must no longer be payable.' );
+
+		$this->assertSame( 'canceled', $this->request( 'GET', '/checkout-sessions/' . $created['id'] )->get_data()['status'] );
+
+		foreach ( array( '/cancel', '/complete' ) as $action ) {
+			$this->assertSame( 409, $this->request( 'POST', '/checkout-sessions/' . $created['id'] . $action )->get_status(), $action );
+		}
+		$this->assertSame( 409, $this->request( 'POST', '/checkout-sessions', array( 'cart_id' => $created['id'] ) )->get_status() );
+	}
+}
diff --git a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpIdempotency.php b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpIdempotency.php
index e85e3b8f297..91cb529198d 100644
--- a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpIdempotency.php
+++ b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpIdempotency.php
@@ -136,6 +136,10 @@ class UcpIdempotency extends UcpCartTestCase {
 		$this->assertSame( 400, $response->get_status() );
 		$this->assertSame( array( 'IDEMPOTENCY_KEY_REQUIRED' ), $this->message_codes( $response ) );
 		$this->assertSame( 0, $this->stored_record_count() );
+		$this->assertSame( array( 'dev.ucp.shopping.cart' ), array_keys( $response->get_data()['ucp']['capabilities'] ) );
+
+		$checkout = $this->request( 'POST', '/checkout-sessions', $this->cart_body( 0 ) );
+		$this->assertSame( array( 'dev.ucp.shopping.checkout' ), array_keys( $checkout->get_data()['ucp']['capabilities'] ), 'The refusal names the capability of the route it came from.' );
 	}

 	/**