Category Archives: Ads Developer Blog

The official blog for information about the AdWords, AdSense, DoubleClick and AdMob APIs and SDKs

Ad Sharing Functionality Will Be Deprecated in Google Ads API in October 2025

What is changing?

Google is deprecating the ad sharing functionality in Google Ads API.

  • With the October 2025 release of v22, the ability to create shared ads will be removed from all supported versions on October 15, 2025.
  • In Q1 2026, shared ads will sunset and stop serving. The exact date isn’t determined, and will be communicated in the future.

This change will affect how ads are created and managed at scale, so it's crucial to understand the implications and prepare your systems accordingly. Let's break down what's happening, why it matters, and what you need to do.

What is Ad Sharing?

In simple terms, "ad sharing" means creating one ad and using that exact same ad in multiple Ad Groups.

Instead of building identical ads over and over for each Ad Group, you build it once and link it everywhere you need it.

Why is this changing?

This change aligns with the movement to Asset-Based Ads. The future of Google Ads is centered around asset-based ad formats like Responsive Search Ads (RSAs) and Performance Max campaigns. In these formats, the "ad" is dynamically assembled from a pool of assets (headlines, descriptions, images), making the concept of a static, shareable ad object less efficient.

How to Prepare

The timeline gives you ample time to adapt, but we strongly recommend starting the process now to avoid any disruption to your advertising operations. Follow these steps to ensure a smooth transition.

Step 1: Audit Your Application

The first step is to determine if your application uses the ad sharing model.

Review your codebase, specifically any logic that interacts with the AdGroupAdService. Look for any instances where you created an AdGroupAd by pointing to an existing ad's resource name that is already in use in another ad group.

Your current, soon-to-be-deprecated logic might look something like this conceptually:

  1. Create an AdGroupAd that contains an Ad.
  2. Create an AdGroup.
  3. Create another AdGroupAd using the embedded Ad from step 1 and the AdGroup from Step 2. (This is the functionality that will be removed).

Step 2: Update Your Ad Creation Logic

You must refactor your code to create a new, unique ad for every ad group. Instead of sharing an ad, your new workflow should be a loop that creates a distinct ad for each target ad group. You will no longer be able to create a standalone ad. Instead, you will specify the ad parameters as part of creating an AdGroup.

The new, compliant logic should look like this:

  1. For AdGroup_1:
    • Create an AdGroupAd using ad for ad_group_1.
  2. For AdGroup_2:
    • Create an AdGroupAd using ad for ad_group_2.

Even if the ad copy is identical, the ads must be created as separate ad objects in the API.

If you still have legacy Expanded Text Ads (ETAs) serving that are shared, you must convert them to Responsive Search Ads and assign each shared instance to a single AdGroup.

Step 3: Understand the Impact on Reporting

When you stop sharing a single ad and start creating unique ads for each ad group, the performance history will be affected.

Important: Performance statistics (impressions, clicks, conversions) are tied to the unique ad. The new ads you create will start with zero performance history. The historical data from your old, shared ads will remain, but it will not be carried over to the new ads.

Be sure to communicate this to your team or clients. Plan to export and archive historical performance data before you make the switch to perform long-term, ad-level analysis.

Migration of Existing Shared Ads

Step 1: Identify Your Shared Ads

First, you need a definitive list of all ads that are currently shared across more than one ad group. 

SELECT
  ad_group_ad.ad.id,  -- This is the unique ID of the 'Ad' itself
  ad_group.id,        -- This is the unique ID of the 'AdGroup'
  ad_group_ad.status,
  ad_group_ad.ad.type,
  campaign.id,
  campaign.name,
  ad_group.name
FROM
  ad_group_ad
WHERE
  ad_group_ad.status IN ('ENABLED', 'PAUSED')
ORDER BY
  ad_group_ad.ad.id, ad_group.id

If you find an ad_group_ad.ad.id in your results whose associated collection of ad_group.ids has more than one entry, it means that specific Ad (identified by ad_group_ad.ad.id) is linked to multiple ad groups (each identified by a unique ad_group.id in the collection).

If any ad_group.id that is associated with more than one distinct ad_group.id, then that Ad is considered "shared".

Step 2: Gather Ad Content and Associated Ad Groups

For each shared Ad you identified in Step 1, you need to retrieve two things:

  1. The content of the ad (its headlines and descriptions).
  2. The list of all ad groups where it is currently active.

Step 3: Create a New, Unique ResponsiveSearchAd in Each Ad Group

For the core of the migration, loop through each ad group you identified in Step 2 and create a new ResponsiveSearchAd inside it.

Best Practice: If your shared ad is an Expanded Text Ad, don't just copy the 3 headlines and 2 descriptions. Use them as a starting point and add more assets. The power of ResponsiveSearchAds comes from having a deep pool of headlines and descriptions for Google to test. Aim for 5 short headlines, 1 long headline, and 5 descriptions.

Here is a quick summary of the ResponsiveSearchAds limits,

Asset Type Maximum Allowed Character Limit Best Practices
Short Headline Up to 5 30 characters Provide all 5
Long Headline 1 90 characters Always provide 1
Description Up to 5 90 characters Provide all 5

Here is a conceptual outline of the mutate operation using AdGroupAdService:

  1. Loop through each ad_group.resource_name from your Step 2 results.
  2. Inside the loop, construct a new AdGroupAd object.
  3. Set the ad_group field to the current ad_group.resource_name.
  4. Create an Ad object within the AdGroupAd.
  5. Populate the responsive_search_ad field with your assets:
    • Create a list of AdTextAsset objects for your headlines.
    • Create a list of AdTextAsset objects for your descriptions.
    • Set the final_urls, path1, and path2 using the data from your old Ad.
  6. Execute the MutateAdGroupAds() request.

This process ensures that each ad group now has its own unique ResponsiveSearchAds, ready to be served.

Step 4: Remove the Old Shared Ads

Once your new ResponsiveSearchAds have been created and have passed the editorial review (status is ENABLED), it's time to retire any shared ads.

  1. Identify the resource name of the old AdGroupAd (the link between the shared ad and the ad group).
  2. Use the AdGroupAdService to perform the mutation. Within this service, you'll construct an AdGroupAdOperation. This operation object has a remove field where you provide the resource name of the AdGroupAd you want to remove.
  3. Finally, you call the mutateAdGroupAds method on the AdGroupAdService.

The Timeline for Phasing Out Shared Ads

We strongly encourage you to manually migrate your shared ads yourself

  • This is the best approach. It allows you to create new ads with unique images and headlines tailored specifically to the audience in each Ad Group. More relevant ads lead to better results.

Phase 1: Starting 15 October 2025

  • You can no longer create new shared ads.
  • Any attempt to link a single ad to a new Ad Group will be blocked and will return an error. If you use automated tools or scripts for this, they will stop working.

Phase 2: Between 15 October 2025 and Q1 2026

  • Your existing shared ads will continue to serve normally.
  • No immediate action is required for ads that are already shared; they will not be affected during this period.

Phase 3: In Q1 2026

  • We will automatically convert all remaining shared ads.
  • For any ads that are still shared, we will create individual copies in each Ad Group they belong to.

We recommend consulting the official Google Ads API documentation and keeping an eye on the Google Ads Developer Blog for further details as the date approaches.

Start your audit today and share this post with your development team to ensure you are prepared for a seamless transition.

Automatic Process in Q1 2026

If you take no action, we will automatically separate your shared ads for you in the first quarter of 2026.

Here’s how our automated process will work:

  • One Ad Group Keeps the Original Ad: Your original ad will be kept in just one of the Ad Groups (specifically, the one with the lowest ad group ID).
  • Other Ad Groups Get Copies: We will create new copies of the original ad for all the other Ad Groups it was shared with.
  • Automated Content Will Be Regenerated: Your settings for features like "asset automation" will be copied. However, the actual machine-generated assets (like automatically created headlines or images) will not be transferred. Our system will create a brand-new set for each copied ad, which may affect initial performance.

If you have any questions, please contact us on the forum.

Bob Hancock, Google Ads API Team

Ad Sharing Functionality Will Be Deprecated in Google Ads API in October 2025

What is changing?

Google is deprecating the ad sharing functionality in Google Ads API.

  • With the October 2025 release of v22, the ability to create shared ads will be removed from all supported versions on October 15, 2025.
  • In Q1 2026, shared ads will sunset and stop serving. The exact date isn’t determined, and will be communicated in the future.

This change will affect how ads are created and managed at scale, so it's crucial to understand the implications and prepare your systems accordingly. Let's break down what's happening, why it matters, and what you need to do.

What is Ad Sharing?

In simple terms, "ad sharing" means creating one ad and using that exact same ad in multiple Ad Groups.

Instead of building identical ads over and over for each Ad Group, you build it once and link it everywhere you need it.

Why is this changing?

This change aligns with the movement to Asset-Based Ads. The future of Google Ads is centered around asset-based ad formats like Responsive Search Ads (RSAs) and Performance Max campaigns. In these formats, the "ad" is dynamically assembled from a pool of assets (headlines, descriptions, images), making the concept of a static, shareable ad object less efficient.

How to Prepare

The timeline gives you ample time to adapt, but we strongly recommend starting the process now to avoid any disruption to your advertising operations. Follow these steps to ensure a smooth transition.

Step 1: Audit Your Application

The first step is to determine if your application uses the ad sharing model.

Review your codebase, specifically any logic that interacts with the AdGroupAdService. Look for any instances where you created an AdGroupAd by pointing to an existing ad's resource name that is already in use in another ad group.

Your current, soon-to-be-deprecated logic might look something like this conceptually:

  1. Create an AdGroupAd that contains an Ad.
  2. Create an AdGroup.
  3. Create another AdGroupAd using the embedded Ad from step 1 and the AdGroup from Step 2. (This is the functionality that will be removed).

Step 2: Update Your Ad Creation Logic

You must refactor your code to create a new, unique ad for every ad group. Instead of sharing an ad, your new workflow should be a loop that creates a distinct ad for each target ad group. You will no longer be able to create a standalone ad. Instead, you will specify the ad parameters as part of creating an AdGroup.

The new, compliant logic should look like this:

  1. For AdGroup_1:
    • Create an AdGroupAd using ad for ad_group_1.
  2. For AdGroup_2:
    • Create an AdGroupAd using ad for ad_group_2.

Even if the ad copy is identical, the ads must be created as separate ad objects in the API.

If you still have legacy Expanded Text Ads (ETAs) serving that are shared, you must convert them to Responsive Search Ads and assign each shared instance to a single AdGroup.

Step 3: Understand the Impact on Reporting

When you stop sharing a single ad and start creating unique ads for each ad group, the performance history will be affected.

Important: Performance statistics (impressions, clicks, conversions) are tied to the unique ad. The new ads you create will start with zero performance history. The historical data from your old, shared ads will remain, but it will not be carried over to the new ads.

Be sure to communicate this to your team or clients. Plan to export and archive historical performance data before you make the switch to perform long-term, ad-level analysis.

Migration of Existing Shared Ads

Step 1: Identify Your Shared Ads

First, you need a definitive list of all ads that are currently shared across more than one ad group. 

SELECT
  ad_group_ad.ad.id,  -- This is the unique ID of the 'Ad' itself
  ad_group.id,        -- This is the unique ID of the 'AdGroup'
  ad_group_ad.status,
  ad_group_ad.ad.type,
  campaign.id,
  campaign.name,
  ad_group.name
FROM
  ad_group_ad
WHERE
  ad_group_ad.status IN ('ENABLED', 'PAUSED')
ORDER BY
  ad_group_ad.ad.id, ad_group.id

If you find an ad_group_ad.ad.id in your results whose associated collection of ad_group.ids has more than one entry, it means that specific Ad (identified by ad_group_ad.ad.id) is linked to multiple ad groups (each identified by a unique ad_group.id in the collection).

If any ad_group.id that is associated with more than one distinct ad_group.id, then that Ad is considered "shared".

Step 2: Gather Ad Content and Associated Ad Groups

For each shared Ad you identified in Step 1, you need to retrieve two things:

  1. The content of the ad (its headlines and descriptions).
  2. The list of all ad groups where it is currently active.

Step 3: Create a New, Unique ResponsiveSearchAd in Each Ad Group

For the core of the migration, loop through each ad group you identified in Step 2 and create a new ResponsiveSearchAd inside it.

Best Practice: If your shared ad is an Expanded Text Ad, don't just copy the 3 headlines and 2 descriptions. Use them as a starting point and add more assets. The power of ResponsiveSearchAds comes from having a deep pool of headlines and descriptions for Google to test. Aim for 5 short headlines, 1 long headline, and 5 descriptions.

Here is a quick summary of the ResponsiveSearchAds limits,

Asset Type Maximum Allowed Character Limit Best Practices
Short Headline Up to 5 30 characters Provide all 5
Long Headline 1 90 characters Always provide 1
Description Up to 5 90 characters Provide all 5

Here is a conceptual outline of the mutate operation using AdGroupAdService:

  1. Loop through each ad_group.resource_name from your Step 2 results.
  2. Inside the loop, construct a new AdGroupAd object.
  3. Set the ad_group field to the current ad_group.resource_name.
  4. Create an Ad object within the AdGroupAd.
  5. Populate the responsive_search_ad field with your assets:
    • Create a list of AdTextAsset objects for your headlines.
    • Create a list of AdTextAsset objects for your descriptions.
    • Set the final_urls, path1, and path2 using the data from your old Ad.
  6. Execute the MutateAdGroupAds() request.

This process ensures that each ad group now has its own unique ResponsiveSearchAds, ready to be served.

Step 4: Remove the Old Shared Ads

Once your new ResponsiveSearchAds have been created and have passed the editorial review (status is ENABLED), it's time to retire any shared ads.

  1. Identify the resource name of the old AdGroupAd (the link between the shared ad and the ad group).
  2. Use the AdGroupAdService to perform the mutation. Within this service, you'll construct an AdGroupAdOperation. This operation object has a remove field where you provide the resource name of the AdGroupAd you want to remove.
  3. Finally, you call the mutateAdGroupAds method on the AdGroupAdService.

The Timeline for Phasing Out Shared Ads

We strongly encourage you to manually migrate your shared ads yourself

  • This is the best approach. It allows you to create new ads with unique images and headlines tailored specifically to the audience in each Ad Group. More relevant ads lead to better results.

Phase 1: Starting 15 October 2025

  • You can no longer create new shared ads.
  • Any attempt to link a single ad to a new Ad Group will be blocked and will return an error. If you use automated tools or scripts for this, they will stop working.

Phase 2: Between 15 October 2025 and Q1 2026

  • Your existing shared ads will continue to serve normally.
  • No immediate action is required for ads that are already shared; they will not be affected during this period.

Phase 3: In Q1 2026

  • We will automatically convert all remaining shared ads.
  • For any ads that are still shared, we will create individual copies in each Ad Group they belong to.

We recommend consulting the official Google Ads API documentation and keeping an eye on the Google Ads Developer Blog for further details as the date approaches.

Start your audit today and share this post with your development team to ensure you are prepared for a seamless transition.

Automatic Process in Q1 2026

If you take no action, we will automatically separate your shared ads for you in the first quarter of 2026.

Here’s how our automated process will work:

  • One Ad Group Keeps the Original Ad: Your original ad will be kept in just one of the Ad Groups (specifically, the one with the lowest ad group ID).
  • Other Ad Groups Get Copies: We will create new copies of the original ad for all the other Ad Groups it was shared with.
  • Automated Content Will Be Regenerated: Your settings for features like "asset automation" will be copied. However, the actual machine-generated assets (like automatically created headlines or images) will not be transferred. Our system will create a brand-new set for each copied ad, which may affect initial performance.

If you have any questions, please contact us on the forum.

Bob Hancock, Google Ads API Team

Join our “Google Advertising and Measurement Community” Discord Server

We’re launching our new “Google Advertising and Measurement Community” Discord server! To join, just click this invite link and follow the onboarding guide.

The current products available on this server are Analytics, Google Ads, Google AdMob, and Google Ad Manager.

The Ads Developer Relations team will be on this server regularly to discuss your feedback or questions using Google’s Advertising and Analytics APIs/SDKs, as well as to let you know what’s new with our products.

We’ll be hosting a “Meet the Team” in August, where we’ll go over who we are, and how you can expect to engage with us in Discord. Stay tuned as we add other events, and more channels.

Looking forward to chatting with you on Discord!

- Cory Liseno, on behalf of the Ads Developer Relations Team

Help shape Google Ads API’s future Model Context Protocol (MCP) Server

The Google Ads API team is exploring bringing a Model Context Protocol Server to the developer base to allow third-party GenAI tools to work with advertiser accounts. We are seeking your initial input to help us shape our roadmap.

If you are interested in providing feedback in relation to this topic please follow this link to participate in a short survey.

How to get help

If you have any questions or need help, check out the Google Ads API support page for options.

 - David Stevens, Google Ads API Product Manager/span>

Upcoming changes to Search and SearchStream responses in Google Ads API

What’s changing?

Last year, we introduced query_resource_consumption metric as a way to measure how expensive a Google Ads API query is. However, this cost was not returned when the query results were empty.

Starting the week of August 4, 2025, we will modify the behavior of both the Search and SearchStream methods of GoogleAdsService in all the API versions to return the query_resource_consumption metric and the field_mask field even when the query results are empty. The responses for empty query results will change as follows:

Method Old response New response
Search 
{    
    "fieldMask": "..."     
}
 
{
    "fieldMask": "...",
    "query_resource_consumption": 123
}
SearchStream 
[]
 
{
    "fieldMask": "...",
    "queryResourceConsumption": 206
}

What do I need to do?

If you are using Search and SearchStream methods to download Google Ads API reports, make sure your application can handle the modified response.

If you have any questions or need help, check out the Google Ads API support page for options.

Reach out to the Google Ads product support team for any questions related to account policies.

 - , Google Ads API Team

[Update] Add Conversion Environment to Google Ads Conversion Imports

Previously we announced that, starting on June 30, 2025, in-app conversions imported through the Google Ads API must include a value for the ClickConversion.conversion_environment field. The timing and details for this rollout have changed.

Now, starting September 30, 2025, we will begin gradually rolling out a change to our bidding models so that they will start using the presence of the ClickConversion.conversion_environment field in imported in-app conversions to ensure accurate attribution for smarter bidding and optimal campaign performance. This means that if you are using the Google Ads API to measure in-app conversions, your campaign performance may degrade if the ClickConversion.conversion_environment field is not set.

For developers importing in-app conversions, the following considerations still apply:

  1. In-app conversions are defined as any conversion events that occur within an app, such as purchase, add to cart, or sign up.
  2. Once this bidding model change is launched to a campaign, if you do not include the conversion_environment field when importing conversions, you may observe fewer in-app conversions and worse overall campaign performance.
  3. If you do include conversion_environment data for your imported conversions, it ensures attribution accuracy and campaign effectiveness.
  4. The presence or absence of the conversion_environment parameter does not impact conversion uploads. These conversions will still be consumed and reported, with no error messages.

If you have any questions or need help, see the Google Ads API support page for options.

- Ben Karl, on behalf of the Google Ads API Team

Upcoming Removal of debug_enabled in Google Ads API Offline Conversion Imports

In v21 of the Google Ads API, the UploadClickConversion method’s debug_enabled setting will be removed. Starting on August 6, 2025, all the previous versions (v18, v19, and v20) will ignore this setting if it’s set as part of a request.

As a result of this change, Google Ads API will no longer return ConversionUploadError.CLICK_NOT_FOUND errors, because setting the debug_enabled field to true is the only way to retrieve it. This error code will be removed from the Google Ads API in a future version.

Here’s a breakdown of how this change will materialize in each Google Ads API version:

If your application uses this field or error code, make sure you update your application to handle the new API behavior.

If you have any questions or need help, check out the Google Ads API support page for options.

- Ben Karl, on behalf of the Google Ads API Team

Google Ads Scripts Sunsetting Ad Customizers for Expanded Text Ads and Legacy Ad Extension Entities Starting July 14, 2025

Starting July 14, 2025, Google Ads scripts will begin to throw errors for requests related to ad customizers for expanded text ads and feed-based legacy ad extensions.

Ad customizer changes

Any requests related to Ad Customizer entities, such as AdsApp.AdCustomizerSource or AdsApp.newAdCustomizerSourceBuilder, will begin to return sunset errors. These entities have been read-only since deprecation in 2022 and haven’t been served on any ads since May 2024. They were also fully removed from the Google Ads API in the v19 release.

Ad extension changes

Feed-based Ad Extensions were sunset in 2022 in favor of asset-based extensions. Users were asked to migrate, or were migrated automatically, but were able to access legacy functionality through the withOnlyLegacy() methods on various selectors. The withOnlyUpgraded() method was added to allow users to only use upgraded asset-based extensions. Starting July 14, 2025, the legacy functionality will be removed, and withOnlyLegacy() methods will begin to throw a sunset error. The withOnlyUpgraded() methods will log a warning, since it will no longer be necessary to specify the use of asset-based extensions when they are the only option.

If you have any questions, ask them in the Google Ads scripts forum. We're here to help!

 - Dora Sun - Google Ads API Team

Announcing v20 of the Google Ads API

Today, we’re announcing the v20 release of the Google Ads API. To use some of the v20 features, you must upgrade your client libraries and client code. The updated client libraries and code examples will be published next week.

Here are the highlights:
  • You can now add campaign level negative keywords to your Performance Max campaigns.
  • Report segmentation by ad_network_type for Demand Gen campaigns is now more granular, and is split between YOUTUBE, MAPS, DISCOVER and GMAIL instead of aggregating all data under the GOOGLE_OWNED_NETWORKS segment.
  • Demand Gen campaigns now support the platform comparable conversions measurement in the API.
  • Gain deeper insights into YouTube Select Lineups, now accessible through a new dimension in the AudienceInsightsService. This feature is only available to accounts on an allowlist.
  • Target your reach forecasts more effectively with the ability to plan based on your own first-party user lists. Reach forecasting is available to allowlisted accounts only.
  • Analyze your audience data with greater precision using new device segmentation, additional video metrics, and the ability to refine searches by sub-country locations. See Planning in the release notes for more details. This feature is only available to accounts on an allowlist.
Where can I learn more?
The following resources can help you get started: If you have any questions or need additional help, contact us via the forum.
 - , Google Ads API Team

Announcing v20 of the Google Ads API

Today, we’re announcing the v20 release of the Google Ads API. To use some of the v20 features, you must upgrade your client libraries and client code. The updated client libraries and code examples will be published next week.

Here are the highlights:
  • You can now add campaign level negative keywords to your Performance Max campaigns.
  • Report segmentation by ad_network_type for Demand Gen campaigns is now more granular, and is split between YOUTUBE, MAPS, DISCOVER and GMAIL instead of aggregating all data under the GOOGLE_OWNED_NETWORKS segment.
  • Demand Gen campaigns now support the platform comparable conversions measurement in the API.
  • Gain deeper insights into YouTube Select Lineups, now accessible through a new dimension in the AudienceInsightsService. This feature is only available to accounts on an allowlist.
  • Target your reach forecasts more effectively with the ability to plan based on your own first-party user lists. Reach forecasting is available to allowlisted accounts only.
  • Analyze your audience data with greater precision using new device segmentation, additional video metrics, and the ability to refine searches by sub-country locations. See Planning in the release notes for more details. This feature is only available to accounts on an allowlist.
Where can I learn more?
The following resources can help you get started: If you have any questions or need additional help, contact us via the forum.
 - , Google Ads API Team