/services/incentive_service.proto

--- v24/services/incentive_service.proto    2026-04-22 18:40:52.000000000 +0000
+++ v25/services/incentive_service.proto    2026-07-21 21:17:11.000000000 +0000
@@ -1,220 +1,201 @@
 // Copyright 2026 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //     http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.

 syntax = "proto3";

-package google.ads.googleads.v24.services;
+package google.ads.googleads.v25.services;

+import "google/ads/googleads/v25/enums/incentive_offer_type.proto";
+import "google/ads/googleads/v25/enums/incentive_type.proto";
 import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/type/money.proto";

-option csharp_namespace = "Google.Ads.GoogleAds.V24.Services";
-option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v24/services;services";
+option csharp_namespace = "Google.Ads.GoogleAds.V25.Services";
+option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v25/services;services";
 option java_multiple_files = true;
 option java_outer_classname = "IncentiveServiceProto";
-option java_package = "com.google.ads.googleads.v24.services";
+option java_package = "com.google.ads.googleads.v25.services";
 option objc_class_prefix = "GAA";
-option php_namespace = "Google\\Ads\\GoogleAds\\V24\\Services";
-option ruby_package = "Google::Ads::GoogleAds::V24::Services";
+option php_namespace = "Google\\Ads\\GoogleAds\\V25\\Services";
+option ruby_package = "Google::Ads::GoogleAds::V25::Services";

 // Service to support incentive related operations.
 service IncentiveService {
   option (google.api.default_host) = "googleads.googleapis.com";
   option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/adwords";

   // Returns incentives for a given user.
   rpc FetchIncentive(FetchIncentiveRequest) returns (FetchIncentiveResponse) {
     option (google.api.http) = {
-      get: "/v24/incentives:fetchIncentive"
+      get: "/v25/incentives:fetchIncentive"
     };
   }

   // Applies the incentive for the ads customer.
   rpc ApplyIncentive(ApplyIncentiveRequest) returns (ApplyIncentiveResponse) {
     option (google.api.http) = {
-      post: "/v24/customers/{customer_id=*}/incentives/{selected_incentive_id=*}:applyIncentive"
+      post: "/v25/customers/{customer_id=*}/incentives/{selected_incentive_id=*}:applyIncentive"
       body: "*"
     };
     option (google.api.method_signature) = "country_code";
+    option (google.api.method_signature) =
+        "selected_incentive_id,customer_id,country_code";
   }
 }

 // Request for getting the acquisition incentive for a user.
 message FetchIncentiveRequest {
-  // Types of incentives offered
-  enum IncentiveType {
-    // Not specified.
-    UNSPECIFIED = 0;
-
-    // Unknown incentive type. Should not be used as a value explicitly.
-    UNKNOWN = 1;
-
-    // An acquisition incentive.
-    ACQUISITION = 2;
-  }
-
   // Optional. User's language code.
   // If not provided, the server will default to "en".
   // Possible language codes:
   // https://developers.google.com/google-ads/api/data/codes-formats#languages
   optional string language_code = 1 [(google.api.field_behavior) = OPTIONAL];

   // Optional. User's country code.
   // If not provided, the server will default to "US".
   // Possible country codes:
   // https://developers.google.com/google-ads/api/data/codes-formats#country_codes
   optional string country_code = 2 [(google.api.field_behavior) = OPTIONAL];

   // Optional. Email of the user that the requested incentive is meant for.
   // Will be used for channel partners who do NOT use OAuth to authenticate on
   // behalf of user.
   optional string email = 3 [(google.api.field_behavior) = OPTIONAL];

   // Optional. The type of incentive to get.
   // Defaults to ACQUISITION.
-  optional IncentiveType type = 4 [(google.api.field_behavior) = OPTIONAL];
+  optional google.ads.googleads.v25.enums.IncentiveTypeEnum.IncentiveType
+      incentive_type = 5 [(google.api.field_behavior) = OPTIONAL];
 }

 // An incentive that a user can claim for their account.
 message Incentive {
   // Requirement for an incentive.
   message Requirement {
     // Spend requirements for an incentive.
     message Spend {
       // Required. Amount in free spend that user will be granted after spending
       // target amount. Denominated in the currency of the country passed in the
       // get request.
       optional google.type.Money award_amount = 1
           [(google.api.field_behavior) = REQUIRED];

       // Required. Amount that user must spend to receive the award amount.
       // Denominated in the currency of the country passed in the get request.
       optional google.type.Money required_amount = 2
           [(google.api.field_behavior) = REQUIRED];
     }

     // The requirement for this incentive.
     //
     // Currently only spend requirements are supported, requirements for other
     // actions may be supported in a later version.
     oneof requirement {
       // Optional. Spend requirement for an incentive.
       Spend spend = 1 [(google.api.field_behavior) = OPTIONAL];
     }
   }

   // The incentive ID of this incentive. This is used to identify which
   // incentive is selected by the user in the CYO flow.
   optional int64 incentive_id = 1;

   // The requirement for this incentive.
   optional Requirement requirement = 2;

   // The URL of the terms and conditions for THIS incentive offer ONLY.
   //
   // This is different from the terms_and_conditions_url field in
   // AcquisitionIncentiveOffer which is a combination of all the Incentive
   // offers in a CYO offer.
   optional string incentive_terms_and_conditions_url = 3;

   // The type of the incentive.
-  optional FetchIncentiveRequest.IncentiveType type = 4;
+  optional google.ads.googleads.v25.enums.IncentiveTypeEnum.IncentiveType
+      incentive_type = 5;
 }

 // An incentive offer in the Choose-Your-Own Incentive feature where a user
 // can select from a set of incentives with different money amounts.
 message CyoIncentives {
   // Required. The CYO incentive with low target and award amounts.
   optional Incentive low_offer = 1 [(google.api.field_behavior) = REQUIRED];

   // Required. The CYO incentive with medium target and award amounts.
   optional Incentive medium_offer = 2 [(google.api.field_behavior) = REQUIRED];

   // Required. The CYO incentive with high target and award amounts.
   optional Incentive high_offer = 3 [(google.api.field_behavior) = REQUIRED];
 }

 // An acquisition incentive offer for a user. An offer means how the user is
 // treated. An offer can have no incentive or multiple incentives.
 message IncentiveOffer {
-  // Types of acquisition incentive offers.
-  enum OfferType {
-    // Unknown offer type. Should not be used as a value explicitly.
-    UNSPECIFIED = 0;
-
-    // Unknown offer type.
-    UNKNOWN = 1;
-
-    // An offer with no incentive.
-    NO_INCENTIVE = 2;
-
-    // A CYO (Choose-Your-Own) offer with multiple incentives to choose from.
-    CYO_INCENTIVE = 3;
-  }
-
-  // Required. The type of this acquisition incentive offer.
-  optional OfferType type = 1 [(google.api.field_behavior) = REQUIRED];
-
   // Optional. The URL of the terms and conditions for the incentive offer.
   optional string consolidated_terms_and_conditions_url = 2
       [(google.api.field_behavior) = OPTIONAL];

+  // Required. The type of this acquisition incentive offer.
+  optional google.ads.googleads.v25.enums.IncentiveOfferTypeEnum.OfferType
+      offer_type = 4 [(google.api.field_behavior) = REQUIRED];
+
   // The specific incentive details, which can only be one of the following.
   oneof incentive_details {
     // CYO incentives. Set when type is CYO_INCENTIVE.
     CyoIncentives cyo_incentives = 3;
   }
 }

 // Response from getting the acquisition incentive for a user when they visit a
 // specific marketing page.
 message FetchIncentiveResponse {
   // Required. The acquisition incentive offer for the user.
   optional IncentiveOffer incentive_offer = 1
       [(google.api.field_behavior) = REQUIRED];
 }

 // Request message for applying an incentive.
 message ApplyIncentiveRequest {
-  // The incentive ID of this incentive. This is used to identify which
-  // incentive is selected by the user in the CYO flow.
-  optional int64 selected_incentive_id = 1;
-
-  // The customer ID of the account that the incentive is being applied to.
-  optional string customer_id = 2;
+  // Required. The incentive ID of this incentive. This is used to identify
+  // which incentive is selected by the user in the CYO flow.
+  int64 selected_incentive_id = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The customer ID of the account that the incentive is being
+  // applied to.
+  string customer_id = 2 [(google.api.field_behavior) = REQUIRED];

   // Required. User's country code.
   // Required. This field must be equal to the Google Ads account's billing
   // country. Incentive eligibility, terms of service, and reward values are
   // often country-specific. This country code is used to ensure the selected
   // incentive is applicable to the user.
   // Possible country codes:
   // https://developers.google.com/google-ads/api/data/codes-formats#country_codes
-  optional string country_code = 3 [(google.api.field_behavior) = REQUIRED];
+  string country_code = 3 [(google.api.field_behavior) = REQUIRED];
 }

 // Response for applying an incentive.
 message ApplyIncentiveResponse {
   // The coupon code of the applied incentive.
   // A globally unique identifier of the applied incentive.
   // This code is separate and distinct from the selected_incentive_id in the
   // request.
   optional string coupon_code = 1;

   // The timestamp when this incentive was applied. The timestamp is in
   // UTC timezone and in "yyyy-MM-dd HH:mm:ss" format.
   optional string creation_time = 2;
 }