Join us live on Discord
on the Google Advertising and Measurement Community server and on YouTube
on April 23rd at 10:00 AM EST! We will discuss the new features added in v24 of the Google Ads API.
Fetch incentives Stay organized with collections
Save and categorize content based on your preferences.
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
(
"===================================================================="
);
}
}
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
(
"==========================================="
);
}
}
}
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
'
\t
Error with message "
{
error
.
message
}
".'
)
if
error
.
location
:
for
field_path_element
in
error
.
location
.
field_path_elements
:
print
(
f
"
\t\t
On field:
{
field_path_element
.
field_name
}
"
)
sys
.
exit
(
1
)
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
Note:
While a direct REST code sample for this step isn't provided here, you can achieve this using a manual REST request. Refer to the Google Ads API REST interface documentation and the method-specific reference pages. You will need to construct the JSON payload based on the proto definitions. Key Resources:
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-04-22 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-04-22 UTC."],[],[]]
