Fetch incentives

Java

// 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
//
//     https://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.

package com.google.ads.googleads.examples.incentives;

import com.beust.jcommander.Parameter;
import com.google.ads.googleads.examples.utils.ArgumentNames;
import com.google.ads.googleads.examples.utils.CodeSampleParams;
import com.google.ads.googleads.lib.GoogleAdsClient;
import com.google.ads.googleads.v24.errors.GoogleAdsError;
import com.google.ads.googleads.v24.errors.GoogleAdsException;
import com.google.ads.googleads.v24.services.CyoIncentives;
import com.google.ads.googleads.v24.services.FetchIncentiveRequest;
import com.google.ads.googleads.v24.services.FetchIncentiveRequest.IncentiveType;
import com.google.ads.googleads.v24.services.FetchIncentiveResponse;
import com.google.ads.googleads.v24.services.Incentive;
import com.google.ads.googleads.v24.services.IncentiveServiceClient;
import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * This example fetches the available incentives for a user.
 */
public class FetchIncentives {

  private static class FetchIncentivesParams extends CodeSampleParams {

    @Parameter(
        names = ArgumentNames.EMAIL_ADDRESS,
        required = true,
        description = "The email of the user to fetch incentives for.")
    private String email;

    @Parameter(
        names = ArgumentNames.LANGUAGE_CODE,
        description = "The language for the returned incentive.")
    private String languageCode = "en";

    @Parameter(
        names = ArgumentNames.COUNTRY_CODE,
        description = "The country for the returned incentive.")
    private String countryCode = "US";
  }

  public static void main(String[] args) throws IOException {
    FetchIncentivesParams params = new FetchIncentivesParams();
    if (!params.parseArguments(args)) {
      // Either pass the required parameters for this example on the command line, or insert them
      // into the code here. See the parameter class definition above for more information.
      params.email = "INSERT_EMAIL_HERE";
    }

    GoogleAdsClient googleAdsClient = null;
    try {
      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
    } catch (FileNotFoundException fnfe) {
      System.err.printf(
          "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
      System.exit(1);
    } catch (IOException ioe) {
      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
      System.exit(1);
    }

    try {
      new FetchIncentives()
          .runExample(googleAdsClient, params.email, params.languageCode, params.countryCode);
    } catch (GoogleAdsException gae) {
      // GoogleAdsException is the base class for most exceptions thrown by an API request.
      // Instances of this exception have a message and a GoogleAdsFailure that contains a
      // collection of GoogleAdsError instances that detail the underlying causes of the
      // exception.
      System.err.printf(
          "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
          gae.getRequestId());
      int i = 0;
      for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
        System.err.printf("  Error %d: %s%n", i++, googleAdsError);
      }
      System.exit(1);
    }
  }

  /**
   * Runs the example.
   *
   * @param googleAdsClient the Google Ads API client.
   * @param email the email of the user to fetch incentives for.
   * @param languageCode the language of the incentives.
   * @param countryCode the country of the incentives.
   */
  private void runExample(
      GoogleAdsClient googleAdsClient, String email, String languageCode, String countryCode) {
    try (IncentiveServiceClient incentiveServiceClient =
        googleAdsClient.getLatestVersion().createIncentiveServiceClient()) {
      FetchIncentiveRequest request = FetchIncentiveRequest.newBuilder().setCountryCode(countryCode)
          .setLanguageCode(languageCode).setEmail(email).setType(IncentiveType.ACQUISITION).build();

      // Issues the request.
      FetchIncentiveResponse response =
          incentiveServiceClient.fetchIncentive(request);

      // Processes the response.
      if (!response.hasIncentiveOffer()) {
        System.out.print("No incentive offer was found");
        return;
      }

      // If the offer type is CHOOSE_YOUR_OWN_INCENTIVE, there will be 3 incentives in the
      // response. At the time this example was written, all incentive offers are CYO incentive offers.
      if (response.getIncentiveOffer().hasCyoIncentives()) {
        CyoIncentives cyoIncentives = response.getIncentiveOffer().getCyoIncentives();
        printIncentiveDetails(cyoIncentives.getLowOffer());
        printIncentiveDetails(cyoIncentives.getMediumOffer());
        printIncentiveDetails(cyoIncentives.getHighOffer());
      }
    }
  }

  private void printIncentiveDetails(Incentive incentive) {
    System.out.println("====================================================================");
    System.out.printf("Incentive ID: '%s'%n", incentive.getIncentiveId());
    System.out.printf("Incentive requirement: '%s'%n", incentive.getRequirement());
    System.out.printf(
        "Incentive terms and conditions: '%s'%n", incentive.getIncentiveTermsAndConditionsUrl());
    System.out.println("====================================================================");
  }
}



FetchIncentives.java

C#

// 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.

using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.Gax.Lib;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V23.Errors;
using Google.Ads.GoogleAds.V23.Services;
using System;

using static Google.Ads.GoogleAds.V23.Services.FetchIncentiveRequest.Types;

namespace Google.Ads.GoogleAds.Examples.V23
{
    /// <summary>
    /// This code example fetches the available incentives for a user.
    /// </summary>
    public class FetchIncentives : ExampleBase
    {
         /// <summary>
        /// Command line options for running the <see cref="FetchIncentives"/> example.
        /// </summary>
        public class Options : OptionsBase
        {
            /// <summary>
            /// The email of the user to fetch incentives for.
            /// </summary>
            [Option("email", Required = true, HelpText =
                "The email of the user to fetch incentives for.")]
            public string Email { get; set; }

            /// <summary>
            /// The language for the returned incentive.
            /// </summary>
            [Option("languageCode", Required = true, HelpText =
                "The language for the returned incentive.")]
            public string LanguageCode { get; set; }

            /// <summary>
            /// The country for the returned incentive.
            /// </summary>
            [Option("countryCode", Required = true, HelpText =
                "The country for the returned incentive.")]
            public string CountryCode { get; set; }
        }

        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            Options options = ExampleUtilities.ParseCommandLine<Options>(args);

            FetchIncentives codeExample = new FetchIncentives();
            Console.WriteLine(codeExample.Description);
            codeExample.Run(new GoogleAdsClient(), options.Email,
            options.LanguageCode, options.CountryCode);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description =>
            "This code example fetches the available incentives for a user.";

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="email">The email of the user to fetch incentives for.</param>
        /// <param name="languageCode">The language for the returned incentive.</param>
        /// <param name="countryCode">The country for the returned incentive.</param>
        public void Run(GoogleAdsClient client, string email, string languageCode,
            string countryCode)
        {
            IncentiveServiceClient incentiveService = client.GetService(
                Services.V23.IncentiveService);

            FetchIncentiveRequest request = new FetchIncentiveRequest()
            {
                CountryCode = countryCode,
                LanguageCode = languageCode,
                Email = email,
                Type = IncentiveType.Acquisition
            };

            try
            {
                FetchIncentiveResponse response =
                    incentiveService.FetchIncentive(request);

                if (response.IncentiveOffer.IsEmpty())
                {
                    Console.WriteLine("No incentive offer was found.");
                    return;
                }

                if (!response.IncentiveOffer.CyoIncentives.IsEmpty())
                {
                    CyoIncentives cyoIncentives = response.IncentiveOffer.CyoIncentives;
                    printIncentiveDetails(cyoIncentives.LowOffer);
                }

            } catch  (GoogleAdsException e)
            {
                Console.WriteLine("Failure:");
                Console.WriteLine($"Message: {e.Message}");
                Console.WriteLine($"Failure: {e.Failure}");
                Console.WriteLine($"Request ID: {e.RequestId}");
                throw;
            }
        }

        private void printIncentiveDetails(Incentive incentive)
        {
            Console.WriteLine("===========================================");
            Console.WriteLine($"Incentive ID: {incentive.IncentiveId}");
            Console.WriteLine($"Incentive requirement: {incentive.Requirement}");
            Console.WriteLine($"Incentive terms and conditions: {incentive.IncentiveTermsAndConditionsUrl}");
            Console.WriteLine("===========================================");
        }

    }
}
FetchIncentives.cs

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

#!/usr/bin/env python
# Copyright 2025 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
#
#     https://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.
"""This example returns incentives for a given user.

To apply an incentive, use apply_incentive.py.
"""

import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
from google.ads.googleads.v24.services import (
    FetchIncentiveRequest,
    FetchIncentiveResponse,
)
from google.ads.googleads.v24.services.services.incentive_service.client import (
    IncentiveServiceClient,
)


def main(
    client: GoogleAdsClient,
    email_address: str,
    language_code: str,
    country_code: str,
) -> None:
    """Returns incentives for a given user.

    Args:
        client: An initialized GoogleAdsClient instance.
        email_address: The email of the user to fetch incentives for.
        language_code: The language code of the user (e.g. 'en').
        country_code: The country code of the user (e.g. 'US').
    """
    incentive_service: IncentiveServiceClient = client.get_service(
        "IncentiveService"
    )
    fetch_incentive_request: FetchIncentiveRequest = client.get_type(
        "FetchIncentiveRequest"
    )

    fetch_incentive_request.email = email_address
    fetch_incentive_request.language_code = language_code
    fetch_incentive_request.country_code = country_code

    response: FetchIncentiveResponse = incentive_service.fetch_incentive(
        request=fetch_incentive_request
    )

    if response.incentive_offer and response.incentive_offer.cyo_incentives:
        print("Fetched incentive.")
        # If the offer type is CHOOSE_YOUR_OWN_INCENTIVE, there will be three
        # incentives in the response. At the time this example was written, all
        # incentive offers are CYO incentive offers.
        cyo_incentives = response.incentive_offer.cyo_incentives
        print(cyo_incentives.low_offer)
        print(cyo_incentives.medium_offer)
        print(cyo_incentives.high_offer)
    else:
        print("No incentives found.")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Returns incentives for a given user."
    )
    # The following argument(s) should be provided to run the example.
    parser.add_argument(
        "-e",
        "--email_address",
        type=str,
        required=True,
        help="The email of the user to fetch incentives for.",
    )
    parser.add_argument(
        "-l",
        "--language_code",
        type=str,
        required=False,
        default="en",
        help="The language code of the user (e.g. 'en').",
    )
    parser.add_argument(
        "-k",
        "--country_code",
        type=str,
        required=False,
        default="US",
        help="The country code of the user (e.g. 'US').",
    )
    args = parser.parse_args()

    # GoogleAdsClient will read the google-ads.yaml configuration file in the
    # home directory if none is specified.
    googleads_client = GoogleAdsClient.load_from_storage(version="v24")

    try:
        main(
            googleads_client,
            args.email_address,
            args.language_code,
            args.country_code,
        )
    except GoogleAdsException as ex:
        print(
            f'Request with ID "{ex.request_id}" failed with status '
            f'"{ex.error.code().name}" and includes the following errors:'
        )
        for error in ex.failure.errors:
            print(f'\tError with message "{error.message}".')
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

fetch_incentives.py

Ruby

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

curl