Insentif

Panduan ini menjelaskan cara menggunakan Google Ads API untuk mengambil dan menerapkan insentif Google Ads secara terprogram untuk pelanggan Anda.

Mengambil insentif

Anda dapat menggunakan metode IncentiveService.FetchIncentive untuk mengambil insentif yang tersedia bagi pelanggan. Metode ini dapat menampilkan opsi insentif "Pilih Sendiri" (CYO) yang dipersonalisasi.

FetchIncentiveRequest dapat mencakup:

language_code: Kode bahasa pelanggan (defaultnya en).
country_code: Kode negara pelanggan (defaultnya US).
email: Email pelanggan.
type: IncentiveType insentif yang akan didapatkan. API hanya mendukung ACQUISITION.

FetchIncentiveResponse berisi IncentiveOffer. Jika OfferType adalah CYO_INCENTIVE, kolom cyo_incentives berisi low_offer, medium_offer, dan high_offer, yang masing-masing merupakan Incentive dengan detail seperti incentive_id, requirement, dan incentive_terms_and_conditions_url.

Contoh berikut menunjukkan cara mengambil insentif:

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.v23.errors.GoogleAdsError;
import com.google.ads.googleads.v23.errors.GoogleAdsException;
import com.google.ads.googleads.v23.services.CyoIncentives;
import com.google.ads.googleads.v23.services.FetchIncentiveRequest;
import com.google.ads.googleads.v23.services.FetchIncentiveRequest.IncentiveType;
import com.google.ads.googleads.v23.services.FetchIncentiveResponse;
import com.google.ads.googleads.v23.services.Incentive;
import com.google.ads.googleads.v23.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.v23.services import FetchIncentiveRequest, FetchIncentiveResponse
from google.ads.googleads.v23.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="v23")

    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.

Menerapkan insentif

Setelah pelanggan memilih insentif, Anda dapat menggunakan metode IncentiveService.ApplyIncentive untuk menerapkannya ke akun pelanggan Google Ads tertentu.

ApplyIncentiveRequest memerlukan:

selected_incentive_id: ID insentif yang dipilih pelanggan.
customer_id: ID pelanggan akun tempat Anda menerapkan insentif.
country_code: Kode negara pelanggan, yang harus cocok dengan negara penagihan akun Google Ads.

ApplyIncentiveResponse menampilkan coupon_code insentif yang diterapkan dan creation_time.

Contoh berikut menunjukkan cara menerapkan insentif:

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.v23.errors.GoogleAdsError;
import com.google.ads.googleads.v23.errors.GoogleAdsException;
import com.google.ads.googleads.v23.services.ApplyIncentiveRequest;
import com.google.ads.googleads.v23.services.ApplyIncentiveResponse;
import com.google.ads.googleads.v23.services.IncentiveServiceClient;
import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * This example applies an incentive to a user's account.
 *
 * <p>This example is a no-op if the user already has an accepted incentive. If the user attempts to
 * apply a new incentive, the response will simply return the existing incentive that has already
 * been applied to the account.
 */
public class ApplyIncentive {

  private static class ApplyIncentiveParams extends CodeSampleParams {

    @Parameter(
        names = ArgumentNames.CUSTOMER_ID,
        required = true,
        description = "The Google Ads customer ID.")
    private Long customerId;

    @Parameter(
        names = ArgumentNames.INCENTIVE_ID,
        required = true,
        description = "The ID of the incentive to apply.")
    private String incentiveId;

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

  public static void main(String[] args) throws IOException {
    ApplyIncentiveParams params = new ApplyIncentiveParams();
    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.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
      params.incentiveId = "INSERT_INCENTIVE_ID_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 ApplyIncentive().runExample(googleAdsClient, params.customerId, params.incentiveId,
          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 customerId the client customer ID.
   * @param incentiveId the ID of the incentive to apply.
   * @param countryCode the country of the incentive.
   */
  private void runExample(GoogleAdsClient googleAdsClient, long customerId, String incentiveId,
      String countryCode) {
    try (IncentiveServiceClient incentiveServiceClient = googleAdsClient.getLatestVersion()
        .createIncentiveServiceClient()) {
      ApplyIncentiveRequest request = ApplyIncentiveRequest.newBuilder()
          .setCustomerId(String.valueOf(customerId))
          .setSelectedIncentiveId(Long.parseLong(incentiveId)).setCountryCode(countryCode).build();
      // Issues the request.
      ApplyIncentiveResponse response = incentiveServiceClient.applyIncentive(request);

      // Processes the response.
      System.out.println("====================================================================");
      System.out.printf("Applied incentive with coupon code '%s'.%n", response.getCouponCode());
      System.out.printf("Incentive was created at '%s'.%n", response.getCreationTime());
      System.out.println("====================================================================");
    }
  }
}
ApplyIncentive.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.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V23.Errors;
using Google.Ads.GoogleAds.V23.Services;
using System;

namespace Google.Ads.GoogleAds.Examples.V23
{
    /// <summary>
    /// This code example applies an incentive to a user's account.
    /// </summary>
    public class ApplyIncentive : ExampleBase
    {
         /// <summary>
        /// Command line options for running the <see cref="FetchIncentives"/> example.
        /// </summary>
        public class Options : OptionsBase
        {
            /// <summary>
            /// The customer ID for which the call is made.
            /// </summary>
            [Option("customerId", Required = true, HelpText =
                "The customer ID for which the call is made.")]
            public long CustomerId { get; set; }

            /// <summary>
            /// The ID of the incentive to apply.
            /// </summary>
            [Option("incentiveId", Required = true, HelpText =
                "The ID of the incentive to apply.")]
            public long IncentiveId { get; set; }

            /// <summary>
            /// The country for the incentive to apply.
            /// </summary>
            [Option("countryCode", Required = true, HelpText =
                "The country for the incentive to apply.")]
            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);

            ApplyIncentive codeExample = new ApplyIncentive();
            Console.WriteLine(codeExample.Description);              
            codeExample.Run(new GoogleAdsClient(), options.CustomerId,
            options.IncentiveId, options.CountryCode);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description =>
            "This code example applies an incentive to a user's account.";

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="customerId">The client customer ID.</param>
        /// <param name="incentiveId">The ID of the incentive to apply.</param>
        /// <param name="countryCode">The country for the returned incentive.</param>
        public void Run(GoogleAdsClient client, long customerId,
            long incentiveId, string countryCode)
        {
            IncentiveServiceClient incentiveService = client.GetService(
                Services.V23.IncentiveService);

            ApplyIncentiveRequest request = new ApplyIncentiveRequest()
            {
                CustomerId = customerId.ToString(),
                SelectedIncentiveId = incentiveId,
                CountryCode = countryCode
            };

            try
            {
                ApplyIncentiveResponse response =
                    incentiveService.ApplyIncentive(request);

                Console.WriteLine("===========================================");
                Console.WriteLine($"Applied incentive with coupon code: {response.CouponCode}");
                Console.WriteLine($"Incentive was created at: {response.CreationTime}");
                Console.WriteLine("===========================================");

            } catch  (GoogleAdsException e)
            {
                Console.WriteLine("Failure:");
                Console.WriteLine($"Message: {e.Message}");
                Console.WriteLine($"Failure: {e.Failure}");
                Console.WriteLine($"Request ID: {e.RequestId}");
                throw;
            }
        }
    }
}ApplyIncentive.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 applies an incentive to a user's account.

This example is a no-op if the user already has an accepted incentive. If the
user attempts to apply a new incentive, the response will simply return the
existing incentive that has already been applied to the account. Use the
fetch_incentives.py example to get the available incentives.
"""


import argparse
import sys

from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
from google.ads.googleads.v23.services import ApplyIncentiveRequest, ApplyIncentiveResponse
from google.ads.googleads.v23.services.services.incentive_service.client import (
    IncentiveServiceClient,
)


def main(
    client: GoogleAdsClient,
    customer_id: str,
    incentive_id: str,
    country_code: str = None,
) -> None:
    """Applies an incentive for the ads customer.

    Args:
        client: An initialized GoogleAdsClient instance.
        customer_id: The client customer ID.
        country_code: The country code of the user.
        incentive_id: The incentive ID to select.
    """
    incentive_service: IncentiveServiceClient = client.get_service("IncentiveService")
    apply_incentive_request: ApplyIncentiveRequest = client.get_type(
        "ApplyIncentiveRequest"
    )

    apply_incentive_request.customer_id = customer_id
    apply_incentive_request.selected_incentive_id = incentive_id

    if country_code:
        apply_incentive_request.country_code = country_code

    response: ApplyIncentiveResponse = incentive_service.apply_incentive(
        request=apply_incentive_request
    )

    print("Applied incentive.")
    print(f"Coupon Code: {response.coupon_code}")
    print(f"Creation Time: {response.creation_time}")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Applies an incentive for the ads customer."
    )
    # The following argument(s) should be provided to run the example.
    parser.add_argument(
        "-c",
        "--customer_id",
        type=str,
        required=True,
        help="The Google Ads customer ID.",
    )
    parser.add_argument(
        "-i",
        "--incentive_id",
        type=int,
        required=True,
        help="The incentive ID to select.",
    )
    parser.add_argument(
        "-k",
        "--country_code",
        type=str,
        required=False,
        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="v23")

    try:
        main(
            googleads_client,
            args.customer_id,
            args.incentive_id,
            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)apply_incentive.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.

Mengambil insentif yang diterapkan

Anda dapat membuat kueri resource AppliedIncentive hanya baca melalui GoogleAdsService.Search dan GoogleAdsService.SearchStream untuk mengambil detail tentang insentif yang diterapkan.

Kolom utama yang tersedia di AppliedIncentive meliputi:

resource_name
coupon_code
incentive_state
redemption_date_time
fulfillment_expiration_date_time
reward_grant_date_time
reward_expiration_date_time
currency_code
reward_amount_micros
granted_amount_micros
required_min_spend_micros
current_spend_towards_fulfillment_micros
reward_balance_remaining_micros

Kueri GAQL berikut mengambil semua kolom dari AppliedIncentive:

SELECT
  applied_incentive.resource_name,
  applied_incentive.coupon_code,
  applied_incentive.incentive_state,
  applied_incentive.redemption_date_time,
  applied_incentive.fulfillment_expiration_date_time,
  applied_incentive.reward_grant_date_time,
  applied_incentive.reward_expiration_date_time,
  applied_incentive.currency_code,
  applied_incentive.reward_amount_micros,
  applied_incentive.granted_amount_micros,
  applied_incentive.required_min_spend_micros,
  applied_incentive.current_spend_towards_fulfillment_micros,
  applied_incentive.reward_balance_remaining_micros
FROM
  applied_incentive

Sebelumnya

Faktur

Insentif Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Mengambil insentif

Java

C#

PHP

Python

Ruby

Perl

Menerapkan insentif

Java

C#

PHP

Python

Ruby

Perl

Mengambil insentif yang diterapkan

Insentif