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
oruser_interests
fields. To retrieve the resource names of available user lists or user interests, issue asearchStream
orsearch
request ofGoogleAdsService
where theFROM
clause of the query isuser_list
oruser_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 inValueRuleDeviceType
are permitted. geo_location_condition
- Applies the rule to impressions where the location information matches any of
the specified
geo_target_constants
for thegeo_match_type
, and does not match any of theexcluded_geo_target_constants
for theexcluded_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 ValueRuleTravelItineraryCondition for further details on the available conditions.
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. Thevalue
must be greater than0
. MULTIPLY
- Multiplies the original value of the conversion by the specified
value
. Thevalue
must be greater than or equal to0.5
and less than or equal to10
. SET
Sets the conversion value to the specified
value
. Thevalue
must be greater than0
.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 toENABLED
.
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
orSTORE_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 allowlisted, and the
conversion_action_categories
of the rule set is empty. - The
conversion_action_categories
of the set only contains a single entry ofSTORE_VISIT
orSTORE_SALE
, thedimensions
of the set only contains an entry forNO_CONDITION
, and none of the condition fields of the rule are set.
- Your account is allowlisted, and the
dimensions
A list of
ValueRuleSetDimension
enum values that indicates which conditions the rules in the set can utilize. For example, ifdimensions
containsGEO_LOCATION
andDEVICE
, you can add rules withgeo_location_condition
ordevice_condition
to the set, but you cannot add a rule withaudience_condition
.This list cannot be empty, and can contain at most two entries.
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 ofSTORE_VISIT
orSTORE_SALE
. - The list of
conversion_value_rules
cannot contain any rule whereaudience_condition
,device_condition
, orgeo_location_condition
is set.
The first entry in this list determines which value appears for
segments.conversion_value_rule_primary_dimension
in metrics.attachment_type
Set this value to
CUSTOMER
to create a rule set that applies to the entire account, orCAMPAIGN
to create a rule set for a specific campaign.campaign
If the
attachment_type
of the rule set isCAMPAIGN
, 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 astatus
ofPAUSED
, then the conversion value rule setstatus
will bePAUSED
. - Otherwise, the conversion value rule set
status
will beENABLED
.
Remove rules and rule sets
A
ConversionValueRuleSet
must have at least one conversion value rule that is eitherPAUSED
orENABLED
.Removing a
ConversionValueRule
that is referenced in theconversion_value_rules
of aPAUSED
orENABLED
ConversionValueRuleSet
will fail.Removing a
ConversionValueRuleSet
does not change thestatus
of eachConversionValueRule
referenced by the set.Once a
ConversionValueRuleSet
is removed,search
andsearchStream
requests for theconversion_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:
Determine the
attachment_type
of rule sets to consider. If there are any rule sets withattachment_type = CAMPAIGN
andcampaign
set to the campaign associated with the impression, then only consider campaign-level rule sets. Otherwise, only consider customer-level rule sets.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 whereconversion_action_categories
is empty.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.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.
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.
There cannot be multiple matching device conditions, because device categories are mutually exclusive.
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
, orNO_CONDITION
- The value of conversions after a rule was applied, grouped by the first entry
in the rule set's
dimensions
collection.