Lifecycle goals

Page Summary

outlined_flag

• The Google Ads API supports configuring customer lifecycle goals, including customer acquisition and retention goals, through dedicated resources.

• Customer lifecycle goals can be configured at the customer-level using the CustomerLifecycleGoal resource and at the campaign-level using the CampaignLifecycleGoal resource.

• Proper audience segmentation for customer lifecycle goals is managed using the UserListCustomerType resource.

• Retention goals, primarily for Performance Max campaigns, aim to enhance customer loyalty and can be set at the account or campaign level.

• Lifecycle goals can be retrieved using the search or searchStream methods of the GoogleAdsService.

Use the Goal and CampaignGoalConfig resources of the Google Ads API to configure goals related to the customer lifecycle. The Google Ads API supports customer acquisition goals and retention goals for efficiently managing customer lifecycle value adjustments through your Google Ads campaigns.

If your Google Ads account is using cross-account conversion tracking, then you must configure customer-level lifecycle goals in the Google Ads conversion account instead of directly in your Google Ads account. You should still set campaign-level configs in your account, however. This is similar to how you manage other goals when using cross-account conversion tracking.

Customer lifecycle goal types

Customer lifecycle goals are configured at the account level using the Goal resource. A goal represents a specific lifecycle objective and is defined by its goal_type.

The supported lifecycle goal types are:

NEW_CUSTOMER_ACQUISITION

For efficiently acquiring new customers by assigning value adjustments to their conversions.

CUSTOMER_RETENTION

For re-engaging existing, high value, and lapsed customers.

LOYALTY_RETENTION

For driving retention and engagement specifically among loyalty program members.

Configure customer lifecycle goals

At the customer level, configure a lifecycle goal by creating a Goal. There can be at most one Goal per goal type (NEW_CUSTOMER_ACQUISITION, CUSTOMER_RETENTION, or LOYALTY_RETENTION) in a Google Ads account.

New customer acquisition goal settings

To set up New Customer Acquisition (NCA), set the goal_type to NEW_CUSTOMER_ACQUISITION and configure the settings in the new_customer_acquisition_goal_settings field using the GoalService.

The new_customer_acquisition_goal_settings.value_settings field uses CustomerLifecycleOptimizationValueSettings to specify conversion value adjustments for acquired customers:

• value_settings (CustomerLifecycleOptimizationValueSettings):
  • value_adjustment (oneof):
    • additional_value (double): Incremental conversion value to add to a new customer's first purchase conversion.
    • value_multiplier (double): Multiplier to apply to the conversion value for a new customer's first purchase (not supported for NEW_CUSTOMER_ACQUISITION; supported for LOYALTY_RETENTION).
  • high_lifetime_value_adjustment (oneof):
    • additional_high_lifetime_value (double): Incremental conversion value for new customers who are identified as high-lifetime-value.
    • high_lifetime_value_multiplier (double): Conversion value multiplier to apply for high-lifetime-value new customers (not supported yet).

The high lifetime value should be greater than value, and the high lifetime value multiplier must be strictly greater than the value multiplier, if set.

def create_nca_goal(client: GoogleAdsClient, customer_id: str) -> None:
    """Sends an API request to add a new New Customer Acquisition Goal.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
    """
    goal_operation: GoalOperation = client.get_type("GoalOperation")
    goal = goal_operation.create
    goal.goal_type = client.enums.GoalTypeEnum.NEW_CUSTOMER_ACQUISITION

    # Configure the value adjustments.
    value_settings = goal.new_customer_acquisition_goal_settings.value_settings
    value_settings.additional_value = 50.0
    value_settings.additional_high_lifetime_value = 100.0

    goal_service = client.get_service("GoalService")
    goal_service.mutate_goals(
        customer_id=customer_id, operations=[goal_operation]
    )

Customer retention goal settings

To set up customer retention, set the goal_type to CUSTOMER_RETENTION and configure the settings in the retention_goal_settings field.

Before creating a retention goal, you must satisfy the prerequisites described in About the retention goal. This includes having a Performance Max campaign and a Customer Match user list.

def create_retention_goal(client: GoogleAdsClient, customer_id: str) -> None:
    """Sends an API request to add a new Customer Retention Goal.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
    """
    goal_operation: GoalOperation = client.get_type("GoalOperation")
    goal = goal_operation.create
    goal.goal_type = client.enums.GoalTypeEnum.CUSTOMER_RETENTION
    value_settings = goal.retention_goal_settings.value_settings
    value_settings.additional_value = 50.0
    value_settings.additional_high_lifetime_value = 100.0

    goal_service = client.get_service("GoalService")
    goal_service.mutate_goals(
        customer_id=customer_id, operations=[goal_operation]
    )

This creates a new retention goal at the account level for the specified client account, which is applied to all of its campaigns. By default, this goal targets all users in your Customer Match user lists.

Loyalty retention goal settings

To set up loyalty retention goals for loyalty program members, set the goal_type to LOYALTY_RETENTION and configure the settings in the loyalty_retention_goal_settings field (LoyaltyRetentionGoal).

Unlike NEW_CUSTOMER_ACQUISITION and CUSTOMER_RETENTION goals (which use additive value adjustments), LOYALTY_RETENTION goals support the value_multiplier setting in value_settings using CustomerLifecycleOptimizationValueSettings:

def create_loyalty_retention_goal(
    client: GoogleAdsClient, customer_id: str
) -> None:
    """Sends an API request to add a new Loyalty Retention Goal.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
    """
    goal_operation: GoalOperation = client.get_type("GoalOperation")
    goal = goal_operation.create
    goal.goal_type = client.enums.GoalTypeEnum.LOYALTY_RETENTION
    goal.loyalty_retention_goal_settings.value_settings.value_multiplier = 1.5

    goal_service = client.get_service("GoalService")
    goal_service.mutate_goals(
        customer_id=customer_id, operations=[goal_operation]
    )

Segment your audiences

You must use the UserListCustomerType resource to segment your audiences for customer lifecycle goals (including New Customer Acquisition, Customer Retention, and Loyalty Retention goals). You must associate each user list with one or more categories by creating a UserListCustomerType for each combination of user list and category.

Use the UserListCustomerTypeService to create UserListCustomerType instances.

The UserListCustomerTypeService only supports create and remove operations, so if you want to update an existing UserListCustomerType you must remove it and 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 results in a UserListCustomerTypeError.CONFLICTING_CUSTOMER_TYPES error:

Configure campaign lifecycle goal configs

At the campaign level, you can configure campaign-specific overrides or targeting options using CampaignGoalConfig. Once you have an account-level goal, use its resource_name to create a CampaignGoalConfig using the mutate_campaign_goal_configs method on the CampaignGoalConfigService.

Campaign new customer acquisition settings

To override settings or configure targeting for NCA at the campaign level, configure the campaign_new_customer_acquisition_settings field of type CampaignNewCustomerAcquisitionGoalSettings:

• value_settings_override (Type: CustomerLifecycleOptimizationValueSettings): Custom value adjustments to override the account-level settings.
• target_option (Type: CustomerLifecycleOptimizationMode): Controls the customer lifecycle optimization mode. The options are:
  • TARGET_ALL: The campaign targets both new and existing customers, but bids higher for new customers using the configured value adjustments.
  • TARGET_SPECIFIC: The campaign targets new customers only. Bidding adjustments are not applicable for this option.

def create_campaign_nca_config(
    client: GoogleAdsClient,
    customer_id: str,
    goal_resource_name: str,
    campaign_resource_name: str,
) -> None:
    """Sends an API request to add a new CampaignGoalConfig for NCA.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        goal_resource_name: the resource name of an existing NCA Goal.
        campaign_resource_name: the resource name of an existing Campaign.
    """
    operation: CampaignGoalConfigOperation = client.get_type(
        "CampaignGoalConfigOperation"
    )
    goal_config = operation.create
    goal_config.campaign = campaign_resource_name
    goal_config.goal = goal_resource_name

    # Set the target option to target both new and existing customers.
    nca_settings = goal_config.campaign_new_customer_acquisition_settings
    nca_settings.target_option = (
        client.enums.CustomerLifecycleOptimizationModeEnum.TARGET_ALL
    )
    # Optionally override value settings.
    nca_settings.value_settings_override.additional_value = 60.0

    campaign_goal_config_service = client.get_service(
        "CampaignGoalConfigService"
    )
    campaign_goal_config_service.mutate_campaign_goal_configs(
        customer_id=customer_id, operations=[operation]
    )

Campaign customer retention settings

To override settings or configure targeting for retention goals at the campaign level, configure the campaign_retention_settings field of type CampaignRetentionGoalSettings:

• value_settings_override (Type: CustomerLifecycleOptimizationValueSettings): Custom value adjustments to override the account-level settings.
• target_option (Type: CustomerLifecycleOptimizationMode): Controls the optimization mode. Defaults to TARGET_ALL. In order to set it to TARGET_SPECIFIC, your account must be on the appropriate allowlist.

def create_campaign_retention_config(
    client: GoogleAdsClient,
    customer_id: str,
    goal_resource_name: str,
    campaign_resource_name: str,
) -> None:
    """Sends an API request to add a new CampaignGoalConfig for Retention.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        goal_resource_name: the resource name of an existing Retention Goal.
        campaign_resource_name: the resource name of an existing Campaign.
    """
    operation: CampaignGoalConfigOperation = client.get_type(
        "CampaignGoalConfigOperation"
    )
    goal_config = operation.create
    goal_config.campaign = campaign_resource_name
    goal_config.goal = goal_resource_name

    goal_config.campaign_retention_settings.target_option = (
        client.enums.CustomerLifecycleOptimizationModeEnum.TARGET_ALL
    )
    # Accounts on the allowlist can set TARGET_SPECIFIC instead:
    # goal_config.campaign_retention_settings.target_option = (
    #     client.enums.CustomerLifecycleOptimizationModeEnum.TARGET_SPECIFIC
    # )

    campaign_goal_config_service = client.get_service(
        "CampaignGoalConfigService"
    )
    campaign_goal_config_service.mutate_campaign_goal_configs(
        customer_id=customer_id, operations=[operation]
    )

The campaign_retention_settings.target_option defaults to TARGET_ALL if not set. The option to set TARGET_SPECIFIC is only available to users on the appropriate allowlist.

Campaign loyalty retention settings

To override settings or configure loyalty-member-specific behavior at the campaign level for LOYALTY_RETENTION goals, configure the campaign_loyalty_retention_settings field of type CampaignLoyaltyRetentionGoalSettings on CampaignGoalConfig:

• value_settings_override (Type: CustomerLifecycleOptimizationValueSettings): Custom value adjustments to override the account-level loyalty retention value settings.
• enable_bid_adjustments_for_loyalty_members (Type: bool): Whether to enable bid adjustments for loyalty program members in this campaign.
• show_targeted_loyalty_member_benefits_in_pla (Type: bool): Whether to display targeted loyalty member benefits in Product Listing Ad (PLA) format in eligible countries.

def create_campaign_loyalty_retention_config(
    client: GoogleAdsClient,
    customer_id: str,
    goal_resource_name: str,
    campaign_resource_name: str,
) -> None:
    """Sends an API request to add a new CampaignGoalConfig for Loyalty.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        goal_resource_name: the resource name of an existing Loyalty Goal.
        campaign_resource_name: the resource name of an existing Campaign.
    """
    operation: CampaignGoalConfigOperation = client.get_type(
        "CampaignGoalConfigOperation"
    )
    goal_config = operation.create
    goal_config.campaign = campaign_resource_name
    goal_config.goal = goal_resource_name

    # Enable bid adjustments and targeted loyalty benefits in PLAs.
    loyalty_settings = goal_config.campaign_loyalty_retention_settings
    loyalty_settings.enable_bid_adjustments_for_loyalty_members = True
    loyalty_settings.show_targeted_loyalty_member_benefits_in_pla = True

    campaign_goal_config_service = client.get_service(
        "CampaignGoalConfigService"
    )
    campaign_goal_config_service.mutate_campaign_goal_configs(
        customer_id=customer_id, operations=[operation]
    )

Validation and errors

When configuring customer lifecycle goals, the following constraints and errors may be encountered:

Goal validation errors

Duplicate goal configuration

Creating a duplicate lifecycle goal when one already exists results in a GoalError.NEW_CUSTOMER_ACQUISITION_GOAL_ALREADY_EXISTS (for NCA), GoalError.RETENTION_GOAL_ALREADY_EXISTS (for retention goals), or GoalError.LOYALTY_RETENTION_GOAL_ALREADY_EXISTS (for loyalty retention goals) error.

Invalid value settings

When configuring lifecycle goal value settings, if high lifetime value is present, then standard value must be present (GoalError.HIGH_LIFETIME_VALUE_PRESENT_BUT_VALUE_ABSENT), and high lifetime value must be greater than value, if set (GoalError.HIGH_LIFETIME_VALUE_LESS_THAN_OR_EQUAL_TO_VALUE).

Similarly, for multiplicative value settings, if the high lifetime value multiplier is present, then the value multiplier must be present (GoalError.HIGH_LIFETIME_VALUE_MULTIPLIER_PRESENT_BUT_VALUE_MULTIPLIER_ABSENT), and the high lifetime value multiplier must be strictly greater than the value multiplier (GoalError.HIGH_LIFETIME_VALUE_MULTIPLIER_LESS_THAN_OR_EQUAL_TO_VALUE_MULTIPLIER).

Campaign goal config validation errors

Target specific value override conflict

For New Customer Acquisition goals, if target_option is set to TARGET_SPECIFIC (to target new customers only), campaign-level value overrides must not be configured (CampaignGoalConfigError.CAMPAIGN_OVERRIDE_VALUES_SET_FOR_NEW_CUSTOMER_ACQUISITION_TARGET_SPECIFIC_OPTION). Bidding adjustments are not applicable when targeting only new customers.

Invalid value settings override

When configuring campaign-level lifecycle value setting overrides, if high lifetime value is present, then standard value must be present (CampaignGoalConfigError.HIGH_LIFETIME_VALUE_PRESENT_BUT_VALUE_ABSENT), and high lifetime value must be greater than value, if set (CampaignGoalConfigError.HIGH_LIFETIME_VALUE_LESS_THAN_OR_EQUAL_TO_VALUE). Similarly, for multiplicative value settings, if the high lifetime value multiplier is present, then the value multiplier must be present (CampaignGoalConfigError.HIGH_LIFETIME_VALUE_MULTIPLIER_PRESENT_BUT_VALUE_MULTIPLIER_ABSENT), and the high lifetime value multiplier must be strictly greater than the value multiplier (CampaignGoalConfigError.HIGH_LIFETIME_VALUE_MULTIPLIER_LESS_THAN_OR_EQUAL_TO_VALUE_MULTIPLIER).

High lifetime value campaign type support

High lifetime value overrides and high lifetime value multiplier overrides must only be set for supported campaign types (CampaignGoalConfigError.CAMPAIGN_OVERRIDE_HIGH_LIFETIME_VALUE_NOT_SUPPORTED_FOR_CAMPAIGN_TYPE or CampaignGoalConfigError.CAMPAIGN_OVERRIDE_HIGH_LIFETIME_VALUE_MULTIPLIER_NOT_SUPPORTED_FOR_CAMPAIGN_TYPE).

Incompatible goals

An error is thrown if a campaign attempts to apply incompatible Customer Lifecycle Optimization goals simultaneously (CampaignGoalConfigError.CANNOT_USE_INCOMPATIBLE_CLO_GOALS). The following table outlines mutually exclusive goal combinations that trigger this error:

Retrieve lifecycle goals

As with other resources in the Google Ads API, use the search or searchStream methods of GoogleAdsService to retrieve lifecycle goals and configs.

The following query retrieves the details of every configured Goal in a Google Ads API account:

SELECT
  goal.goal_id,
  goal.goal_type,
  goal.owner_customer,
  goal.new_customer_acquisition_goal_settings.value_settings.additional_value,
  goal.new_customer_acquisition_goal_settings.value_settings.additional_high_lifetime_value,
  goal.retention_goal_settings.value_settings.additional_value,
  goal.retention_goal_settings.value_settings.additional_high_lifetime_value,
  goal.loyalty_retention_goal_settings.value_settings.value_multiplier
FROM goal

Similarly, the following query retrieves the details of every CampaignGoalConfig:

SELECT
  campaign_goal_config.campaign,
  campaign_goal_config.goal,
  campaign_goal_config.goal_type,
  campaign_goal_config.campaign_new_customer_acquisition_settings.target_option,
  campaign_goal_config.campaign_new_customer_acquisition_settings.value_settings_override.additional_value,
  campaign_goal_config.campaign_new_customer_acquisition_settings.value_settings_override.additional_high_lifetime_value,
  campaign_goal_config.campaign_retention_settings.target_option,
  campaign_goal_config.campaign_retention_settings.value_settings_override.additional_value,
  campaign_goal_config.campaign_loyalty_retention_settings.value_settings_override.value_multiplier,
  campaign_goal_config.campaign_loyalty_retention_settings.enable_bid_adjustments_for_loyalty_members,
  campaign_goal_config.campaign_loyalty_retention_settings.show_targeted_loyalty_member_benefits_in_pla
FROM campaign_goal_config