Use the CustomerLifecycleGoal
and
CampaignLifecycleGoal
resources of the
Google Ads API to configure goals related to the customer lifecycle. As of v15, the
Google Ads API supports customer acquisition
goals for efficiently
acquiring new customers through your Google Ads Search and Performance Max
campaigns.
If your Google Ads account is using cross-account conversion tracking, then you must configure customer lifecycle goals in the Google Ads conversion customer account instead of directly in your Google Ads account. You should still set campaign lifecycle goals in your account, however. This is similar to how you manage other goals when using cross-account conversion tracking.
Configure customer lifecycle goals
At the customer-level, configure a lifecycle goal by creating or updating a
CustomerLifecycleGoal
. There can be at
most one CustomerLifecycleGoal
per Google Ads account. The
customer_acquisition_goal_value_settings.value
field defines the additional
value adjustment to add to a new customer's first purchase conversion. You can
read the customer_acquisition_goal_value_settings.high_lifetime_value
of the
goal, but this field is immutable in the Google Ads API.
Segment your audiences
Starting in Google Ads API v17 you must use the
UserListCustomerType
resource to segment
your audiences for customer lifecycle goals. Configuring audiences directly on
the CustomerLifecycleGoal
resource is
deprecated. Here are the details:
- Prior to v17:
- Add user lists to the
existing_user_lists
collection of aCustomerLifecycleGoal
.
- Add user lists to the
- Starting with v17:
- Associate each user list with one or more categories by creating a
UserListCustomerType
for each combination of user list and category.
- Associate each user list with one or more categories by creating a
In Google Ads API v17 and later
Use the
UserListCustomerTypeService
to
create UserListCustomerType
instances.
If you had already populated the
CustomerLifecycleGoal.lifecycle_goal_customer_definition_settings.existing_user_lists
field, then your account will already contain related UserListCustomerType
instances.
The UserListCustomerTypeService
only supports create
and remove
operations, so if you want to update an existing UserListCustomerType
you will
need to remove it then create a new one with the necessary updates.
A UserListCustomerType
can only be assigned to one user list, but a
user list can have multiple associated UserListCustomerType
instances
as long as there are no conflicts between the UserListCustomerType
instances. Trying to assign UserListCustomerType
instances with the
following combinations of
customer_type_category
to the same user list will result in a
UserListCustomerTypeError.CONFLICTING_CUSTOMER_TYPES
error:
First customer_type_category |
Second customer_type_category |
---|---|
PURCHASERS | CONVERTED_LEADS |
PURCHASERS | QUALIFIED_LEADS |
PURCHASERS | CART_ABANDONERS |
CONVERTED_LEADS | QUALIFIED_LEADS |
DISENGAGED_CUSTOMERS | CONVERTED_LEADS |
DISENGAGED_CUSTOMERS | QUALIFIED_LEADS |
DISENGAGED_CUSTOMERS | CART_ABANDONERS |
In Google Ads API v16
Set the following fields on your account's
CustomerLifecycleGoal
:
lifecycle_goal_customer_definition_settings.existing_user_lists
indicates which user lists contain existing customers.The
lifecycle_goal_customer_definition_settings.high_lifetime_value_user_lists
field indicates which user lists contain high lifetime value customers. You can read this field, but it is immutable in the Google Ads API.
Shared resource behavior
Until Google Ads API v16 is sunset in January 2025, it's important to remember that
UserListCustomerType
and the audience segmentation fields on
CustomerLifecycleGoal
are a shared resource, meaning that creating new
UserListCustomerType
instances in v17 and later will result in modifications
to your CustomerLifecycleGoal
instance in v16 and earlier, and the other way
around.
Here is how the fields on the two resources are mapped:
Mutating `CustomerLifecycleGoal` field in v16 | Side effect on `UserListCustomerType` in v17 |
---|---|
lifecycle_goal_customer_definition_settings.existing_user_lists
|
Creates or removes UserListCustomerType instances. The
user_list field contains the associated user list resource
name.
|
Mutating `UserListCustomerType` in v17 | Side effect on `CustomerLifecycleGoal` field in v16 |
---|---|
Create or remove UserListCustomerType instances.
|
Individual resource names will be added to, or removed from, the
lifecycle_goal_customer_definition_settings.existing_user_lists
|
Create or remove UserListCustomerType instances, where the
customer_type_category is set to
HIGH_VALUE_CUSTOMERS
|
Individual resource names will be added to, or removed from, the
lifecycle_goal_customer_definition_settings.high_lifetime_value_user_lists
|
Configure campaign lifecycle goals
At the campaign level, configure a lifecycle goal by creating or updating a
CampaignLifecycleGoal
. There can be at
most one CampaignLifecycleGoal
per campaign.
The customer_acquisition_goal_settings
field of a campaign-level goal lets you
set the optimization mode of the campaign as well as override the value settings
from the parent customer goal.
The optimization_mode
can be one of the following values:
TARGET_ALL_EQUALLY
- The campaign targets new and existing customers equally. This is the default optimization mode.
BID_HIGHER_FOR_NEW_CUSTOMERS
- The campaign targets both new and existing customers, but bids higher for
customers that are predicted be new and are not in one of the
existing_user_lists
. TARGET_NEW_CUSTOMERS
- The campaign only targets new customers.
The value_settings
are the same as the
customer_acquisition_goal_value_settings
on the customer-level goal. Use these
campaign-level settings to override the values for a specific campaign.
Retrieve lifecycle goals
As with other resources in the Google Ads API, use the search
or searchStream
methods of GoogleAdsService
to retrieve
lifecycle goals.
The following query retrieves the details of every CustomerLifecycleGoal
in a
Google Ads account:
SELECT
customer_lifecycle_goal.lifecycle_goal_customer_definition_settings.existing_user_lists,
customer_lifecycle_goal.lifecycle_goal_customer_definition_settings.high_lifetime_value_user_lists,
customer_lifecycle_goal.customer_acquisition_goal_value_settings.value,
customer_lifecycle_goal.customer_acquisition_goal_value_settings.high_lifetime_value
FROM customer_lifecycle_goal
Similarly, the following query retrieves the details of every
CampaignLifecycleGoal
:
SELECT
campaign_lifecycle_goal.campaign,
campaign_lifecycle_goal.customer_acquisition_goal_settings.optimization_mode,
campaign_lifecycle_goal.customer_acquisition_goal_settings.value_settings.value,
campaign_lifecycle_goal.customer_acquisition_goal_settings.value_settings.high_lifetime_value
FROM campaign_lifecycle_goal