Google Ads API Updates & Release Notes

Features and updates

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, views, etc. 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. The new field parental_statuses has been added to Targeting for service ReachPlanService.GenerateReachForecast, and parental_statuses has been added to PlannableTargeting for service ReachPlanService.ListPlannableProducts.

• Recommendations

  • 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.

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
    • Structural change
    • 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.

• General

  • Nested enum fields in Incentive Service request and response messages: FetchIncentiveRequest.type Incentive.type IncentiveOffer.type
  • Standalone enum fields: FetchIncentiveRequest.incentive_type Incentive.incentive_type IncentiveOffer.offer_type
  • Rename / removal
  • Use the new standalone enum fields instead of the legacy type fields.

• Optional selected_incentive_id and customer_id fields in ApplyIncentiveRequest

  • Required fields
  • 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
  • Behavioral shift
  • 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.

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.

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

Features and updates

• 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.

• Errors

  • 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

  • AdGroup.DemandGenAdGroupSettings.DemandGenChannelControls.DemandGenSelectedChannels.maps: New field. Includes Google Maps in the selectable channels for Demand Gen ad groups.

• Errors

  • 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.

• Errors

  • 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

  • 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.

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.

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.

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

Features and updates

• 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).

• CriterionErrorEnum.CANNOT_TARGET_LANGUAGE

  • New enum value / error
  • Returned when attempting to target a language that is not allowed.

• 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.

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
    • 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
    • Removal
    • The loyalty sign ups user category has been removed. Remove code references to it.
• InsightsAudienceAttributeGroup type for topic_audience_combinations
  • Behavioral shift / type change
  • Typed client libraries integrations must be updated to use the new resource namespaces.
• youtube_select_lineups field in ReachPlanService.ListPlannableProducts
  • Removal
  • Switch to using lineups from youtube_select_lineup_targeting.
• is_brand_connect_creator field in ContentCreatorInsightsService.GenerateCreatorInsights and GenerateTrendingInsights
  • Removal
  • Instead, check if a creator has CREATOR_PARTNERSHIPS available in partnership_opportunities.
• geo_modifiers and biddable_keywords in KeywordPlanIdeaService.GenerateKeywordForecastMetrics
  • Rename / removal
  • Replaced by CampaignToForecast.geo_target_constants[] and ForecastAdGroup.keywords[].
• Deprecated keywords plan / forecast fields in GenerateKeywordForecastMetrics
  • 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.
• ad_sub_network_type segment in campaign_budget
  • Removal
  • Removed ad_sub_network_type segment for the campaign_budget resource.
• click_type segment in asset views
  • Removal
  • Removed segment from AdGroupAsset, CampaignAsset, and CustomerAsset views.
• Partial failure allowed in ShareablePreviewService.GenerateShareablePreviews
  • 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
  • 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)

• Ads
  • AssetAutomationType.GENERATE_ANIMATED_IMAGES_FROM_OTHER_ASSETS
    • New enum value / behavior
    • 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
  • Behavior change
  • Asset.synthetic_content_info and Ad.synthetic_content_info are now fully mutable in v25, v24, and v23.
• Campaigns
  • Loyalty Retention Goal
    • New features / settings
    • 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
    • New features / settings
    • 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
    • New fields
    • 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
    • New field
    • Added to the LocalServicesLead resource.
  • IncentiveError
    • New enum values / errors
    • 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)
  • YouTube channel details in trending insights
    • New fields
    • Added support for more YouTube channel details of related videos when searching trending insights. The new fields channel_id, channel_name, and channel_url have been added to YouTubeVideoAttributeMetadata.
• Reports
  • ad_sub_format_type
    • New segment
    • 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
    • New fields / 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.

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

Features and updates

• 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.
• Conversions
  • ConversionActionCategory.YOUTUBE_FOLLOW_ON_VIEWS
    • New enum value
    • Supports tracking users who watch an ad and later watch a video from the same channel.
• CriterionErrorEnum.CANNOT_TARGET_ONLY_UNDETERMINED
  • New enum value / error
  • Returned when attempting to target only the undetermined category in demographics dimensions.
• Incentives
  • IncentiveErrorEnum
    • New enum values / errors
    • Added two new error codes: MAX_INCENTIVES_REDEEMED and ACCOUNT_TOO_OLD. These errors can be returned for requests made on or after March 11, 2026.
• Planning
  • GenerateBenchmarksMetrics
    • New feature
    • Added support for date breakdowns using a BreakdownDefinition.
  • ReachPlanService.GenerateReachForecast
    • New enum value
    • Added GOOGLE_DISPLAY_NETWORK as a targetable surface for Demand Gen Max Conversions.
  • GenerateTrendingInsights
    • New fields
    • Added historical trend line information in TrendInsightDataPoint to TrendInsights when searching by topic.
• Reports
  • Unique user frequency metrics
    • New fields
    • Added new metrics that report how many users saw your ad at least two, three, four, five or ten times: unique_users_two_plus, unique_users_three_plus, unique_users_four_plus, unique_users_five_plus, and unique_users_ten_plus.
  • SearchTermMatchSource
    • New enum value
    • Added VERTICAL_ADS_DATA_FEED to support vertical ad data feeds, such as Travel Ads entity targeting.
• YouTubeVideoUpload
  • New service / resource
  • Added the YouTubeVideoUpload service to support uploading and managing videos on YouTube, and the YouTubeVideoUpload resource to support fetching upload status and metadata. This feature is only supported for REST and the Python client library.

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.

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

Features and updates include:

• Added Customer.contains_eu_political_advertising field to retrieve account-level declaration status for political advertising targeted towards the EU.
• Added Campaign.missing_eu_political_advertising_declaration field to support querying and filtering campaigns missing declarations about political advertising targeted towards the EU.

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

Features and updates

• Account management
  • advertising_partner_properties.allowed_domain: New field. Added to ProductLinkInvitation and ProductLink resources. The advertising partner will only be able to advertise on this domain.
• 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.text_guidelines: New field. Added support for text guidelines, which can be used with Performance Max and Search campaigns to programmatically control AI-generated text assets. Within text_guidelines, you can define term_exclusions and messaging_restrictions.
  • CampaignPrimaryStatusReason: New enum values. Added CAMPAIGN_NOT_BOOKED, BOOKING_HOLD_EXPIRING, BOOKING_HOLD_EXPIRED, and BOOKING_CANCELLED to provide primary status reasons for campaigns with the FIXED_CPM bidding strategy.
  • Campaign.VideoCampaignSettings.reservation_ad_category_self_disclosure Campaign.VideoCampaignSettings.booking_details: New fields. Added support for reservation ad category self disclosure and read-only booking details.
  • 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.
• Conversions
  • ConversionActionCategory.YOUTUBE_FOLLOW_ON_VIEWS: New enum value. Supports tracking users who watch an ad and later watch a video from the same channel.
• Errors
  • CriterionErrorEnum.CANNOT_TARGET_ONLY_UNDETERMINED: New enum value / error. Returned when attempting to target only the undetermined category in demographics dimensions.
• Incentives
  • IncentiveErrorEnum: New enum values / errors. Added two new error codes: MAX_INCENTIVES_REDEEMED and ACCOUNT_TOO_OLD. These errors can be returned for requests made on or after March 11, 2026.
• Planning
  • GenerateBenchmarksMetrics: New feature. Added support for date breakdowns using a BreakdownDefinition.
  • ReachPlanService.GenerateReachForecast: New enum value. Added GOOGLE_DISPLAY_NETWORK as a targetable surface for Demand Gen Max Conversions.
  • GenerateTrendingInsights: New fields. Added historical trend line information in TrendInsightDataPoint to TrendInsights when searching by topic.
• Reports
  • Unique user frequency metrics: New fields. Added new metrics that report how many users saw your ad at least two, three, four, five or ten times.
• SearchTermMatchSource: New enum value. Added VERTICAL_ADS_DATA_FEED to support vertical ad data feeds, such as Travel Ads entity targeting.
• YouTubeVideoUpload: New service / resource. Added the YouTubeVideoUpload service to support uploading and managing videos on YouTube, and the YouTubeVideoUpload resource to support fetching upload status and metadata. This feature is only supported for REST and the Python client library.

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

See Upgrade to the latest version for guidance.

Breaking changes

• Ads
  • Ad sharing permitted: Behavioral shift. Ad sharing among multiple ad groups is no longer permitted. Requests attempting to share ads will return an AD_SHARING_NOT_ALLOWED error.
• Support for CallAd and CallAdInfo
  • Removal
  • Support for call ads has been removed. Refer to the About call ads help center article.
• Campaigns
  • Campaign.start_date Campaign.end_date
    • Rename / replacement
    • Use the new date-time fields to specify time components for campaigns. The original date-only fields are removed.
• Demand Gen
  • DemandGenMultiAssetAdInfo.lead_form_only
    • Removal
    • The lead_form_only field has been removed. Update references in your code.
• Reports
  • Aggregate asset performance label metrics and enum
    • Removal
    • Removed aggregate asset performance label metrics. The performance label enum is no longer returned for Search and Display.

Features and updates (non-breaking)

• Ads
  • AdFormatType
    • New enum values
    • Added new format types: TEXT, VERTICAL_ADS_BOOKING_LINK, and VERTICAL_ADS_PROMOTION.
• Assets
  • asset_group view
    • New fields
    • Added the following metrics: metrics.engagements, metrics.engagement_rate, and metrics.average_cpe.
  • asset_group_asset view
    • New fields
    • Added the following metrics: metrics.average_cpe, metrics.average_cpm, metrics.trueview_average_cpv, metrics.video_trueview_view_rate, metrics.video_trueview_views, and metrics.interaction_event_types.
  • Asset.orientation
    • New field
    • Read-only orientation field added to image and video assets.
  • CampaignAsset
    • New feature
    • Added support to retrieve campaign assets with field_type set to HEADLINE and DESCRIPTION.
  • ServedAssetFieldType
    • New enum values
    • Added HEADLINE_AS_SITELINK_POSITION_ONE, HEADLINE_AS_SITELINK_POSITION_TWO, DESCRIPTION_LINE_HEADLINE_AS_SITELINK_POSITION_ONE, and DESCRIPTION_LINE_HEADLINE_AS_SITELINK_POSITION_TWO for assets served as sitelinks.
  • BusinessMessageAsset
    • New features / support
    • Updated Business Message assets: Added support for Facebook Messenger and Zalo as providers. Added FACEBOOK_MESSENGER and ZALO to BusinessMessageProvider. Added fields facebook_messenger_info and zalo_info. Added CUSTOMER_NOT_ON_ALLOWLIST_FOR_MESSAGE_ASSETS to AssetError.
• Billing
  • InvoiceService.ListInvoices
    • New options
    • Can now return more granular details in Invoice, including campaign-level cost breakdown, itemized regulatory costs, and adjustment information, by setting include_granular_level_invoice_details in ListInvoicesRequest.
• RegulatoryFeeType UnitOfMeasure
  • New enums
    • Added helper enums for regulatory fees and units of measure.
• Campaigns
  • CampaignError
    • New enum values / errors
    • Added DURATION_TOO_LONG_FOR_TOTAL_BUDGET and END_DATE_TIME_REQUIRED_FOR_TOTAL_BUDGET error codes.
• Conversions
  • ConversionActionCategory.YOUTUBE_FOLLOW_ON_VIEWS
    • New enum value
    • Added YOUTUBE_FOLLOW_ON_VIEWS to support tracking users who watch an ad and later watch a video from the same channel.
• Demand Gen
  • DemandGenVideoResponsiveAdInfo.companion_banner
    • New field
    • Added support for companion banners in Demand Gen responsive video ads.
• Incentives
  • Added Choose Your Own (CYO) incentives support: Added the FetchIncentive method to retrieve available personalized incentives for a user. Added the ApplyIncentive method to apply a selected incentive to a customer account. Added the AppliedIncentive resource (queryable using Search and SearchStream) to provide redemption details. Added new error codes in IncentiveError and AuthenticationError.INVALID_EMAIL_ADDRESS. To facilitate more granular programmatic handling of failures, we will add additional error codes to IncentivesService in future releases. We recommend that you monitor upcoming announcements and release notes for these new error codes to make sure your applications can manage these new failure modes.