Google Ads API Updates & Release Notes

The following new features and updates were added in Google Ads API v26.1. Minor versions like v26.1 don't contain breaking changes.

Assets

External promotion redemption tracking

New messages, fields, enums, and error

Added the immutable PromotionAsset.external_redeem_info field of type ExternalRedeemInfo to specify external redemption tracking details for a promotion:

• ExternalRedeemInfo.partner_promotion_id: An immutable ExternalPartnerId message that holds either an integer (int_value) or a string (string_value) ID of the promotion in the partner's system. Required when the code_source field is set to GOOGLE_GENERATED.
• ExternalRedeemInfo.code_type: Required and immutable. The offline promotion code type (OfflinePromotionCodeType: SINGLE_USE_PROMOTION_CODE or MULTI_USE_PROMOTION_CODE).
• ExternalRedeemInfo.code_source: Required and immutable. The offline promotion code source (OfflinePromotionCodeSource: CUSTOMER_UPLOADED or GOOGLE_GENERATED).

Also added the AssetError.PARTNER_PROMOTION_ID_TYPE_INCOMPATIBLE error code, which the API returns when the partner_promotion_id field uses a format that the account's promotion integration does not accept.

Campaigns

Waterfall channel prioritization and budget caps for campaign budgets

New features, resource, service, fields, and enums

Added support for waterfall channel prioritization and budget caps on campaign budgets, which let you control how you allocate a budget across network channels (Google Owned and Operated properties, the Search Partner Network, and the Google Display Network). For more information, see the channel prioritization and budget allocation blog post.

Added the CampaignBudget.budget_network_settings field of type BudgetNetworkSettings, which holds at most one BudgetNetworkSetting message per advertising channel type (advertising_channel_type) in the BudgetNetworkSettings.settings field. Each setting assigns network channels (NetworkChannelType: OWNED_AND_OPERATED, SEARCH_PARTNER, and GOOGLE_DISPLAY) to priority tiers (ChannelPriorityTier: TIER1 and TIER2) in the BudgetNetworkSetting.channel_priorities field (of type ChannelPriorityConfig). A setting can also cap the share of the budget that secondary-tier network channels spend in the BudgetNetworkSetting.budget_caps field (of type BudgetCapConfig). The BudgetCapConfig.cap_percent_millis field specifies the cap in milli-percent units (1,000 = 1%, 100,000 = 100%, and 0 = 0% opt-out). When unset, the customer-level defaults in the CustomerBudgetNetworkSetting resource apply.

Added the read-only CampaignBudget.budget_network_eligibility field of type BudgetNetworkEligibility, which indicates whether a budget is eligible (eligible) for waterfall prioritization and budget caps and, if not, the ineligibility reasons (ineligible_reasons of type BudgetNetworkIneligibleReason).

Added the CustomerBudgetNetworkSetting resource, a singleton per customer with the resource name customers/{customer_id}/customerBudgetNetworkSettings. Its budget_network_settings field of type BudgetNetworkSettings holds the defaults that apply to every campaign budget whose CampaignBudget.budget_network_settings field is unset.

Added the CustomerBudgetNetworkSettingService service with the CustomerBudgetNetworkSettingService.MutateCustomerBudgetNetworkSetting method to create or update the setting. You can also mutate the resource through the GoogleAdsService.Mutate method and query it through the GoogleAdsService.Search and GoogleAdsService.SearchStream methods.

Added the BudgetNetworkSettingError enum, which the API returns when budget network settings are invalid.

Migrated Demand Gen campaign activation error

New enum and error

Added the DemandGenCampaignError enum with the DemandGenCampaignError.CANNOT_ACTIVATE_MIGRATED_CAMPAIGN error code. The API returns this error if you try to activate a migrated Demand Gen campaign before removing the original campaign, or while another migrated campaign for the same original campaign is active.

General

Local Services eligibility service and category details

New service, messages, and fields

Added the LocalServicesEligibilityService service with the LocalServicesEligibilityService.CheckLocalServicesEligibility method to check Local Services eligibility for a customer and Google Business Profile listing ID (CheckLocalServicesEligibilityRequest). The CheckLocalServicesEligibilityResponse message returns:

• eligible: Indicates whether the customer is eligible for Local Services.
• eligible_goals (of type EligibleGoal): Maps each eligible lead type (EligibleGoal.lead_type) to its eligible service categories (EligibleGoal.categories of type EligibleCategory), including each category's ID (category_id), display name (display_name), available job type IDs (job_types), and business callout IDs (callouts).
• suggestion_reasons (of type SuggestionReason): Provides short and detailed text reasons (short_text and long_text) explaining eligibility issues (such as licensing issues).

Local Services external redemption provider settings

Updated field, new messages, and new fields

Updated the Customer.local_services_settings field from OUTPUT_ONLY to mutable. Also added the LocalServicesSettings.redemption_provider_info field of type RedemptionProviderInfo to configure the external redemption provider for a Local Services account. This message contains the required RedemptionProviderInfo.external_merchant_id field of type ExternalPartnerMerchantId, which holds either an integer (numeric_id) or a 1–50 character string (alphanumeric_id) merchant ID.

Recommendations

Optimize for new customers recommendation

New recommendation

Added the RecommendationType.OPTIMIZE_FOR_NEW_CUSTOMERS enum value and the following fields to support optimizing campaigns for new customer acquisition (with incremental conversion values expressed in standard units of the account's local currency, not in micros):

• Recommendation.optimize_for_new_customers_recommendation (of type OptimizeForNewCustomersRecommendation): Exposes the recommended_incremental_conversion_value field.
• ApplyRecommendationOperation.optimize_for_new_customers (of type OptimizeForNewCustomersParameters): Accepts the account_default_incremental_conversion_value and campaign_override_incremental_conversion_value fields when you apply the recommendation.

Reports

Reach reporting frequency buckets and metric state information

New metrics, message, and enum

Added the following metrics to the Metrics message, completing the set of N+ frequency buckets (1+ through 10+) for reach reporting:

• Metrics.unique_users_six_plus
• Metrics.unique_users_seven_plus
• Metrics.unique_users_eight_plus
• Metrics.unique_users_nine_plus

Also added the following ReachMetricInfo metrics to the Metrics message to provide additional state information (the ReachMetricInfo.reach_metric_states field of type ReachMetricState, such as when a value is suppressed for privacy or quality reasons) for each unique-users metric:

• Metrics.unique_users_info
• Metrics.unique_users_two_plus_info
• Metrics.unique_users_three_plus_info
• Metrics.unique_users_four_plus_info
• Metrics.unique_users_five_plus_info
• Metrics.unique_users_six_plus_info
• Metrics.unique_users_seven_plus_info
• Metrics.unique_users_eight_plus_info
• Metrics.unique_users_nine_plus_info
• Metrics.unique_users_ten_plus_info

Search top impression share and search click share support for hotel booking itinerary and vertical ads segments

Updated metrics and segments

Expanded support for the Metrics.search_top_impression_share and Metrics.search_click_share metrics so that you can select them with the following hotel booking itinerary and vertical ads segments:

• Segments.advance_booking_window
• Segments.length_of_booking
• Segments.start_date
• Segments.start_day_of_week
• Segments.user_set_dates
• Segments.vertical_ads_event_participant_display_names
• Segments.vertical_ads_hotel_class
• Segments.vertical_ads_listing
• Segments.vertical_ads_listing_brand
• Segments.vertical_ads_listing_city
• Segments.vertical_ads_listing_country
• Segments.vertical_ads_listing_region
• Segments.vertical_ads_listing_user_rating
• Segments.vertical_ads_listing_venue
• Segments.vertical_ads_partner_account
• Segments.vertical_ads_price_tier
• Segments.vertical_ads_rate_rule_id
• Segments.vertical_ads_rate_type
• Segments.vertical_ads_vertical

Targeting

Household income exclusions in Performance Max campaigns

Expanded support

Added support for household income exclusions in Performance Max campaigns. Exclude household income ranges by creating a negative CampaignCriterion resource with the income_range field set.

Original source

The following new features, updates, and breaking changes were added in Google Ads API v26, which is a major release.

See Upgrade to the latest version for guidance.

Breaking changes

Campaigns

Optional country_code field in LocalServicesPmaxCampaignSettings

Required field during Local Services Performance Max campaign creation (LocalServicesPmaxCampaignSettings.country_code)

Behavioral shift

Ensure you specify country_code (along with the newly required listing_id) when creating Local Services Performance Max campaigns.

Conversions

The enhanced_conversions_for_leads_enabled field in ConversionTrackingSetting (Customer.conversion_tracking_setting)

None

Removal

Use ConversionTrackingSetting.enablement_setting on Customer.conversion_tracking_setting instead to inspect the account-level Enhanced Conversions setting.

Targeting

Hotel-specific criterion fields in AdGroupBidModifier: hotel_date_selection_type hotel_advance_booking_window hotel_length_of_stay (min_nights and max_nights) hotel_check_in_day hotel_check_in_date_range

Vertical-agnostic criterion fields in AdGroupBidModifier: user_set_dates of type UserSetDatesInfo advance_booking_window of type AdvanceBookingWindowInfo length_of_booking of type LengthOfBookingInfo (min_days and max_days) start_day_of_week of type StartDayOfWeekInfo start_date_range of type StartDateRangeInfo

Rename / removal

Update references to use the vertical-agnostic criterion fields, which support targeting across travel verticals beyond hotels (such as Things to do). Criterion IDs, targeting behavior, and existing bid modifiers stay the same. Values for min_nights and max_nights carry over to min_days and max_days as they are.

HotelDateSelectionType and type of segments.user_set_dates

DateSelectionType

Rename / type change

Use DateSelectionType instead of HotelDateSelectionType.

Hotel-specific error reasons in CriterionError: HOTEL_LENGTH_OF_STAY_OVERLAPS_WITH_EXISTING_CRITERION HOTEL_ADVANCE_BOOKING_WINDOW_OVERLAPS_WITH_EXISTING_CRITERION HOTEL_CHECK_IN_DATE_RANGE_OVERLAPS_WITH_EXISTING_CRITERION HOTEL_CHECK_IN_DATE_RANGE_START_DATE_TOO_EARLY HOTEL_CHECK_IN_DATE_RANGE_END_DATE_TOO_LATE HOTEL_CHECK_IN_DATE_RANGE_REVERSED

Vertical-agnostic error reasons in CriterionError: LENGTH_OF_BOOKING_OVERLAPS_WITH_EXISTING_CRITERION ADVANCE_BOOKING_WINDOW_OVERLAPS_WITH_EXISTING_CRITERION START_DATE_RANGE_OVERLAPS_WITH_EXISTING_CRITERION START_DATE_RANGE_START_DATE_TOO_EARLY START_DATE_RANGE_END_DATE_TOO_LATE START_DATE_RANGE_REVERSED

Rename

Update error handling to check for the new vertical-agnostic error reasons.

Features and updates (non-breaking)

Assets

LINE and SMS business message providers

New fields and enum values

Added support for LINE and SMS as message providers in BusinessMessageAsset, including new fields BusinessMessageAsset.line_info and BusinessMessageAsset.sms_info along with BusinessMessageProvider.LINE and BusinessMessageProvider.SMS.

AssetGroupError.UNSUPPORTED_LOCAL_SERVICES_CATEGORY

New enum value / error

Added to AssetGroupError to indicate when a category specified in GoogleLocalServicesInfo (AssetGroup.google_local_services_info) is not supported for Local Services Performance Max campaigns.

Campaigns

Local Services Performance Max campaign creation

New features, fields, and error

Updated PmaxCampaignSettings.local_services_enabled from OUTPUT_ONLY to IMMUTABLE, allowing external API clients to specify local_services_enabled = true when creating new Local Services Performance Max campaigns. Also added LocalServicesPmaxCampaignSettings.listing_id to expose the Google Business Profile listing ID linked to the Local Services Performance Max campaign (marked as REQUIRED during Local Services Performance Max campaign creation), and added the CampaignError.INVALID_LOCAL_SERVICES_PERFORMANCE_MAX_LISTING_ID error code.

Local Services campaign validation errors

New enum values and errors

Added new validation errors for Local Services campaigns: CampaignError: LOCAL_SERVICES_MULTIPLE_PERFORMANCE_MAX_CAMPAIGNS_NOT_ALLOWED LOCAL_SERVICES_AGREEMENT_REQUIRED AssetSetLinkError: LOCATION_ASSET_DOES_NOT_MATCH_CAMPAIGN_LISTING_ID CampaignConversionGoalError and CampaignGoalConfigError: CANNOT_UNLINK_LOCAL_SERVICES_GOAL_FROM_LOCAL_SERVICES_CAMPAIGN GOAL_NOT_ALLOWED_FOR_LOCAL_SERVICES_CAMPAIGN LOCAL_SERVICES_GOAL_NOT_ALLOWED_FOR_NON_LOCAL_SERVICES_CAMPAIGN ConversionGoalCampaignConfigError: CANNOT_DISABLE_CAMPAIGN_OVERRIDE_GOALS_FOR_LOCAL_SERVICES_CAMPAIGN

Hotel Center account link validation

New enum value / error

Added the CampaignError.HOTEL_PROPERTY_ASSET_SET_HOTEL_CENTER_LINK_REQUIRED error code to CampaignError to indicate that linking a hotel property asset set (Campaign.hotel_property_asset_set) to a Performance Max for travel goals campaign requires an active Hotel Center account link.

Demand Gen minimum budget per day

New field

Added the field demand_gen_info.minimum_budget_per_day_micros to CurrencyConstant, which specifies the minimum required budget per day for Demand Gen campaigns in that currency. This field's value updates when the minimum budget enforced by the API changes.

Lift measurement config for campaigns

New field

Added Campaign.lift_measurement_config to expose the resource name of the lift measurement configuration linked to the campaign.

AI Max experiment validation

New enum value / error

Added the ExperimentArmError.ADOPT_AI_MAX_CAMPAIGN_ALREADY_ENABLED error code to ExperimentArmError when attempting to create an ADOPT_AI_MAX experiment for a campaign that already has AI Max enabled (or is enabled within the same request prior to experiment arm creation).

Shopping campaign listing type

Expanded support

Expanded support of Campaign.listing_type to Shopping campaigns.

EU political advertising self-declaration updates

Updated behavior and new fields

Campaign.contains_eu_political_advertising is now optional for some campaigns that don't positively target the European Union. Except as noted for DEMAND_GEN campaigns with upgraded targeting, the field is optional if a campaign satisfies all of the following conditions after the request is executed:

• Contains no positive location campaign criterion that is inside the EU
• Contains no positive proximity or location group campaign criterion
• Contains at least one positive location campaign criterion that is outside of the EU

For DEMAND_GEN campaigns with upgraded_targeting, the field is optional if every active ad group within the campaign satisfies all of the following conditions after the request is executed:

• Contains no positive location ad group criterion that is inside the EU
• Contains no positive proximity or location group ad group criterion
• Contains at least one positive location ad group criterion that is outside of the EU

The field is also optional for campaigns with no active ad groups. If a request creates an ad group that does not meet these conditions, AdGroupError.MISSING_EU_POLITICAL_ADVERTISING_SELF_DECLARATION is returned. These changes apply to both new and existing campaigns. In some cases a new campaign can only be created if criteria are added in the same request — use GoogleAdsService.Mutate to group mutates.

Updated Campaign.missing_eu_political_advertising_declaration to match the changes to Campaign.contains_eu_political_advertising. Added GeoTargetConstant.require_eu_political_advertising_declaration to indicate if a location is within or outside of the EU. Added CampaignCriterion.require_eu_political_advertising_declaration and AdGroupCriterion.require_eu_political_advertising_declaration.

Campaign.contains_eu_political_advertising is required if this field is true for any campaign-level criterion within the campaign (or for any active ad-group-level criterion in DEMAND_GEN campaigns with upgraded targeting). The fields return true if the criterion's negative field is false and the criterion is a location within the EU, a proximity (regardless of whether it overlaps with EU territory), or a location group (regardless of whether it overlaps with EU territory).

Conversions

Unified Enhanced Conversions configuration

New fields and enum

Added ConversionTrackingSetting.enablement_setting and ConversionTrackingSetting.effective_enablement_setting (on Customer.conversion_tracking_setting) to expose the unified Enhanced Conversions configuration for the account, represented using the new EnhancedConversionsConfig enum.

ConversionActionCategory.MESSAGE_LEAD

New enum value

Added to ConversionActionCategory to support message or chat interactions indicating interest in an advertiser's offering.

ConversionAttributionEventType.CLICK

New enum value

Added to ConversionAttributionEventType to represent conversions attributed to an ad click, which were previously included in the UNKNOWN enum value.

General

Local Services leads updates

New field and enum value

Added the LocalServicesLead.campaign field to the LocalServicesLead resource to link a lead to its associated campaign. Added COUPON to LocalServicesLeadType to support coupon lead types for Local Services.

Recommendations

Raise budget recommendation for Search

New recommendation

Added RecommendationType.RAISE_BUDGET_PERFORMANCE_TOO_LOW, Recommendation.raise_budget_performance_too_low_recommendation, and ApplyRecommendationOperation.raise_budget_performance_too_low to support raising budgets when daily budgets are too low for Search campaigns.

Reports

Search Lift measurements

New features, resource, segments, and metrics

Added support for Search Lift measurements: Added a new read-only resource SearchLiftKeywordBundle representing a keyword bundle in a Search Lift study. Added new selectable segments (segments.search_lift_keyword_bundle and segments.search_property) and 15 new Search Lift metrics (such as relative_search_lift, normalized_incremental_searches, search_lift_cost_micros, and search_lift_impressions) to support Search Lift analysis with LiftMeasurementConfig (linked to campaigns using Campaign.lift_measurement_config). Added the SearchLiftKeywordBundleStatus, SearchLiftMatchingInfoSource, and SearchLiftSearchProperty enums.

Final URL expansion asset view for Shopping campaigns

Expanded support

Expanded final_url_expansion_asset_view to support Shopping campaigns (with ad_group selectable as an attributed resource alongside final_url_expansion_asset_view.ad_group).

Videos

YouTube generative content disclosures

New fields and enum

Added support for generative content disclosures for YouTube uploads. The new field YouTubeVideoUpload.video_content_metadata of type VideoContentMetadata has been added to YouTubeVideoUpload, containing disclosure settings under VideoContentMetadata.generative_content_disclosure of type YouTubeVideoUploadGenerativeContentDisclosure.

Original source

Assets

URL options for Asset Group

• Added support for URL options on AssetGroup, allowing advertisers to specify tracking templates, custom parameters, and final URL suffixes at the asset group level: AssetGroup.tracking_url_template: URL template for constructing a tracking URL. AssetGroup.url_custom_parameters: A list of mappings to be used for substituting URL custom parameter tags in tracking_url_template, final_urls, or final_mobile_urls. AssetGroup.final_url_suffix: URL template for appending parameters to landing page URLs served with parallel tracking.

Campaigns

Automated video crawl info

• Added AutomatedVideoCrawlSetting to Campaign.AssetAutomationSetting, along with AssetAutomationType.AUTOMATED_VIDEO_CRAWL, allowing you to specify the automated video crawl settings for a Performance Max campaign. AutomatedVideoCrawlSetting.automated_video_crawl_infos contains a list of AutomatedVideoCrawlInfo entries, each configuring a crawl url, source_platform (VideoCrawlSourcePlatform: LANDING_PAGE, SOCIAL, or YOUTUBE), and enabled opt-in status.

Customer Lifecycle Optimization value multiplier errors

• Added new validation error reasons when configuring value multipliers (value_multiplier and high_lifetime_value_multiplier) for Customer Lifecycle Optimization: GoalError: HIGH_LIFETIME_VALUE_MULTIPLIER_PRESENT_BUT_VALUE_MULTIPLIER_ABSENT HIGH_LIFETIME_VALUE_MULTIPLIER_LESS_THAN_OR_EQUAL_TO_VALUE_MULTIPLIER CampaignGoalConfigError: HIGH_LIFETIME_VALUE_MULTIPLIER_PRESENT_BUT_VALUE_MULTIPLIER_ABSENT HIGH_LIFETIME_VALUE_MULTIPLIER_LESS_THAN_OR_EQUAL_TO_VALUE_MULTIPLIER CAMPAIGN_OVERRIDE_HIGH_LIFETIME_VALUE_MULTIPLIER_NOT_SUPPORTED_FOR_CAMPAIGN_TYPE

SmartCampaignSettingService.GeneratePMaxDraftCampaign

• Added SmartCampaignSettingService.GeneratePMaxDraftCampaign to support generating a Performance Max draft campaign from an existing Smart campaign, initialized with a status of CampaignStatus.PAUSED and a creation status of CampaignCreationStatus.INCOMPLETE (see Convert smart campaigns to PMax campaigns): Set GeneratePMaxDraftCampaignRequest.validate_only to true to validate the conversion and receive any validation warnings or conversion issues in GeneratePMaxDraftCampaignResponse.validated_info without creating the draft campaign. (Leave gbp_enabled and image_enabled unset or false; setting them to true is not yet supported and returns SmartCampaignError.GBP_ENABLED_GENERATE_PMAX_NOT_SUPPORTED or SmartCampaignError.IMAGE_ENABLED_GENERATE_PMAX_NOT_SUPPORTED.) GeneratePMaxDraftCampaignResponse returns the resource names of the generated entities (pmax_campaign, campaign_budget, asset_group, and assets) along with validated_info.

Conversions

Firebase ad impressions

• Exposed FIREBASE_ANDROID_APP_AD_IMPRESSION and FIREBASE_IOS_APP_AD_IMPRESSION conversion action types, allowing you to retrieve and modify these conversion actions. Also exposed the IN_APP_AD_REVENUE category in ConversionActionCategory to track in-app ad monetization revenue.

General

BusinessProfileLocationSyncError

• Added reasons for the Business Profile location sync errors when syncing locations in a LOCATION_SYNC-typed AssetSet. Instead of returning a generic UNKNOWN error, the API now returns BusinessProfileLocationSyncError with specific reasons (EMAIL_INVALID, OAUTH_TOKEN_INVALID, ACCOUNT_REMOVED, and NO_PERMISSION_TO_ACCESS_LOCATION_ACCOUNT).

Planning

BenchmarksService.GenerateBenchmarksMetrics percentile metrics

• Updated BenchmarksService.GenerateBenchmarksMetrics to provide metrics representing the customer's competitive standing among other advertisers in percentile tier format. Metrics are returned in PercentileMetrics on the new CustomerMetrics.percentile_metrics field (on both GenerateBenchmarksMetricsResponse.customer_metrics and BreakdownMetrics.customer_metrics) and represented using BenchmarksCustomerPercentileTier. CustomerMetrics.percentile_metrics is only populated when both of the following conditions are met in GenerateBenchmarksMetricsRequest: PERCENTILE_DATA is requested in supplemental_data. BenchmarksSource.all_advertisers is set on benchmarks_source (which also requires specifying category_filter). Added support for percentile metrics for open quarter dates within ListBenchmarksAvailableDatesResponse.supported_dates (returned by BenchmarksService.ListBenchmarksAvailableDates). While customer aggregate metrics (CustomerMetrics.aggregate_metrics), customer rate metrics (CustomerMetrics.average_rate_metrics), and customer percentile metrics (CustomerMetrics.percentile_metrics) are supported across all dates in supported_dates (including open quarters), customer share metrics (CustomerMetrics.share_metrics) and rate metrics of the benchmarks source (average_benchmarks_metrics, such as average_cpm of "/Apparel/Clothing" ads) are not supported for open quarters and are omitted from the response unless the requested date_range falls within the narrower ListBenchmarksAvailableDatesResponse.supported_dates_for_all_metrics range.

• Added a custom BenchmarksError.NO_METRICS_FOUND error that indicates no metrics were found for the selected combination of inputs to improve usability.

YouTube channel handles for creator insights

• Updated ContentCreatorInsightsService.GenerateCreatorInsights to support searching by YouTube channel handles using YouTubeChannels.youtube_channel_handles (valid channel handles must start with @, such as @channel_handle). This option is similar to searching by YouTube channel IDs. The response contains insights on the requested YouTube creators.

Recommendations

CPA and ROAS bid recommendations

• Added Recommendation.raise_target_cpa_performance_bid_too_low_recommendation (RAISE_TARGET_CPA_PERFORMANCE_BID_TOO_LOW) and Recommendation.lower_target_roas_performance_bid_too_low_recommendation (LOWER_TARGET_ROAS_PERFORMANCE_BID_TOO_LOW), along with ApplyRecommendationOperation.raise_target_cpa_performance_bid_too_low and ApplyRecommendationOperation.lower_target_roas_performance_bid_too_low, to support raising Target CPA or lowering Target ROAS when bids are too low for Search campaigns to enter auctions: RaiseTargetCpaPerformanceBidTooLowRecommendation provides recommended_target_multiplier (a factor greater than 1.0) and current_average_target_cpa_micros; apply it using RaiseTargetCpaPerformanceBidTooLowParameters with target_cpa_multiplier. LowerTargetRoasPerformanceBidTooLowRecommendation provides recommended_target_multiplier (a factor less than 1.0) and current_average_target_roas; apply it using LowerTargetRoasPerformanceBidTooLowParameters with target_roas_multiplier.

Reports

Hotel itinerary dimension segments

• Added the following hotel and travel booking itinerary dimension segments to Segments (selectable with campaign, ad_group, and customer): Segments.advance_booking_window: Advance booking window for the itinerary in days. Segments.length_of_booking: Length of booking for the itinerary in days. Segments.start_date: Start date of the booking formatted as yyyy-MM-dd. Segments.start_day_of_week: Start day of week (DayOfWeek) of the booking. Segments.user_set_dates: Indicates whether user-specified dates were selected (HotelDateSelectionType).

Vertical ads metrics

• Added the following metrics for hotel and travel vertical ads reporting to Metrics (selectable with campaign, ad_group, and customer): Metrics.vertical_ads_average_booking_value_micros: Click-weighted average daily rate in micros, including taxes and fees, over the total length of stay for hotel bookings. Metrics.vertical_ads_potential_impressions: Total view-capped eligible impressions available across the query context. Metrics.vertical_ads_price_difference_percentage: Percentage delta comparing the advertiser's offered price against the lowest competing price for the same property.

Vertical ads segments

• Added the following segments for hotel and travel vertical ads reporting to Segments (selectable with campaign, ad_group, and customer): Segments.vertical_ads_price_tier: Advertiser's price tier (HotelPriceBucket) compared to competitors in the auction. Segments.vertical_ads_rate_rule_id: The rate rule ID associated with the advertiser's rate rule. Segments.vertical_ads_rate_type: Rate type (HotelRateType) of the hotel booking.

Original source

The following new features and updates were added in Google Ads API v25.1. Minor versions like v25.1 don't contain breaking changes.

Assets

AssetFieldType.TEXT_DISCLAIMER ServedAssetFieldType.TEXT_DISCLAIMER

New enum values

Added support for text disclaimer assets.

Campaigns

Campaign.aca_migration_date_time Campaign.broad_match_migration_date_time

New fields

Track the upcoming auto-migration to AI Max.

Conversions

Brand Lift measurements

New features

Added support for Brand Lift measurements with the following updates:

• Added new read-only dimensional resources for lift study results: LiftMeasurementAgeRange, LiftMeasurementCampaign, LiftMeasurementDevice, LiftMeasurementGender, and LiftMeasurementVideo.
• Added new segments and metrics to support Brand Lift analysis with LiftMeasurementConfig and the new dimensional resources.
• Added the following enums: BrandLiftMeasurementType, LiftMeasurementFlightStatus, SurveyIntendedAction, SurveyLiftFlightTargetResponseMode, and SurveySubjectType.

Conversion Lift measurements

New features

Added support for Conversion Lift measurements with the following updates:

• Added a new read-only resource LiftMeasurementConfig representing a lift study.
• Added new selectable segments to segment and filter lift results.
• Added 24 new Conversion Lift metrics and winner score metrics supporting detailed statistical analysis of lift performance.
• Added support to retrieve campaign details and conversion goals.
• Added a new optional field Experiment.lift_measurement_config.
• Added the ConversionLiftIncludedConversionActionTypes enum.

LiftMeasurementFlight

New resource

A new read-only resource representing flight details for a lift measurement configuration, including measured flight start and end dates (start_date and end_date).

General

SmartCampaignError

New enum values

Added new specific error codes for Performance Max generation constraints:

• VALIDATE_ONLY_GENERATE_PMAX_NOT_SUPPORTED
• GBP_ENABLED_GENERATE_PMAX_NOT_SUPPORTED
• IMAGE_ENABLED_GENERATE_PMAX_NOT_SUPPORTED

AuthorizationErrorEnum.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION

New enum value / error

Returned when a Google Cloud project with TEST access level attempts to make requests against a non-test account.

Planning

Brand sentiment insights

New features

Added support for brand sentiment insights in ContentCreatorInsightsService:

• Added the BrandSentimentInsight, SentimentInsightDistribution, and SentimentInsightSummary messages.
• Added the Sentiment enum.
• Added the BRAND_SENTIMENT_DATA value to the ContentCreatorInsightsSupplementalData enum.
• Added the BRAND value to the InsightsKnowledgeGraphEntityCapabilities enum.

BenchmarksService enhancements

New features

Added support for categories as filters for scoping a benchmarks analysis. Also supported additional business critical metrics:

• Added an option to benchmark against all advertisers running ads in one or more Product & Service Categories using BenchmarksService.GenerateBenchmarksMetrics and the category_filter.
• Surfaced more customer ad metrics, such as the customer's aggregate cost and views, and share metrics such as share_of_voice. Metrics are returned using AggregateMetrics and ShareMetrics.
• The list of supported categories can be retrieved using BenchmarksService.ListBenchmarksSources with the CATEGORY source type.

Parental status targeting

New feature

Added support for parental status targeting in reach planning. Added the new field parental_statuses to Targeting for service ReachPlanService.GenerateReachForecast, and parental_statuses to PlannableTargeting for service ReachPlanService.ListPlannableProducts.

Recommendations

Recommendation.campaign_specific_app_goal_recommendation

New recommendation

Suggests adding a campaign-specific app conversion goal. The new EffectiveAutomaticGoal resource is used to represent current goals within this recommendation.

Reports

Metrics.original_conversion_value

New field

Represents the original conversion value from biddable conversions. This is the unadjusted value of conversions before any value rule adjustments, such as conversion value rules or lifecycle goals adjustments, are applied.

Loyalty membership stats

New features

Added support for segmenting stats by user loyalty membership program status, and added loyalty membership primary dimension for conversion value rules:

• Added the Segments.loyalty_membership segment to support segmenting report metrics by the loyalty program tier of the converting user.
• Added the LOYALTY_MEMBERSHIP primary dimension to identify when a loyalty membership condition was satisfied for a conversion value rule.

Targeting

vertical_ads_item_bid

New criterion type

Added the new vertical_ads_item_bid criterion type to AdGroupCriterion.criterion.

Original source

The following new features, updates, and breaking changes were added in Google Ads API v25, which is a major release.

See Upgrade to the latest version for guidance.

Breaking changes

• Campaigns

  • Standalone fields additional_value and additional_high_lifetime_value in CustomerLifecycleOptimizationValueSettings
    • Part of value_adjustment and high_lifetime_value_adjustment oneofs respectively, alongside the new value_multiplier and high_lifetime_value_multiplier fields
    • Update references to these fields as they are now part of oneofs.
  • Legacy CustomerLifecycleGoal and CampaignLifecycleGoal resources, their corresponding services CustomerLifecycleGoalService and CampaignLifecycleGoalService, and legacy settings/enums (CustomerAcquisitionGoalSettings, CustomerAcquisitionOptimizationModeEnum, LifecycleGoalValueSettings)
    • Removal
    • Use the revamped unified goals schema: Use the new_customer_acquisition_goal_settings field in the Goal resource. Use the campaign_new_customer_acquisition_settings field in the CampaignGoalConfig resource to configure campaign-specific overrides.
  • Nested enum fields in Incentive Service request and response messages: FetchIncentiveRequest.type Incentive.type IncentiveOffer.type
    • Use the new standalone enum fields instead of the legacy type fields.
  • Optional selected_incentive_id and customer_id fields in ApplyIncentiveRequest
    • Behavioral shift
    • Ensure you provide both fields when calling ApplyIncentive.
  • The consumer email address field ContactDetails.email in the LocalServicesLead resource
    • Removal
    • Remove references to this field because it is no longer supported.
  • Optional allowed_domain field in AdvertisingPartnerLinkInvitationProperties
    • Required field when calling CreateProductLinkInvitation for an advertising partner
    • Ensure you provide allowed_domain when creating a product link invitation for an advertising partner.

• Planning

  • The search_brand field in GenerateCreatorInsightsRequest
    • Removal
    • Use search_topics instead.
  • The plannable_location_id field in Targeting and cookie_frequency_cap field in GenerateReachForecastRequest
    • Removal
    • Switch to using plannable_location_ids and cookie_frequency_cap_setting.

• Reports

  • customer_metrics field in GenerateBenchmarksMetricsResponse and BreakdownMetrics of type Metrics
    • Type change / behavioral shift
    • Update your integrations to use the new CustomerMetrics type, which only contains metrics representing the customer's ad performance.

Features and updates (non-breaking)

• Ads

  • AssetAutomationType.GENERATE_ANIMATED_IMAGES_FROM_OTHER_ASSETS
    • Available for DemandGenMultiAssetAds. If enabled, it generates animated images using non-animated images as input. New DemandGenMultiAssetAds are opted in by default starting with this API version.
  • Synthetic content info mutability
    • Asset.synthetic_content_info and Ad.synthetic_content_info are now fully mutable in v25, v24, and v23.

• Campaigns

  • Loyalty Retention Goal
    • Added support for Loyalty Retention Goal, which allows advertisers to optimize campaigns for retaining loyalty program members. Added LOYALTY_RETENTION to the GoalType enum. Added CampaignGoalConfig.campaign_loyalty_retention_settings to configure campaign-specific loyalty retention settings, including bid adjustments and showing member benefits in PLA format. Added Goal.loyalty_retention_goal_settings to configure account-level loyalty retention goal settings. Added new error codes: LOYALTY_RETENTION_GOAL_INVALID_MODE CANNOT_USE_INCOMPATIBLE_CLO_GOALS LOYALTY_RETENTION_GOAL_ALREADY_EXISTS
  • New Customer Acquisition Goal
    • Updated New Customer Acquisition Goal support in the Google Ads API to reflect the revamped unified goals schema: Extended the Goal resource to support New Customer Acquisition settings using the new_customer_acquisition_goal_settings field. Extended the CampaignGoalConfig resource to support campaign-specific overrides for New Customer Acquisition using the campaign_new_customer_acquisition_settings field. Added the new CustomerLifecycleOptimizationGoalSubType enum to define supported goal subtypes. Added NEW_CUSTOMER_ACQUISITION to the GoalType enum. Added new validation error reasons to GoalError: NEW_CUSTOMER_ACQUISITION_GOAL_ALREADY_EXISTS Added new validation error reasons to CampaignGoalConfigError: CAMPAIGN_OVERRIDE_VALUES_SET_FOR_NEW_CUSTOMER_ACQUISITION_TARGET_SPECIFIC_OPTION CAMPAIGN_OVERRIDE_HIGH_LIFETIME_VALUE_NOT_SUPPORTED_FOR_CAMPAIGN_TYPE CANNOT_USE_INCOMPATIBLE_CLO_GOALS Added ErrorDetails.incompatible_clo_goal_error_details to expose the new IncompatibleCloGoalsErrorDetails structure for validation errors.

• Conversions

  • YouTube third-party conversion attribution
    • Added support for YouTube conversion attribution verification using third-party partners: Added CustomerThirdPartyIntegrationPartners.conversion_attribution_integration_partners to allow configuring integration partners at the customer level. Added CampaignThirdPartyIntegrationPartners.conversion_attribution_integration_partners to allow configuring integration partners at the campaign level. See the Help Center article to learn more.

• General

  • ContactDetails.phone_number_extension
    • Added to the LocalServicesLead resource.
  • IncentiveError
    • Added new specific error codes for incentive redemption failures: BILLING_COUNTRY_NOT_ELIGIBLE (the customer's billing country is not eligible for the incentive) USER_IS_MCC_MANAGER (the user is a manager account and cannot redeem the incentive) USER_SUSPENDED (the customer account is suspended) MAX_PENDING_INCENTIVES (the customer has reached the maximum number of pending incentives) ACCOUNT_HAD_RECENT_SPEND (the account had recent spend and is not eligible) MAX_INCENTIVES_REDEEMED_FROM_OFFER (the customer has already redeemed the maximum number of incentives from this offer) MISMATCHING_BILLING_COUNTRY_CODE (the billing country code provided in the request does not match the customer's account country)

• Planning

  • YouTube channel details in trending insights
    • Added support for more YouTube channel details of related videos when searching trending insights. Added the new fields channel_id, channel_name, and channel_url to YouTubeVideoAttributeMetadata.

• Reports

  • ad_sub_format_type
    • Provides a breakdown of YouTube instream non-skippable ads by duration: INSTREAM_NON_SKIPPABLE_STANDARD (standard duration instream non-skippable ad) INSTREAM_NON_SKIPPABLE_MAX30_SEC (instream non-skippable ad no longer than 30.99 seconds) INSTREAM_NON_SKIPPABLE_MAX60_SEC (instream non-skippable ad no longer than 60.99 seconds) This segment must always be selected together with ad_format_type. It is selectable with AdGroup, AdGroupAd, Campaign, Customer, Video, and VideoEnhancement.
  • Video-specific social metrics
    • Added video-specific social metrics to help advertisers track user engagement (comments, likes, and shares) for Shorts ads on YouTube: Metrics.youtube_comments Metrics.youtube_likes Metrics.youtube_shares They are available in AdGroup, AdGroupAd, Asset, Campaign, Customer, and Video.

Original source

The following new features and updates were added in Google Ads API v22.2. Minor versions like v22.2 don't contain breaking changes.

Features and updates

• General
  • Asset.synthetic_content_info Ad.synthetic_content_info
    • New fields
    • Contain attestations for synthetic/AI-generated content, split into advertiser_attestation (declarations provided directly by the advertiser) and system_attestation (attestations automatically detected or provided by Google's systems). To help you plan your upcoming integration work for v25, the interface for mutating advertiser attestation fields is being introduced early for v22 and higher. The interface is visible in these versions, but synthetic_content_info.advertiser_attestation.status and synthetic_content_info.advertiser_attestation.source will remain immutable for these versions. If you attempt a mutate request on either of these fields, one of these errors will be returned: "The field attempted to be mutated is immutable" or "Field cannot be set". These fields will become fully mutable starting in v25. We recommend using the interface now to build and test your internal logic so your system is ready for full write capabilities when v25 is launched.
• Multi-party approvals
  • New features
  • Added support for multi-party approvals (MPA) reviews: Added the MultiPartyAuthReview resource and corresponding MultiPartyAuthReviewService. Added the MultiPartyAuthReviewStatus enum to track the review status. Added CustomerUserAccess.pending_multi_party_auth_review to link to a pending review. Added MutateCustomerUserAccessResult.multi_party_auth_review and MutateCustomerUserAccessInvitationResult.multi_party_auth_review to return the associated review resource name. Added MultiPartyAuthReviewError for validation errors.

Original source

The following new features and updates were added in Google Ads API v24.2. Minor versions like v24.2 don't contain breaking changes.

Ads

AssetAutomationType.GENERATE_LANDING_PAGE_TEXT

New enum value

Generates text information from the landing page to be shown in the engagement panel for DemandGenVideoResponsiveAd instances (which are opted in by default starting with this API version).

Assets

AssetGroup.google_local_services_info

New field

Added to support Local Services Ads information (category ID and callouts) in Performance Max campaigns.

AssetGroupSignal.local_services_id

New field

Added to support Local Services Ads service ID signals in Performance Max campaigns.

AssetGroupSignal.vertical_ads_item_group_rule_list

New field

Added to support vertical ads item group rules for selecting items from attached vertical feeds in Performance Max campaigns. This feature is only available to accounts on the allowlist.

AssetGroupErrorEnum.CANNOT_REMOVE_ALL_ASSET_GROUPS_FROM_CAMPAIGN

New enum value / error

Returned when attempting to remove all asset groups from a campaign.

AssetGroupSignalErrorEnum.CANNOT_REMOVE_ALL_SIGNALS

New enum value / error

Returned when attempting to remove all signals from an asset group.

Campaigns

Campaign.PmaxCampaignSettings.local_services_pmax_campaign_settings

Campaign.PmaxCampaignSettings.local_services_enabled

New fields

Support identifying Local Services Performance Max campaigns.

AdGroup.DemandGenAdGroupSettings.DemandGenChannelControls.DemandGenSelectedChannels.maps

New field

Includes Google Maps in the selectable channels for Demand Gen ad groups.

CampaignCriterionErrorEnum.CANNOT_REMOVE_ALL_LOCATIONS_FROM_LOCAL_SERVICES_PMAX_CAMPAIGN

New enum value / error

Returned when attempting to remove all locations from a local services Performance Max campaign.

SmartCampaignErrorEnum.CREATION_FAILED

New enum value / error

Returned when attempting to create new Smart Campaigns.

Conversions

ConversionOrigin.LOCAL_SERVICES_ADS

ConversionActionType.LOCAL_SERVICES_ADS

New enum values

Represent conversions that occur when a user clicks on a local services ad and calls, messages, or books the advertiser.

Experiments

COMPARE_CAMPAIGNS

PMAX_TEXT_CUSTOMIZATION_FINAL_URL_EXPANSION

New enum values

Added support for new ExperimentType types:

• COMPARE_CAMPAIGNS: For campaign mix experiments and custom Performance Max experiments that compare multiple campaigns of the same or different types in a single experiment.
• PMAX_TEXT_CUSTOMIZATION_FINAL_URL_EXPANSION: For Performance Max optimization experiments for text customization and Final URL expansion.

General

Asset.synthetic_content_info

Ad.synthetic_content_info

New fields

Contain attestations for synthetic/AI-generated content, split into advertiser_attestation (declarations provided directly by the advertiser) and system_attestation (attestations automatically detected or provided by the system). This feature has been backported to v23 and v22. To help you plan your upcoming integration work for v25, the interface for mutating advertiser attestation fields is being introduced early for v22 and higher. The interface is visible in these versions, but synthetic_content_info.advertiser_attestation.status and synthetic_content_info.advertiser_attestation.source will remain immutable for these versions. If you attempt a mutate request on either of these fields, one of these errors will be returned: "The field attempted to be mutated is immutable" or "Field cannot be set". These fields will become fully mutable starting in v25. We recommend using the interface now to build and test your internal logic so your system is ready for full write capabilities when v25 is launched.

Multi-Party Authorization

New features

Added support for Multi-Party Authorization (MPA) reviews:

• Added the MultiPartyAuthReview resource and corresponding MultiPartyAuthReviewService.
• Added the MultiPartyAuthReviewStatus enum to track the review status.
• Added CustomerUserAccess.pending_multi_party_auth_review to link to a pending review.
• Added MutateCustomerUserAccessResult.multi_party_auth_review and MutateCustomerUserAccessInvitationResult.multi_party_auth_review to return the associated review resource name.
• Added MultiPartyAuthReviewError for validation errors.

This feature has been backported to v23.3, v22.2, and v21.2.

IncentiveService.FetchIncentive

Behavioral change

When an invalid email address is provided in the request, the method now gracefully falls back to returning the default incentive offers instead of throwing an AuthenticationError.INVALID_EMAIL_ADDRESS error.

Planning

GenerateCreatorInsightsRequest.search_topics

New field

Added to the ContentCreatorInsightsService.GenerateCreatorInsights service. This option searches for creators talking about a topic in the country specified in country_locations (supports searching for one country only).

CREATOR_TOPIC_INSIGHTS

New enum value

Added to InsightsKnowledgeGraphEntityCapabilities to signify entities for searching creators talking about a topic. These entities should be used in the search_topics field. Retrieved using AudienceInsightsService.ListAudienceInsightsAttributes.

KnowledgeGraphEntitySearchOptions

New type / options

Contains additional search options for topics in ListAudienceInsightsAttributes, including options to retrieve all topics supported as creator attributes, and filtering by capabilities.

GenerateCreatorInsightsRequest.supplemental_data

GenerateTrendingInsightsRequest.supplemental_data

New fields

Optional inputs to the ContentCreatorInsightsService methods. Supplying this field populates additional locations or creator attributes in the response.

local_creator_insights

related_local_creators

New fields

Populated when supplemental_data contains the LOCAL_CREATOR_DATA enum. Exposes local creators viewed in or based in the chosen country who consented to share location data.

GenerateTrendingInsightsRequest.sub_country_locations

New field

Added to ContentCreatorInsightsService.GenerateTrendingInsights, allowing searches for trending insights using country location and sub country locations.

Reports

PerformanceMaxPlacementView

Segments extension

Made segmentable by ad_network_type.

Shopping

Campaign.ShoppingSetting.ignore_brand_exclusion_in_shopping_ads

New field

If true, brand exclusions are ignored for Shopping ads. Only supported for Shopping campaigns.

Targeting

CriterionErrorEnum.CANNOT_TARGET_LANGUAGE

New enum value / error

Returned when attempting to target a language that is not allowed.

Videos

DataLink.youtube_link_metadata

New field

Contains brand_channel_id to specify the ID of the linked YouTube brand channel.

Original source

The following new features and updates were added in Google Ads API v23.3. Minor versions like v23.3 don't contain breaking changes.

Features and updates

• General

  • Asset.synthetic_content_info Ad.synthetic_content_info
    • New fields
    • Contain attestations for synthetic/AI-generated content, split into advertiser_attestation (declarations provided directly by the advertiser) and system_attestation (attestations automatically detected or provided by Google's systems). To help you plan your upcoming integration work for v25, the interface for mutating advertiser attestation fields is being introduced early for v22 and higher. The interface is visible in these versions, but synthetic_content_info.advertiser_attestation.status and synthetic_content_info.advertiser_attestation.source will remain immutable for these versions. If you attempt a mutate request on either of these fields, one of these errors will be returned: "The field attempted to be mutated is immutable" or "Field cannot be set". These fields will become fully mutable starting in v25. We recommend using the interface now to build and test your internal logic so your system is ready for full write capabilities when v25 is launched.

• Multi-party approvals

  • New features
  • Added support for multi-party approvals (MPA) reviews: Added the MultiPartyAuthReview resource and corresponding MultiPartyAuthReviewService. Added the MultiPartyAuthReviewStatus enum to track the review status. Added CustomerUserAccess.pending_multi_party_auth_review to link to a pending review. Added MutateCustomerUserAccessResult.multi_party_auth_review and MutateCustomerUserAccessInvitationResult.multi_party_auth_review to return the associated review resource name. Added MultiPartyAuthReviewError for validation errors.

Original source

The following new features and updates were added in Google Ads API v23.3. Minor versions like v23.3 don't contain breaking changes.

Features and updates include:

• Added attestations for synthetic/AI-generated content, split into advertiser_attestation and system_attestation.
• Added support for multi-party approvals (MPA) reviews (beta).
• Added new fields and enums for MultiPartyAuthReview and related services.
• Added new error codes for validation errors related to multi-party auth reviews.

Original source

The following new features and updates were added in Google Ads API v24.1. Minor versions like v24.1 don't contain breaking changes.

Ads

DemandGenMultiAssetAdInfo.classic_display_images

New field

Custom uploaded display images served without requiring extra responsive assets.

Experiments

ADOPT_AI_MAX ADOPT_BROAD_MATCH_KEYWORDS OPTIMIZE_ASSETS PMAX_REPLACEMENT_SHOPPING

New enum values

Added support for new ExperimentType types:

• ADOPT_AI_MAX: For experiments that test how AI Max can help you engage more customers with Google AI and broad match keywords.
• ADOPT_BROAD_MATCH_KEYWORDS: For experiments that test how broad match keywords can impact the number of searches your ads appear in.
• OPTIMIZE_ASSETS: For custom experiments for optimizing assets.
• PMAX_REPLACEMENT_SHOPPING: For experiments that test how your Shopping campaigns perform compared to Performance Max.

Experiment.video_experiment

New field

Configuration support for existing YOUTUBE_CUSTOM experiments consisting of Video campaigns.

ExperimentArm.asset_testing_info ExperimentArm.asset_groups ExperimentArm.performance_max_experiment_arm_info

New fields

Exposes fields to support asset testing, asset groups, and Performance Max settings in experiment arms:

• asset_testing_info: Details of assets associated with the experimental copies of ads.
• asset_groups: List of asset groups in the experiment arm for Optimize Assets experiments.
• performance_max_experiment_arm_info: Settings for Performance Max campaigns in PMAX_REPLACEMENT_SHOPPING experiments.

General

CustomerUserAccess.passkey_enabled

New field

Read-only field indicating whether the user has a passkey enabled.

Reports

mobile_device_platform

New segment

Allows segmenting reports by the user device's platform (such as iOS or Android).

REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED

New enum value / error

Returned when the requested daily, hourly, or weekly time granularity is not supported for query date ranges (only available for the last 37 months).

vertical_ads_listing_user_rating vertical_ads_listing_venue

New segments

New segments to be used for vertical ads.

user_rating, venue, event_participant_display_name

New filter criteria

Supported filtering in VerticalAdsItemGroupRuleInfo for the SharedCriterion resource.

Control/treatment experiment metrics

New fields

Added control values (control_clicks, etc.), treatment values (clicks, etc.), point estimates (clicks_point_estimate, etc.), margins of error (clicks_margin_of_error, etc.), and p-values (clicks_p_value, etc.) across seven core metric families (Clicks, Impressions, Cost, Conversions, Cost per conversion, Conversion value, Conversion value per cost).

Conversions absolute change metrics

New fields

Support for Conversions absolute difference estimations using point estimate, margin of error, and p-value fields.

Targeting

CriterionErrorEnum.CANNOT_EXCLUDE_ALL_TARGETS

New enum value / error

Returned when attempting to exclude all demographics targets.

Videos

ThirdPartyViewabilityIntegrationPartnerEnum.ZEFR

New enum value

Published ZEFR as a third party viewability integration partner.

DataLink.youtube_video.channel_id

New field

Exposes the YouTube channel ID associated with the data link.

Original source

The following new features, updates, and breaking changes were added in Google Ads API v24, which is a major release.

See Upgrade to the latest version for guidance.

Breaking changes

Ads

Optional videos and logo_images in DemandGenVideoResponsiveAdInfo

Required fields

Behavioral shift

Provide videos and logo_images when creating or mutating responsive Demand Gen video ads.

Optional videos, business_name, and logo_images in VideoResponsiveAdInfo

Required fields

Behavioral shift

Provide videos, business_name, and logo_images when creating or mutating video responsive ads. Note that VideoResponsiveAdInfo is now mutable.

Campaigns

Campaign.video_brand_safety_suitability

None

Removal

Campaign-level suitability control is removed. Brand safety suitability is still available on the customer level. Use Customer.video_brand_safety_suitability instead.

Conversions

UserListCustomerTypeCategoryEnum.LOYALTY_SIGN_UPS

None

Removal

The loyalty sign ups user category has been removed. Remove code references to it.

Planning

InsightsAudienceAttributeGroup type for topic_audience_combinations

common.InsightsAudienceAttributeGroup type

Behavioral shift / type change

Typed client libraries integrations must be updated to use the new resource namespaces.

youtube_select_lineups field in ReachPlanService.ListPlannableProducts

None

Removal

Switch to using lineups from youtube_select_lineup_targeting.

is_brand_connect_creator field in ContentCreatorInsightsService.GenerateCreatorInsights and GenerateTrendingInsights

None

Removal

Instead, check if a creator has CREATOR_PARTNERSHIPS available in partnership_opportunities.

geo_modifiers and biddable_keywords in KeywordPlanIdeaService.GenerateKeywordForecastMetrics

geo_target_constants and keywords

Rename / removal

Replaced by CampaignToForecast.geo_target_constants[] and ForecastAdGroup.keywords[].

Deprecated keywords plan / forecast fields in GenerateKeywordForecastMetrics

None

Removal

Removed the following plan / forecast fields and types: CampaignToForecast.keyword_plan_network CampaignToForecast.negative_keywords and ForecastAdGroup.negative_keywords ForecastAdGroup.max_cpc_bid_micros BiddableKeyword CriterionBidModifier KeywordForecastMetrics.impressions KeywordForecastMetrics.click_through_rate Update integrations accordingly.

Reports

ad_sub_network_type segment in campaign_budget

None

Removal

Removed ad_sub_network_type segment for the campaign_budget resource.

click_type segment in asset views

None

Removal

Removed segment from AdGroupAsset, CampaignAsset, and CustomerAsset views.

Videos

Partial failure allowed in ShareablePreviewService.GenerateShareablePreviews

No partial failure

Behavioral shift

Requests will fail and throw an error if any ID within it fails validation.

ShareablePreviewError legacy codes: ASSET_GROUP_DOES_NOT_EXIST_UNDER_THIS_CUSTOMER TOO_MANY_ASSET_GROUPS_IN_REQUEST

MutateErrorEnum.RESOURCE_NOT_FOUND ShareablePreviewError.TOO_MANY_RESOURCES_IN_REQUEST

Rename / behavioral shift

Error codes returned for asset groups are modified to align with ad group ad errors. Update validation catch logic.

Features and updates (non-breaking)

Responsive video ads information objects are now mutable.

Added to retrieve travel feed assets attributes (hotel_center_account_id, merchant_center_id, partner_center_id, subset_id, travel_feed_vertical_type).

Allows enabling View-Through Conversion (VTC) Optimization (default false) in Demand Gen and App campaigns.

Enabled gender exclusions for Performance Max campaigns on all Google Ads API versions.

Added new GA4/Firebase conversion action type enums in ConversionActionType: GOOGLE_ANALYTICS_4_GENERATE_LEAD GOOGLE_ANALYTICS_4_QUALIFY_LEAD GOOGLE_ANALYTICS_4_CLOSE_CONVERT_LEAD FIREBASE_ANDROID_GENERATE_LEAD FIREBASE_ANDROID_QUALIFY_LEAD FIREBASE_ANDROID_CLOSE_CONVERT_LEAD FIREBASE_IOS_GENERATE_LEAD FIREBASE_IOS_QUALIFY_LEAD FIREBASE_IOS_CLOSE_CONVERT_LEAD

Returned when attempting to create multiple identical lookalike lists.

Added plannable product description, marketing objective, cost model, and buying method to ProductCoreAttributes under ListPlannableProductsResponse.

Exposes reports segmenting conversions metrics by the specific product sold (brand, etc.) in addition to the clicked product.

Added non-biddable metrics (metrics showing conversions that campaigns are not optimizing for) to all matching resources: all_average_cart_size all_average_order_value_micros all_cost_of_goods_sold_micros all_cross_sell_cost_of_goods_sold_micros all_cross_sell_gross_profit_micros all_cross_sell_revenue_micros all_cross_sell_units_sold all_gross_profit_margin all_gross_profit_micros all_lead_cost_of_goods_sold_micros all_lead_gross_profit_micros all_lead_revenue_micros all_lead_units_sold all_orders all_revenue_micros all_units_sold

Added to ShoppingPerformanceView.

Supported App campaigns inside the ShoppingProduct resource. Note status and issues are not supported.

Introduced filtering using logical set expressions dynamically:

• Added RETAIL_FILTER_BUNDLE and RETAIL_FILTER criterion types.
• Added RETAIL_FILTER shared set type.
• Added the retail_filter_bundle field to AdGroupCriterion.
• Added the retail_filter field to SharedCriterion.
• Added RETAIL to ListingGroupFilterListingSource.
• Added RetailFilter dimension to AssetGroupListingGroupFilter.
• Added related new validation errors in CriterionError and AssetGroupListingGroupFilterError.
• This feature is only available to accounts on the allowlist.

Original source

The following new features and updates were added in Google Ads API v23.2. Minor versions like v23.2 don't contain breaking changes.

Assets

VideoEnhancement

New resource

Contains enhancement-specific video ad information, such as whether it's Google-generated or advertiser-provided. See the About video enhancements to learn more.

AppTopCombinationView

New resource

Read-only resource to provide insights into top-performing asset combinations in App campaigns.

CustomerAsset

New feature

Added support to retrieve CustomerAsset with field_type set to BUSINESS_LOGO.

Campaigns

AdGroupAd.start_date_time AdGroupAd.end_date_time

New fields

Provide more granular scheduling constraints over the campaign's dates. This is only supported for some ad group types.

HotelSettingInfo.disable_hotel_setting

New field

Allows disabling the hotel feed in Demand Gen campaigns.

General

CustomerClientLinkError

New enum values / errors

Added two new error codes: MAX_CUSTOMER_LIMIT_REACHED and ACCOUNT_CREATION_POLICY_VIOLATION.

UserListCustomerTypeCategoryEnum.LOYALTY_SIGN_UPS

Behavioral change

An error is now thrown when attempting to use this sunsetted user list customer type category.

Planning

GenerateTrendingInsights GenerateCreatorInsights

New features

Added support for custom AND/OR combinations of entities, topics, and audiences.

ReachPlanService.GenerateReachForecast

New enum values

Added new targetable age ranges, such as AGE_RANGE_21_44 or AGE_RANGE_21_49.

youtube_select_lineup_targeting

New field

Added to ReachPlanService.ListPlannableProducts, which will replace youtube_select_lineups. Both fields are currently populated.

ReachPlanSurface

New enum value

Added IN_STREAM_NON_SKIPPABLE_THIRTY_SECONDS as a surface option.

Forecast

New field

Added clicks for Demand Gen Max Clicks (CPC) in ReachPlanService.GenerateReachForecast.

partnership_opportunities

New field

Added to ContentCreatorInsightsService.GenerateCreatorInsights and ContentCreatorInsightsService.GenerateTrendingInsights.

Reports

biddable_indirect_install_first_in_app_conversion_micros

New field

Added to Campaign, Customer, and AdGroup resources.

Videos

ShareablePreviewService

New feature

Extended to support YouTube Live previews by setting preview_type to YOUTUBE_LIVE_PREVIEW. Added UNSUPPORTED_AD_TYPE and TOO_MANY_RESOURCES_IN_REQUEST to ShareablePreviewError. This is only supported for some ad types.

Original source

The following new feature was added in Google Ads API v22.1. Minor versions like v22.1 don't contain breaking changes.

Features and updates

• Account management
  • Customer.contains_eu_political_advertising: New field. Retrieves the account-level declaration status of whether it contains political advertising targeted towards the EU, and returns an EuPoliticalAdvertisingStatus.
• Campaigns
  • Campaign.missing_eu_political_advertising_declaration: New field. Supports querying and filtering campaigns that are missing declarations about whether they contain political advertising targeted towards the EU.

Original source