Draft: [GOOWOO-493] Implement endpoint to apply incentive

src/API/Google/Ads.php

@@ -17,6 +17,7 @@
 use Google\Ads\GoogleAds\V23\Enums\AccessRoleEnum\AccessRole;
 use Google\Ads\GoogleAds\V23\Enums\ProductLinkInvitationStatusEnum\ProductLinkInvitationStatus;
 use Google\Ads\GoogleAds\V23\Resources\ProductLinkInvitation;
+use Google\Ads\GoogleAds\V23\Services\ApplyIncentiveRequest;
 use Google\Ads\GoogleAds\V23\Services\FetchIncentiveRequest;
 use Google\Ads\GoogleAds\V23\Services\FetchIncentiveRequest\IncentiveType;
 use Google\Ads\GoogleAds\V23\Services\Incentive;
@@ -342,6 +343,51 @@ protected function format_money( ?Money $money ): array {
 		];
 	}
 
+	/**
+	 * Apply a selected incentive to the connected Google Ads account.
+	 *
+	 * @since 3.3.0
+	 *
+	 * @param string $incentive_id The selected incentive ID.
+	 * @param string $country_code ISO 3166-1 alpha-2 country code.
+	 *
+	 * @return array The applied incentive data with coupon_code and creation_time.
+	 * @throws ExceptionWithResponseData When the API call fails.
+	 */
+	public function apply_incentive( string $incentive_id, string $country_code ): array {
+		try {
+			$request = new ApplyIncentiveRequest(
+				[
+					'selected_incentive_id' => (int) $incentive_id,
+					'customer_id'           => (string) $this->options->get_ads_id(),
+					'country_code'          => $country_code,
+				]
+			);
+
+			$response = $this->client->getIncentiveServiceClient()->applyIncentive( $request );
+
+			return [
+				'coupon_code'   => $response->getCouponCode(),
+				'creation_time' => $response->getCreationTime(),
+			];
+		} catch ( ApiException $e ) {
+			do_action( 'woocommerce_gla_ads_client_exception', $e, __METHOD__ );
+
+			$errors = $this->get_exception_errors( $e );
+
+			throw new ExceptionWithResponseData(
+				sprintf(
+				/* translators: %s Error message */
+					__( 'Error applying incentive: %s', 'google-listings-and-ads' ),
+					reset( $errors )
+				),
+				$this->map_grpc_code_to_http_status_code( $e ),
+				null,
+				[ 'errors' => $errors ]
+			);
+		}
+	}
+
 	/**
 	 * Convert ads ID from a resource name to an int.
 	 *

src/API/Site/Controllers/Ads/IncentivesController.php

@@ -6,16 +6,19 @@
 use Automattic\WooCommerce\GoogleListingsAndAds\API\Google\Ads;
 use Automattic\WooCommerce\GoogleListingsAndAds\API\Site\Controllers\BaseController;
 use Automattic\WooCommerce\GoogleListingsAndAds\API\TransportMethods;
+use Automattic\WooCommerce\GoogleListingsAndAds\Exception\ExceptionWithResponseData;
 use Automattic\WooCommerce\GoogleListingsAndAds\Proxies\RESTServer;
 use Automattic\WooCommerce\GoogleListingsAndAds\Proxies\WC;
+use Exception;
 use WP_REST_Request as Request;
+use WP_REST_Response as Response;
 
 defined( 'ABSPATH' ) || exit;
 
 /**
  * Class IncentivesController
  *
- * Handles fetching Choose-Your-Own (CYO) incentive offers from the Google Ads API.
+ * Handles fetching and applying Choose-Your-Own (CYO) incentive offers via the Google Ads API.
  *
  * @since 3.3.0
  *
@@ -58,6 +61,12 @@ public function register_routes(): void {
 					'callback'            => $this->get_incentives_callback(),
 					'permission_callback' => $this->get_permission_callback(),
 				],
+				[
+					'methods'             => TransportMethods::CREATABLE,
+					'callback'            => $this->apply_incentive_callback(),
+					'permission_callback' => $this->get_permission_callback(),
+					'args'                => $this->get_apply_incentive_params(),
+				],
 				'schema' => $this->get_api_response_schema_callback(),
 			]
 		);
@@ -92,6 +101,46 @@ protected function get_language_code(): string {
 		return strtolower( substr( $locale, 0, 2 ) );
 	}
 
+	/**
+	 * @return callable
+	 */
+	protected function apply_incentive_callback(): callable {
+		return function ( Request $request ) {
+			try {
+				$incentive_id = $request->get_param( 'id' );
+				$country_code = $this->wc->get_base_country();
+
+				$result = $this->ads->apply_incentive( $incentive_id, $country_code );
+
+				return new Response( $result );
+			} catch ( ExceptionWithResponseData $e ) {
+				return $this->response_from_exception( $e );
+			} catch ( Exception $e ) {
+				return new Response(
+					[ 'message' => $e->getMessage() ],
+					500
+				);
+			}
+		};
+	}
+
+	/**
+	 * Get the request params for applying an incentive.
+	 *
+	 * @return array
+	 */
+	protected function get_apply_incentive_params(): array {
+		return [
+			'id' => [
+				'type'              => 'string',
+				'description'       => __( 'The incentive ID to apply.', 'google-listings-and-ads' ),
+				'required'          => true,
+				'validate_callback' => 'rest_validate_request_arg',
+				'sanitize_callback' => 'sanitize_text_field',
+			],
+		];
+	}
+
 	/**
 	 * Get the item schema properties for the controller.
 	 *

tests/Unit/API/Site/Controllers/Ads/IncentivesControllerTest.php

@@ -5,6 +5,7 @@
 
 use Automattic\WooCommerce\GoogleListingsAndAds\API\Google\Ads;
 use Automattic\WooCommerce\GoogleListingsAndAds\API\Site\Controllers\Ads\IncentivesController;
+use Automattic\WooCommerce\GoogleListingsAndAds\Exception\ExceptionWithResponseData;
 use Automattic\WooCommerce\GoogleListingsAndAds\Proxies\WC;
 use Automattic\WooCommerce\GoogleListingsAndAds\Tests\Framework\RESTControllerUnitTest;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -219,4 +220,58 @@ public function test_get_incentives_no_incentive_type() {
 		$this->assertSame( 'NO_INCENTIVE', $response->get_data()['type'] );
 		$this->assertEmpty( $response->get_data()['incentives'] );
 	}
+
+	public function test_apply_incentive_success() {
+		$this->ads->expects( $this->once() )
+			->method( 'apply_incentive' )
+			->with( '2378556534', 'GB' )
+			->willReturn(
+				[
+					'coupon_code'   => 'abc123',
+					'creation_time' => '2026-03-15 15:33:21',
+				]
+			);
+
+		$response = $this->do_request(
+			self::ROUTE_INCENTIVES,
+			'POST',
+			[ 'id' => '2378556534' ]
+		);
+
+		$this->assertEquals( 200, $response->get_status() );
+		$this->assertSame( 'abc123', $response->get_data()['coupon_code'] );
+		$this->assertSame( '2026-03-15 15:33:21', $response->get_data()['creation_time'] );
+	}
+
+	public function test_apply_incentive_api_exception() {
+		$this->ads->expects( $this->once() )
+			->method( 'apply_incentive' )
+			->willThrowException(
+				new ExceptionWithResponseData(
+					'Error applying incentive: PERMISSION_DENIED',
+					403,
+					null,
+					[ 'errors' => [ 'PERMISSION_DENIED' => 'The caller does not have permission' ] ]
+				)
+			);
+
+		$response = $this->do_request(
+			self::ROUTE_INCENTIVES,
+			'POST',
+			[ 'id' => '2378556534' ]
+		);
+
+		$this->assertEquals( 403, $response->get_status() );
+		$this->assertArrayHasKey( 'errors', $response->get_data() );
+	}
+
+	public function test_apply_incentive_missing_id() {
+		$response = $this->do_request(
+			self::ROUTE_INCENTIVES,
+			'POST',
+			[]
+		);
+
+		$this->assertEquals( 400, $response->get_status() );
+	}
 }