// 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.v23.services;

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.V23.Services";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v23/services;services";
option java_multiple_files = true;
option java_outer_classname = "IncentiveServiceProto";
option java_package = "com.google.ads.googleads.v23.services";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V23\\Services";
option ruby_package = "Google::Ads::GoogleAds::V23::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: "/v23/incentives:fetchIncentive"
    };
  }

  // Applies the incentive for the ads customer.
  rpc ApplyIncentive(ApplyIncentiveRequest) returns (ApplyIncentiveResponse) {
    option (google.api.http) = {
      post: "/v23/customers/{customer_id=*}/incentives/{selected_incentive_id=*}:applyIncentive"
      body: "*"
    };
    option (google.api.method_signature) = "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];
}

// 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;
}

// 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];

  // 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. 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];
}

// 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;
}