Lifecycle Goals

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.

Handle create and update operations (for v15 only)

In Google Ads API v15, the operations supported in the CustomerLifecycleGoalService and CampaignLifecycleGoalService differ slightly from other services in the Google Ads API. Instead of having separate create and update operations, the v15 CustomerLifecycleGoalOperation and CampaignLifecycleGoalOperation have only a create operation, and you indicate your intent using the update_mask as follows:

  • To create a lifecycle goal using v15, populate create with the goal but don't set its resource_name and don't set the update_mask of the operation.

  • To update a lifecycle goal using v15, populate create with the goal, set the resource_name of the goal, and set the update_mask to list the fields you want to update.

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 a CustomerLifecycleGoal.
  • Starting with v17:
    • Associate each user list with one or more categories by creating a UserListCustomerType for each combination of user list and category.

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 and earlier

Set the following fields on your account's CustomerLifecycleGoal:

  1. lifecycle_goal_customer_definition_settings.existing_user_lists indicates which user lists contain existing customers.

  2. 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
Previous
Campaign goals