Use the [`Goal`](https://developers.google.com/google-ads/api/reference/rpc/v26/Goal) and [`CampaignGoalConfig`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignGoalConfig)
resources of the Google Ads API to configure goals related to the customer lifecycle.
The Google Ads API supports [customer acquisition goals](https://support.google.com/google-ads/answer/12080169) and
[retention goals](https://support.google.com/google-ads/answer/14792043) for efficiently managing customer lifecycle
value adjustments through your Google Ads campaigns.

If your Google Ads account is using
[cross-account conversion tracking](https://developers.google.com/google-ads/api/docs/conversions/getting-started#cross-account-conversion-tracking), then you must configure
customer-level lifecycle goals in the
[Google Ads conversion account](https://developers.google.com/google-ads/api/docs/conversions/getting-started) 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](https://developers.google.com/google-ads/api/docs/conversions/goals/overview)
when using cross-account conversion tracking.

## Customer lifecycle goal types

Customer lifecycle goals are configured at the account level using the
[`Goal`](https://developers.google.com/google-ads/api/reference/rpc/v26/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`](https://developers.google.com/google-ads/api/reference/rpc/v26/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`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoalService).

The `new_customer_acquisition_goal_settings.value_settings` field uses
[`CustomerLifecycleOptimizationValueSettings`](https://developers.google.com/google-ads/api/reference/rpc/v26/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](https://support.google.com/google-ads/answer/14792043). 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/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`](https://developers.google.com/google-ads/api/reference/rpc/v26/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`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserListCustomerTypeService) to
create [`UserListCustomerType`](https://developers.google.com/google-ads/api/reference/rpc/v26/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`](https://developers.google.com/google-ads/api/reference/rpc/v26/UserListCustomerTypeCategoryEnum.UserListCustomerTypeCategory) to the same user list results 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` |
| `LOYALTY_TIER_X_MEMBERS` | `LOYALTY_TIER_Y_MEMBERS` |

## Configure campaign lifecycle goal configs

At the campaign level, you can configure campaign-specific overrides or
targeting options using [`CampaignGoalConfig`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignGoalConfig). Once
you have an account-level goal, use its `resource_name` to create a
`CampaignGoalConfig` using the [`mutate_campaign_goal_configs`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignGoalConfigService/MutateCampaignGoalConfigs) method on the
[`CampaignGoalConfigService`](https://developers.google.com/google-ads/api/reference/rpc/v26/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`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignGoalSettings.CampaignNewCustomerAcquisitionGoalSettings):

- **`value_settings_override`** (Type: [`CustomerLifecycleOptimizationValueSettings`](https://developers.google.com/google-ads/api/reference/rpc/v26/CustomerLifecycleOptimizationValueSettings)): Custom value adjustments to override the account-level settings.
- **`target_option`** (Type: [`CustomerLifecycleOptimizationMode`](https://developers.google.com/google-ads/api/reference/rpc/v26/CustomerLifecycleOptimizationModeEnum.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`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignGoalSettings.CampaignRetentionGoalSettings):

- **`value_settings_override`** (Type: [`CustomerLifecycleOptimizationValueSettings`](https://developers.google.com/google-ads/api/reference/rpc/v26/CustomerLifecycleOptimizationValueSettings)): Custom value adjustments to override the account-level settings.
- **`target_option`** (Type: [`CustomerLifecycleOptimizationMode`](https://developers.google.com/google-ads/api/reference/rpc/v26/CustomerLifecycleOptimizationModeEnum.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`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignGoalSettings.CampaignLoyaltyRetentionGoalSettings) on
[`CampaignGoalConfig`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignGoalConfig):

- **`value_settings_override`** (Type: [`CustomerLifecycleOptimizationValueSettings`](https://developers.google.com/google-ads/api/reference/rpc/v26/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:

| Customer Lifecycle Goal Type / Mode | Incompatible Goal / Mode |
|---|---|
| Customer Retention ("Only bid for lapsed customers" / `TARGET_SPECIFIC`) | New Customer Acquisition ("Only bid for new customers" / `TARGET_SPECIFIC`, "Bid higher for new customers" / `TARGET_ALL`), Prospecting |
| Customer Retention ("Bid higher for lapsed customers" / `TARGET_ALL`) | New Customer Acquisition ("Only bid for new customers" / `TARGET_SPECIFIC`), Prospecting |
| Loyalty Retention (Value Multiplier) | New Customer Acquisition ("Only bid for new customers" / `TARGET_SPECIFIC`), Customer Retention ("Only bid for lapsed customers" / `TARGET_SPECIFIC`), Prospecting, Gross Profit |
| Loyalty Retention (Benefits in PLA) | New Customer Acquisition ("Only bid for new customers" / `TARGET_SPECIFIC`), Prospecting, Gross Profit |
| Prospecting | New Customer Acquisition ("Only bid for new customers" / `TARGET_SPECIFIC`, "Bid higher for new customers" / `TARGET_ALL`) |

## Retrieve lifecycle goals

As with other resources in the Google Ads API, use the `search` or `searchStream`
methods of [`GoogleAdsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/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