Commit 6f85ffdcae3 for woocommerce

commit 6f85ffdcae389441bc6749b8a5aa7a6476a7b8a0
Author: Luis Felipe Zaguini <26530524+zaguiini@users.noreply.github.com>
Date:   Fri Nov 20 15:04:06 2026 -0300

    Tell agents to change variation options through the parent product (#71172)

    * Tell agents to change variation options through the parent product

    product-update refuses attributes on a variation ID. The refusal now names
    the parent product ID and the variations input, so the agent knows how to
    change the options.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Show the parent route hint only when the caller can follow it

    The update schema now accepts the variation shape of attributes, so a
    direct variation update reaches the refusal with the hint instead of a
    schema error. The hint names the variable parent from
    get_variable_parent(), and only shows when the parent's variations input
    takes attributes for that variation.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Show the parent route hint only when the parent takes variations

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    ---------

    Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

diff --git a/plugins/woocommerce/changelog/wooai-1736-variation-options-error b/plugins/woocommerce/changelog/wooai-1736-variation-options-error
new file mode 100644
index 00000000000..af692e4bfbd
--- /dev/null
+++ b/plugins/woocommerce/changelog/wooai-1736-variation-options-error
@@ -0,0 +1,4 @@
+Significance: patch
+Type: tweak
+
+The product-update ability now tells agents to change a variation's options through its parent product.
diff --git a/plugins/woocommerce/src/Internal/Abilities/Domain/Traits/ProductAbilityTrait.php b/plugins/woocommerce/src/Internal/Abilities/Domain/Traits/ProductAbilityTrait.php
index 410a8e3e730..9ee951da6ec 100644
--- a/plugins/woocommerce/src/Internal/Abilities/Domain/Traits/ProductAbilityTrait.php
+++ b/plugins/woocommerce/src/Internal/Abilities/Domain/Traits/ProductAbilityTrait.php
@@ -83,7 +83,7 @@ trait ProductAbilityTrait {
 				self::add_product_type_notes(
 					array_merge(
 						self::get_product_mutation_field_schemas_for_fields( $fields, false, $creating ),
-						$creating && in_array( 'attributes', $fields, true ) ? array( 'attributes' => self::get_product_create_attributes_schema() ) : array()
+						in_array( 'attributes', $fields, true ) ? array( 'attributes' => self::get_product_input_attributes_schema() ) : array()
 					),
 					$configs
 				)
@@ -93,15 +93,14 @@ trait ProductAbilityTrait {
 	}

 	/**
-	 * Get the schema of the `attributes` input of a create. A variable product
-	 * takes attributes with their options, and a variation takes the option it
-	 * picks for each attribute. The ability checks the shape against the type.
-	 * An update takes the parent shape only: a variation's options change
-	 * through the `variations` input of its parent.
+	 * Get the schema of the `attributes` input. A variable product takes
+	 * attributes with their options, and a variation takes the option it picks
+	 * for each attribute. The ability checks the shape against the type. An
+	 * update of a variation refuses `attributes` and names its parent route.
 	 *
 	 * @return array
 	 */
-	private static function get_product_create_attributes_schema(): array {
+	private static function get_product_input_attributes_schema(): array {
 		return array(
 			'type'        => 'array',
 			'description' => __( 'On a variable product, the attributes with their options. On a variation, the option it picks for each attribute of its parent.', 'woocommerce' ),
@@ -1498,17 +1497,41 @@ trait ProductAbilityTrait {
 			return null;
 		}

-		return new \WP_Error(
-			'woocommerce_product_field_unsupported',
-			sprintf(
-				/* translators: 1: product type, 2: comma-separated list of the fields sent, 3: comma-separated list of the fields the type takes. */
-				__( 'The %1$s product type does not take %2$s. It takes %3$s.', 'woocommerce' ),
-				$product->get_type(),
-				implode( ', ', $unsupported ),
-				implode( ', ', $supported )
-			),
-			array( 'status' => 400 )
+		$message = sprintf(
+			/* translators: 1: product type, 2: comma-separated list of the fields sent, 3: comma-separated list of the fields the type takes. */
+			__( 'The %1$s product type does not take %2$s. It takes %3$s.', 'woocommerce' ),
+			$product->get_type(),
+			implode( ', ', $unsupported ),
+			implode( ', ', $supported )
 		);
+
+		$parent = in_array( 'attributes', $unsupported, true ) ? self::get_variable_parent( $product ) : null;
+		if ( null !== $parent && self::parent_route_takes_attributes( $parent, $product ) ) {
+			$message .= ' ' . sprintf(
+				/* translators: %d: parent product ID. */
+				__( 'To change the options of a variation, update its parent product %d and send the variation in the variations input, with its id and attributes.', 'woocommerce' ),
+				$parent->get_id()
+			);
+		}
+
+		return new \WP_Error( 'woocommerce_product_field_unsupported', $message, array( 'status' => 400 ) );
+	}
+
+	/**
+	 * Whether an update of the parent takes `variations`, and an item of that
+	 * input takes `attributes` for this variation. That item uses the create
+	 * fields, so when it takes `attributes`, the refusal came from a direct update.
+	 *
+	 * @param \WC_Product_Variable $parent_product Parent.
+	 * @param \WC_Product          $variation      Variation.
+	 * @return bool
+	 */
+	private static function parent_route_takes_attributes( \WC_Product_Variable $parent_product, \WC_Product $variation ): bool {
+		$parent_config    = self::get_product_config_for_product( $parent_product );
+		$variation_config = self::get_product_config_for_product( $variation, true );
+
+		return ! is_wp_error( $parent_config ) && in_array( 'variations', $parent_config['fields'], true )
+			&& ! is_wp_error( $variation_config ) && in_array( 'attributes', $variation_config['fields'], true );
 	}

 	/**
diff --git a/plugins/woocommerce/tests/php/src/Internal/Abilities/AbilitiesLoaderTest.php b/plugins/woocommerce/tests/php/src/Internal/Abilities/AbilitiesLoaderTest.php
index 412272d76f5..9bffe109760 100644
--- a/plugins/woocommerce/tests/php/src/Internal/Abilities/AbilitiesLoaderTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/Abilities/AbilitiesLoaderTest.php
@@ -2661,6 +2661,78 @@ class AbilitiesLoaderTest extends \WC_Unit_Test_Case {
 		$this->assertCount( 2, wc_get_product( $parent_id )->get_children() );
 	}

+	/**
+	 * @testdox Should name the parent route for variation options only when the variation has a variable parent whose route takes variations and attributes.
+	 */
+	public function test_variation_options_hint_needs_a_parent_route(): void {
+		$created = wp_get_ability( 'woocommerce/product-create' )->execute( $this->get_shirt_input() );
+		$this->assertNotWPError( $created );
+		$parent_id  = $created['product']['id'];
+		$small_id   = $created['product']['variation_ids'][0];
+		$attributes = array(
+			array(
+				'name'   => 'Size',
+				'option' => 'M',
+			),
+		);
+
+		$no_attributes = static fn( $fields, $type ) => 'variation' === $type ? array_values( array_diff( $fields, array( 'attributes' ) ) ) : $fields;
+		add_filter( 'woocommerce_ability_product_type_fields', $no_attributes, 10, 2 );
+		try {
+			$through_parent = wp_get_ability( 'woocommerce/product-update' )->execute(
+				array(
+					'id'         => $parent_id,
+					'variations' => array(
+						array(
+							'id'         => $small_id,
+							'attributes' => $attributes,
+						),
+					),
+				)
+			);
+		} finally {
+			remove_filter( 'woocommerce_ability_product_type_fields', $no_attributes, 10 );
+		}
+		$this->assertWPError( $through_parent );
+		$this->assertSame( 'woocommerce_product_field_unsupported', $through_parent->get_error_code() );
+		$this->assertStringNotContainsString( 'parent product', $through_parent->get_error_message(), 'The parent route does not point at itself.' );
+
+		$no_variations = static fn( $fields, $type ) => 'variable' === $type ? array_values( array_diff( $fields, array( 'variations' ) ) ) : $fields;
+		add_filter( 'woocommerce_ability_product_type_fields', $no_variations, 10, 2 );
+		try {
+			$closed_parent = wp_get_ability( 'woocommerce/product-update' )->execute(
+				array(
+					'id'         => $small_id,
+					'attributes' => $attributes,
+				)
+			);
+		} finally {
+			remove_filter( 'woocommerce_ability_product_type_fields', $no_variations, 10 );
+		}
+		$this->assertWPError( $closed_parent );
+		$this->assertSame( 'woocommerce_product_field_unsupported', $closed_parent->get_error_code() );
+		$this->assertStringNotContainsString( 'parent product', $closed_parent->get_error_message(), 'A parent that does not take variations is no route.' );
+
+		wp_update_post(
+			array(
+				'ID'          => $small_id,
+				'post_parent' => 0,
+			)
+		);
+		wc_delete_product_transients( $small_id );
+		clean_post_cache( $small_id );
+
+		$orphan = wp_get_ability( 'woocommerce/product-update' )->execute(
+			array(
+				'id'         => $small_id,
+				'attributes' => $attributes,
+			)
+		);
+		$this->assertWPError( $orphan );
+		$this->assertSame( 'woocommerce_product_field_unsupported', $orphan->get_error_code() );
+		$this->assertStringNotContainsString( 'parent product', $orphan->get_error_message(), 'An orphan variation has no parent to name.' );
+	}
+
 	/**
 	 * @testdox Should treat a variation as a product in update, create, query and delete.
 	 */
@@ -2692,7 +2764,7 @@ class AbilitiesLoaderTest extends \WC_Unit_Test_Case {
 		);
 		$this->assertSame( '8.00', wc_get_product( $parent_id )->get_price() );

-		$direct_options = wp_get_ability( 'woocommerce/product-update' )->execute_change(
+		$direct_options = wp_get_ability( 'woocommerce/product-update' )->execute(
 			array(
 				'id'         => $small_id,
 				'attributes' => array(
@@ -2706,6 +2778,7 @@ class AbilitiesLoaderTest extends \WC_Unit_Test_Case {
 		$this->assertWPError( $direct_options );
 		$this->assertSame( 'woocommerce_product_field_unsupported', $direct_options->get_error_code() );
 		$this->assertStringContainsString( 'attributes', $direct_options->get_error_message() );
+		$this->assertStringContainsString( "update its parent product {$parent_id} and send the variation in the variations input", $direct_options->get_error_message(), 'The refusal names the parent route.' );

 		$resized = wp_get_ability( 'woocommerce/product-update' )->execute(
 			array(