Conversion Value Rules

Conversion value rules let you define actions that will modify the value of a conversion based on the category of the ConversionAction and the following dimensions of an impression:

• Audience membership
• Physical location or location of interest
• Device
• Travel itinerary

You can use the Google Ads API to define conversion value rules, combine them into a conversion value rule set, and then apply the rule set to your entire Google Ads account or a specific campaign. Segments in the Google Ads API reports provide breakdowns so you can compare the original, unadjusted, and adjusted portions of your conversion values.

Create rules

The first step in using conversion value rules is to create at least one ConversionValueRule, which consists of:

• The conditions that determine when the rule is applied
• The action to take when the rule is applied

Rule conditions

Define the conditions of a ConversionValueRule with the following fields:

audience_condition

Applies the rule to impressions associated with one or more audiences. Specify the resource names of each user list or user interest with the user_lists or user_interests fields. To retrieve the resource names of available user lists or user interests, issue a searchStream or search request of GoogleAdsService where the FROM clause of the query is user_list or user_interest, respectively.

If an audience_condition contains multiple user lists or user interests, an impression will match the rule if the impression is associated with any of the user lists or user interests.

device_condition

Applies the rule if the device of the impression matches any of the specified device_types. Only device types in ValueRuleDeviceType are permitted.

geo_location_condition

Applies the rule to impressions where the location information matches any of the specified geo_target_constants for the geo_match_type, and does not match any of the excluded_geo_target_constants for the excluded_geo_match_type. Consult the location targeting guide for how to retrieve location resource names.

itinerary_condition

Applies the rule to impressions where the search terms include itinerary-specific information, such as booking window, length of travel, or travel start day. Review ValueRuleItineraryCondition for further details on the available conditions.

Important: Travel itinerary conversion value rules are available only to accounts added to the allowlist. Contact your Google representative if you need access to the feature.

You can specify at most two of audience_condition, device_condition, geo_location_condition, or itinerary_condition on each ConversionValueRule.

A rule with no conditions specified applies to impressions that don't meet the conditions of a more specific rule in the same rule set.

Rule action

A rule must have a single action, which consists of an operation and a value. The action defines how to adjust the conversion value of a conversion that satisfies the rule's conditions. The available operations are as follows.

ADD

Adds the value to the original value of the conversion. The value must be greater than 0.

MULTIPLY

Multiplies the original value of the conversion by the specified value. The value must be greater than or equal to 0.5 and less than or equal to 10.

SET

Sets the conversion value to the specified value. The value must be greater than 0.

You can only use a rule with the SET action in a rule set that meets the conditions described in creating a rule set.

Other rule attributes

In addition to conditions and an action, a ConversionValueRule has the following attributes.

owner_customer

The resource name of the Customer that owns the rule. Use this to determine if a rule is defined within the account or one of its manager accounts.

status

The status of the rule. You can pause a rule by setting this field to PAUSED, and enable a paused rule by setting this field to ENABLED.

Create rule sets

Once you have at least one ConversionValueRule, you can create a ConversionValueRuleSet, which consists of:

conversion_action_categories

A list of categories of conversion actions to which this rule set applies. If the list is empty, the rule set applies to all categories. If the list is not empty, it must contain a single entry of either STORE_VISIT or STORE_SALE.

You can only set the list of conversion action categories when creating the rule set.

conversion_value_rules

The resource names of the rules to include in the set.

This list can only contain a rule that uses the SET action if either of these conditions are met:

• Your account is on the allowlist, and the conversion_action_categories of the rule set is empty.
• The conversion_action_categories of the set only contains a single entry of STORE_VISIT or STORE_SALE, the dimensions of the set only contains an entry for NO_CONDITION, and none of the condition fields of the rule are set.

Important: You can only include each conversion value rule in one conversion value rule set. If the conversion_value_rules contains the resource name of a rule that is in the conversion_value_rules of another rule set with status of ENABLED or PAUSED, the operation will fail with a DATA_CONSTRAINT_VIOLATION error.

dimensions

A list of ValueRuleSetDimension enum values that indicates which conditions the rules in the set can utilize. For example, if dimensions contains GEO_LOCATION and DEVICE, you can add rules with geo_location_condition or device_condition to the set, but you cannot add a rule with audience_condition.

This list cannot be empty, and can contain at most two entries.

The first entry in this list determines which value appears for segments.conversion_value_rule_primary_dimension in metrics.

If this list contains an entry for NO_CONDITION, then:

• NO_CONDITION must be the only entry in the list.
• The list of conversion_action_categories of the set must only contain a single entry of STORE_VISIT or STORE_SALE.
• The list of conversion_value_rules cannot contain any rule where audience_condition, device_condition, or geo_location_condition is set.

attachment_type

Set this value to CUSTOMER to create a rule set that applies to the entire account, or CAMPAIGN to create a rule set for a specific campaign.

campaign

If the attachment_type of the rule set is CAMPAIGN, set this to the resource name to which the rule set applies.

Similar to rules, a rule set also has an owner_customer and a status. However, the status of a rule set is read-only and derived from its rules as follows:

• If every rule referenced by conversion_value_rules has a status of PAUSED, then the conversion value rule set status will be PAUSED.
• Otherwise, the conversion value rule set status will be ENABLED.

Remove rules and rule sets

• A ConversionValueRuleSet must have at least one conversion value rule that is either PAUSED or ENABLED.

• Removing a ConversionValueRule that is referenced in the conversion_value_rules of a PAUSED or ENABLED ConversionValueRuleSet will fail.

• Removing a ConversionValueRuleSet does not change the status of each ConversionValueRule referenced by the set.

• Once a ConversionValueRuleSet is removed, search and searchStream requests for the conversion_value_rule_set resource will no longer return the removed set.

Precedence of rules and rule sets

Google Ads uses the following logic to select and apply at most one rule to each conversion. Find more information on these rules in Help Center:

1. Determine the attachment_type of rule sets to consider. If there are any rule sets with attachment_type = CAMPAIGN and campaign set to the campaign associated with the impression, then only consider campaign-level rule sets. Otherwise, only consider customer-level rule sets.

2. Among the rule sets to consider, choose the rule set where the conversion_action_categories is not empty and contains the category of the conversion's conversion action, if such a rule set exists. Otherwise, choose the rule set where conversion_action_categories is empty.

3. Evaluate the rules in the chosen rule set in the order in which they appear in conversion_value_rules, and select the first rule with conditions that match the impression.

4. For multiple matching geo location conditions, the most precise location is applied. For example, if an impression matches both United States and California conditions, then California will be applied because it's a more precise location.

5. For multiple matching audience conditions, the existing audience attribution hierarchy will be applied. If there is a tie between two rules in a set, then a "Multiply" rule will be selected over an "Add" rule. If there is still a tie (meaning more than one "Multiply" rule), the rule with the highest multiplier adjustment will be selected.

6. There cannot be multiple matching device conditions, because device categories are mutually exclusive.

7. For travel itinerary conditions, the most specific itinerary rule is applied. This means that if multiple rules match a given conversion, the rule that is used is the one with the most number of itinerary options defined, such as "Advance booking window" or "Length of travel".

Metrics

The metrics.conversions_value and metrics.all_conversions_value fields, as well as fields derived from those metrics, reflect modifications made by conversion value rule sets. In addition, you can include segments.conversion_value_rule_primary_dimension in your query for more information regarding how rules were applied. The possible values for that segment are as follows:

NO_RULE_APPLIED

Values for conversions where no rule was applied.

ORIGINAL

The original value of conversions where a rule was applied.

GEO_LOCATION, DEVICE, AUDIENCE, or NO_CONDITION

The value of conversions after a rule was applied, grouped by the first entry in the rule set's dimensions collection.