[Conversion value rules](https://support.google.com/google-ads/answer/10518330) let you define actions that will modify the value of a conversion based on the category of the [`ConversionAction`](https://developers.google.com/google-ads/api/reference/rpc/v26/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`](https://developers.google.com/google-ads/api/reference/rpc/v26/ConversionValueRule), which consists of: - The conditions that determine when the rule is applied - The action to take when the rule is applied > [!NOTE] > **Note:** Until a `ConversionValueRule` is added to a `ConversionValueRuleSet`, you won't be able to view it in the Google Ads UI. For example, the following JSON payload for [`ConversionValueRuleService.MutateConversionValueRules`](https://developers.google.com/google-ads/api/reference/rpc/v26/ConversionValueRuleService/MutateConversionValueRules) creates a rule that multiplies conversion values by `1.5` for mobile impressions: { "operations": [ { "create": { "action": { "operation": "MULTIPLY", "value": 1.5 }, "deviceCondition": { "deviceTypes": ["MOBILE"] } } } ] } ### 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/ValueRuleDeviceTypeEnum.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](https://developers.google.com/google-ads/api/docs/targeting/location-targeting#retrieve-geo-targets) 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/ConversionValueRule.ValueRuleItineraryCondition) for further details on the available conditions. > [!IMPORTANT] > **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`](https://developers.google.com/google-ads/api/reference/rpc/v26/ConversionValueRule#action), which consists of an [`operation`](https://developers.google.com/google-ads/api/reference/rpc/v26/ValueRuleOperationEnum.ValueRuleOperation) and a [`value`](https://developers.google.com/google-ads/api/reference/rpc/v26/ConversionValueRule.ValueRuleAction#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](https://developers.google.com/google-ads/api/docs/conversions/conversion-value-rules#create-rule-sets). ### 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/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] > **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`](https://developers.google.com/google-ads/api/reference/rpc/v26/DatabaseErrorEnum.DatabaseError#data_constraint_violation) error. `dimensions` : A list of [`ValueRuleSetDimension`](https://developers.google.com/google-ads/api/reference/rpc/v26/ValueRuleSetDimensionEnum.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`](https://developers.google.com/google-ads/api/reference/rpc/v26/Segments#conversion_value_rule_primary_dimension) in [metrics](https://developers.google.com/google-ads/api/docs/conversions/conversion-value-rules#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](https://developers.google.com/google-ads/api/docs/conversions/conversion-value-rules#other-rule-attributes), 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 the [Google Ads Help Center](https://support.google.com/google-ads/answer/10520348#what_happens): 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](https://support.google.com/google-ads/answer/10562924) 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.